OpenRouter

يوجّه OpenRouter الطلبات إلى نماذج عديدة من خلال واجهة API واحدة ومفتاح واحد. وهو متوافق مع OpenAI، لذلك يتواصل OpenClaw معه عبر آلية النقل نفسها بنمط openai-completions المستخدمة مع موفّري الوكيل الآخرين.

بدء الاستخدام

openclaw onboard --auth-choice openrouter-oauth

openclaw models set openrouter/<provider>/<model>

openclaw onboard --auth-choice openrouter-api-key

openclaw models set openrouter/<provider>/<model>

مثال على الإعداد

{  env: { OPENROUTER_API_KEY: "sk-or-..." },  agents: {    defaults: {      model: { primary: "openrouter/auto" },    },  },}

مراجع النماذج

نماذج الرجوع الاحتياطية المضمّنة، والمستخدمة عند تعذّر الاكتشاف المباشر للكتالوج:

يُحلّ أي مرجع آخر بصيغة openrouter/<provider>/<model>، بما في ذلك openrouter/openrouter/fusion (راجع موجّه Fusion)، ديناميكيًا بالاستناد إلى كتالوج النماذج المباشر في OpenRouter.

توليد الصور

يمكن لـ OpenRouter دعم أداة image_generate. عيّن نموذج صور من OpenRouter ضمن agents.defaults.imageGenerationModel:

{  env: { OPENROUTER_API_KEY: "sk-or-..." },  agents: {    defaults: {      imageGenerationModel: {        primary: "openrouter/google/gemini-3.1-flash-image-preview",        timeoutMs: 180_000,      },    },  },}

يرسل OpenClaw طلبات الصور إلى واجهة API للصور القائمة على إكمالات المحادثة في OpenRouter مع modalities: ["image", "text"]. تتلقى نماذج صور Gemini أيضًا تلميحات aspectRatio وresolution عبر image_config الخاص بـ OpenRouter؛ أما نماذج الصور الأخرى فلا تتلقاها. استخدم agents.defaults.imageGenerationModel.timeoutMs للنماذج الأبطأ؛ وتظل قيمة timeoutMs الخاصة بكل استدعاء لأداة image_generate هي المقدَّمة.

توليد الفيديو

يمكن لـ OpenRouter دعم أداة video_generate عبر واجهة API غير المتزامنة /videos. عيّن نموذج فيديو من OpenRouter ضمن agents.defaults.videoGenerationModel:

{  env: { OPENROUTER_API_KEY: "sk-or-..." },  agents: {    defaults: {      videoGenerationModel: {        primary: "openrouter/google/veo-3.1-fast",      },    },  },}

يرسل OpenClaw مهام تحويل النص إلى فيديو والصورة إلى فيديو، ويستطلع polling_url المُعاد، ثم ينزّل الفيديو المكتمل من unsigned_urls في OpenRouter أو من نقطة نهاية محتوى المهمة. تُستخدم الصور المرجعية افتراضيًا كصور للإطار الأول/الأخير؛ أما الصور الموسومة بـ reference_image فتُرسل كمراجع إدخال بدلًا من ذلك. يدعم النموذج الافتراضي المضمّن google/veo-3.1-fast مددًا قدرها 4/6/8 ثوانٍ، ودقتي 720P و1080P، ونسبتي عرض إلى ارتفاع 16:9 و9:16. تحويل الفيديو إلى فيديو غير مدعوم: لا تقبل واجهة API المصدرية إلا مراجع النصوص والصور.

توليد الموسيقى

يمكن لـ OpenRouter دعم أداة music_generate من خلال إخراج الصوت في إكمالات المحادثة. عيّن نموذج صوت من OpenRouter ضمن agents.defaults.musicGenerationModel:

{  env: { OPENROUTER_API_KEY: "sk-or-..." },  agents: {    defaults: {      musicGenerationModel: {        primary: "openrouter/google/lyria-3-pro-preview",        timeoutMs: 180_000,      },    },  },}

يستخدم موفّر الموسيقى المضمّن في OpenRouter النموذج google/lyria-3-pro-preview افتراضيًا، ويتيح أيضًا google/lyria-3-clip-preview. يرسل OpenClaw ‏modalities: ["text", "audio"]، ويبث الاستجابة، ويجمع مقاطع الصوت، ويحفظ النتيجة كوسائط مولّدة لتسليمها عبر القناة. تقبل نماذج Lyria صورة مرجعية واحدة من خلال المعامل المشترك music_generate image=.... يُحدّ الصوت المتدفق، والاحتفاظ بالنص المنسوخ، وغلاف أحداث SSE المشتق بواسطة agents.defaults.mediaMaxMb (الحد الافتراضي للصوت هو 16 ميغابايت).

تحويل النص إلى كلام

يمكن أن يعمل OpenRouter كمزوّد لتحويل النص إلى كلام (TTS) من خلال نقطة النهاية المتوافقة مع OpenAI /audio/speech.

{  messages: {    tts: {      auto: "always",      provider: "openrouter",      providers: {        openrouter: {          model: "hexgrad/kokoro-82m",          speakerVoice: "af_alloy",          responseFormat: "mp3",        },      },    },  },}

إذا حُذف messages.tts.providers.openrouter.apiKey، فسيعود تحويل النص إلى كلام احتياطيًا إلى models.providers.openrouter.apiKey، ثم إلى OPENROUTER_API_KEY.

تحويل الكلام إلى نص (الصوت الوارد)

