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.mediaModels.image تنظیم کنید:

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

OpenClaw درخواست‌های تصویر را با modalities: ["image", "text"] به API تصویر تکمیل‌های گفت‌وگوی OpenRouter ارسال می‌کند. مدل‌های تصویر Gemini علاوه بر این، راهنمایی‌های aspectRatio و resolution را از طریق image_config متعلق به OpenRouter دریافت می‌کنند؛ سایر مدل‌های تصویر چنین راهنمایی‌هایی دریافت نمی‌کنند. برای مدل‌های کندتر از agents.defaults.mediaModels.image.timeoutMs استفاده کنید؛ مقدار timeoutMs در هر فراخوانی ابزار image_generate همچنان اولویت دارد.

تولید ویدئو

OpenRouter می‌تواند از طریق API ناهمگام /videos خود، پشتیبان ابزار video_generate باشد. یک مدل ویدئوی OpenRouter را در agents.defaults.mediaModels.video تنظیم کنید:

{  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.mediaModels.music تنظیم کنید:

{  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 MB است).

تبدیل متن به گفتار

OpenRouter می‌تواند از طریق endpoint سازگار با OpenAI خود با نام /audio/speech به‌عنوان ارائه‌دهنده TTS عمل کند.

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

اگر tts.providers.openrouter.apiKey حذف شود، TTS ابتدا به models.providers.openrouter.apiKey و سپس به OPENROUTER_API_KEY برمی‌گردد.

تبدیل گفتار به متن (صدای ورودی)

OpenRouter می‌تواند پیوست‌های صوتی/صدای ورودی را از طریق مسیر مشترک tools.media.audio و با استفاده از endpoint تبدیل گفتار به متن خود (/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 می‌خواهد پاسخ‌های آن‌ها را داوری کند و یک پاسخ نهایی را از طریق endpoint معمول 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، مدل داور است. برای وادارکردن Fusion، در نوبت‌های عادی عامل/چت tool_choice سطح بالا را روی "required" تنظیم نکنید: نوبت‌های OpenClaw می‌توانند شامل تعریف ابزارهای خود باشند و انتخاب اجباری ابزار در سطح بالا ممکن است به‌جای مسیریاب Fusion یکی از آن‌ها را انتخاب کند. وقتی این پیکربندی Plugin مربوط به Fusion وجود داشته باشد، OpenClaw یادداشتی پالایش‌شده به اعلان سیستم اضافه می‌کند که مدل‌های تحلیل پیکربندی‌شده و مدل داور را فهرست می‌کند تا عامل بتواند به پرسش‌های مربوط به پنل Fusion خودش پاسخ دهد. سایر فیلدهای extraBody در اعلان کپی نمی‌شوند.

Fusion بنا به طراحی کندتر است: OpenRouter اعلان را به چند مدل تحلیل ارسال می‌کند و سپس مرحله داوری/ترکیب را اجرا می‌کند؛ بنابراین تأخیر از یک درخواست مستقیم تک‌مدلی بیشتر است. از آن برای پاسخ‌های سنجیده و باکیفیت یا مسیرهای ارجاع استفاده کنید، نه به‌عنوان پیش‌فرضی حساس به تأخیر. برای دریافت پاسخ‌های سریع‌تر، پنل را کوچک نگه دارید و مدل‌های تحلیل/داور سریع‌تری انتخاب کنید.

یک ارجاع پیکربندی‌شده را با یک فراخوانی محلی یک‌باره آزمایش کنید:

openclaw infer model run --local \  --model openrouter/openrouter/fusion \  --prompt "دقیقاً با این عبارت پاسخ دهید: 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,            },          },        },      },    },  },}

مرتبط