OpenRouter

OpenRouter يوفّر API موحّدة توجّه الطلبات إلى نماذج كثيرة خلف نقطة نهاية ومفتاح API واحدين. وهو متوافق مع OpenAI، لذلك تعمل معظم حِزم OpenAI SDK عبر تبديل عنوان URL الأساسي.

البدء

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

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

يمكن أيضًا استخدام 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، فستعيد TTS استخدام 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 STT بصيغة JSON مع صوت base64 ضمن input_audio (عقد OpenRouter STT)، وليس كعمليات رفع نماذج OpenAI متعددة الأجزاء.

موجّه Fusion

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

openclaw models set openrouter/openrouter/fusion

اضبط لوحة Fusion والحَكَم من خلال params.extraBody الخاصة بالنموذج. تُمرَّر هذه الحقول إلى جسم طلب إكمالات المحادثة في OpenRouter. يعمل Fusion مع إعداد OpenRouter عبر 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" في دورات وكيل/محادثة OpenClaw العادية لمحاولة فرض Fusion؛ قد تتضمن دورات OpenClaw تعريفات أدوات OpenClaw، ويمكن لاختيار أداة مطلوب على المستوى الأعلى أن يتطلب واحدة من تلك الأدوات بدلًا من موجّه Fusion. عند وجود إعدادات Plugin Fusion هذه، يضيف OpenClaw أيضًا ملاحظة مهيأة في موجّه النظام تتضمن نماذج التحليل ونموذج الحَكَم المضبوطة حتى يتمكن الوكيل من الإجابة عن الأسئلة حول لوحة Fusion الحالية لديه. لا تُنسخ حقول extraBody الأخرى إلى الموجّه.

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

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

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

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

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

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

openclaw models auth login --provider openrouter --method oauth

استخدم openclaw models auth login --provider openrouter --method api-key عندما تريد لصق مفتاح أنشأته يدويًا في OpenRouter.

في طلبات 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,            },          },        },      },    },  },}

ذو صلة