يمكن لـ OpenRouter نسخ مرفقات الصوت/الرسائل الصوتية الواردة من خلال المسار المشترك tools.media.audio، باستخدام نقطة نهاية تحويل الكلام إلى نص (STT) الخاصة به (/audio/transcriptions). ينطبق ذلك على أي Plugin قناة يمرّر الصوت/الرسائل الصوتية الواردة إلى الفحص التمهيدي لفهم الوسائط.

{  tools: {    media: {      audio: {        enabled: true,        models: [{ provider: "openrouter", model: "openai/whisper-large-v3-turbo" }],      },    },  },}

يرسل OpenClaw طلبات تحويل الكلام إلى نص في OpenRouter بصيغة JSON مع صوت مشفّر بـ base64 ضمن input_audio (وفق عقد تحويل الكلام إلى نص الخاص بـ OpenRouter)، وليس كعمليات رفع لنماذج OpenAI متعددة الأجزاء.

موجّه Fusion

يرسل OpenRouter Fusion مرجع نموذج واحدًا من OpenClaw إلى عدة نماذج OpenRouter بالتوازي، ويجعل OpenRouter يحكم على إجاباتها، ثم يعيد استجابة نهائية واحدة من خلال نقطة نهاية OpenRouter المعتادة. معرّف النموذج في المصدر الأعلى هو openrouter/fusion، ولذلك يحمل مرجع نموذج OpenClaw كلًا من بادئة مزوّد OpenClaw ونطاق أسماء OpenRouter في المصدر الأعلى:

openclaw models set openrouter/openrouter/fusion

اضبط لجنة Fusion ونموذج التحكيم من خلال params.extraBody الخاص بالنموذج؛ تُمرّر هذه الحقول مباشرةً إلى متن طلب إكمالات المحادثة في OpenRouter. يعمل Fusion مع الإعداد الأولي عبر OAuth أو مفتاح API؛ وإذا كنت تستخدم OAuth، فاحذف سطر env.OPENROUTER_API_KEY أدناه.

{  env: { OPENROUTER_API_KEY: "sk-or-..." },  agents: {    defaults: {      model: { primary: "openrouter/openrouter/fusion" },      models: {        "openrouter/openrouter/fusion": {          params: {            extraBody: {              plugins: [                {                  id: "fusion",                  analysis_models: [                    "google/gemini-3.5-flash",                    "moonshotai/kimi-k2.6",                    "deepseek/deepseek-v4-pro",                  ],                  model: "google/gemini-3.5-flash",                },              ],            },          },        },      },    },  },}

تمثّل analysis_models اللجنة المتوازية؛ أما model داخل إعدادات Plugin الخاص بـ Fusion فهو نموذج التحكيم. لا تضبط tool_choice في المستوى الأعلى على "required" في أدوار الوكيل/المحادثة المعتادة لمحاولة فرض Fusion؛ إذ قد تتضمن أدوار OpenClaw تعريفات أدواته الخاصة، وقد يؤدي فرض اختيار أداة في المستوى الأعلى إلى اختيار إحدى تلك الأدوات بدلًا من موجّه Fusion. عند وجود إعداد Plugin الخاص بـ Fusion هذا، يضيف OpenClaw ملاحظة منقّحة إلى موجّه النظام تسرد نماذج التحليل المضبوطة ونموذج التحكيم، بحيث يستطيع الوكيل الإجابة عن الأسئلة المتعلقة بلجنة Fusion الخاصة به. لا تُنسخ حقول extraBody الأخرى إلى الموجّه.

يكون Fusion أبطأ حسب التصميم: يوزّع OpenRouter الموجّه على عدة نماذج تحليل، ثم ينفّذ خطوة تحكيم/توليف، ولذلك يكون زمن الاستجابة أعلى من طلب مباشر إلى نموذج واحد. استخدمه للحصول على إجابات متأنية وعالية الجودة أو في مسارات التصعيد، وليس كخيار افتراضي حساس لزمن الاستجابة. أبقِ اللجنة صغيرة واختر نماذج تحليل وتحكيم أسرع للحصول على استجابات أسرع.

اختبر مرجعًا مضبوطًا باستدعاء محلي لمرة واحدة:

openclaw infer model run --local \  --model openrouter/openrouter/fusion \  --prompt "Reply with exactly: FUSION_OK" \  --json

المصادقة والترويسات

يستخدم OpenRouter رمز Bearer من مفتاح API الخاص بك. يمثّل OAuth في OpenRouter تدفق تسجيل دخول باستخدام PKCE يُصدر مفتاح API لـ OpenRouter، ولذلك يخزّن OpenClaw النتيجة في ملف تعريف مصادقة مفتاح API نفسه openrouter:default المستخدم عند الإعداد اليدوي لمفتاح API.

لتسجيل الدخول أو تدوير المفتاح المخزّن في تثبيت حالي من دون إعادة تشغيل الإعداد الأولي الكامل:

openclaw models auth login --provider openrouter --method oauthopenclaw models auth login --provider openrouter --method api-key

في طلبات OpenRouter الموثّقة (https://openrouter.ai/api/v1)، يضيف OpenClaw ترويسات إسناد التطبيق الموثّقة في OpenRouter:

الإعدادات المتقدمة

{  agents: {    defaults: {      models: {        "openrouter/auto": {          params: {            responseCache: true,            responseCacheTtlSeconds: 300,          },        },      },    },  },}

{  models: {    providers: {      openrouter: {        params: {          provider: {            sort: "latency",            require_parameters: true,            data_collection: "deny",          },        },      },    },  },}

{  agents: {    defaults: {      models: {        "openrouter/anthropic/claude-sonnet-4-6": {          params: {            provider: {              order: ["anthropic"],              allow_fallbacks: false,            },          },        },      },    },  },}

ذو صلة