OpenRouter

OpenRouter یک API یکپارچه ارائه می‌دهد که درخواست‌ها را از طریق یک endpoint و کلید API واحد به مدل‌های بسیاری هدایت می‌کند. این سرویس با OpenAI سازگار است، بنابراین بیشتر OpenAI SDKها با تغییر base 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" },    },  },}

ارجاع‌های مدل

نمونه‌های fallback همراه:

تولید تصویر

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 درخواست‌های تصویر را با modalities: ["image", "text"] به API تصویر تکمیل‌های چت OpenRouter می‌فرستد. مدل‌های تصویر Gemini راهنمایی‌های پشتیبانی‌شده aspectRatio و resolution را از طریق image_config در OpenRouter دریافت می‌کنند. برای مدل‌های تصویر کندتر OpenRouter از agents.defaults.imageGenerationModel.timeoutMs استفاده کنید؛ پارامتر timeoutMs در هر فراخوانی ابزار image_generate همچنان اولویت دارد.

تولید ویدیو

OpenRouter می‌تواند از طریق API ناهمگام /videos خود پشتوانه ابزار video_generate نیز باشد. از یک مدل ویدیوی 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 یا endpoint مستندشده محتوای کار دانلود می‌کند. تصاویر مرجع به‌طور پیش‌فرض به‌عنوان تصاویر فریم اول/آخر ارسال می‌شوند؛ تصاویر دارای برچسب 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"] را می‌فرستد، streaming را فعال می‌کند، قطعه‌های صوتی streamشده را جمع‌آوری می‌کند و نتیجه را به‌عنوان رسانه تولیدشده برای تحویل در کانال ذخیره می‌کند. تصاویر مرجع برای مدل‌های Lyria از طریق پارامتر مشترک music_generate image=... پذیرفته می‌شوند.

متن-به-گفتار

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

{  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 و با استفاده از endpoint STT خود (/audio/transcriptions) رونویسی کند. این برای هر Plugin کانالی اعمال می‌شود که صدا/voice ورودی را به پیش‌بررسی فهم رسانه ارسال می‌کند.

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

OpenClaw درخواست‌های STT OpenRouter را به‌صورت JSON با صدای base64 در input_audio (قرارداد STT در OpenRouter) ارسال می‌کند، نه به‌صورت بارگذاری‌های فرم چندبخشی OpenAI.

مسیریاب Fusion

وقتی می‌خواهید یک ارجاع مدل OpenClaw از چندین مدل OpenRouter به‌صورت موازی بپرسد، OpenRouter پاسخ‌های آن‌ها را داوری کند و یک پاسخ نهایی واحد را از طریق endpoint عادی ارائه‌دهنده OpenRouter برگرداند، از OpenRouter Fusion استفاده کنید. چون slug مدل بالادستی openrouter/fusion است، ارجاع مدل OpenClaw هم پیشوند ارائه‌دهنده OpenClaw و هم namespace بالادستی OpenRouter را شامل می‌شود:

openclaw models set openrouter/openrouter/fusion

پنل و داور Fusion را از طریق params.extraBody مدل پیکربندی کنید. این فیلدها به بدنه درخواست chat-completions در OpenRouter فرستاده می‌شوند. Fusion هم با راه‌اندازی OAuth در OpenRouter و هم با راه‌اندازی کلید 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 مدل داور است. در نوبت‌های عادی agent/chat در OpenClaw، مقدار سطح بالای tool_choice را برای تلاش جهت اجبار Fusion روی "required" تنظیم نکنید؛ نوبت‌های OpenClaw ممکن است شامل تعریف ابزارهای OpenClaw باشند، و انتخاب اجباری ابزار در سطح بالا می‌تواند به‌جای مسیریاب Fusion یکی از همان ابزارها را الزام کند. وقتی این پیکربندی Plugin Fusion وجود داشته باشد، OpenClaw همچنین یک یادداشت system-prompt پاک‌سازی‌شده با مدل‌های تحلیل و مدل داور پیکربندی‌شده اضافه می‌کند تا agent بتواند به پرسش‌ها درباره پنل Fusion فعلی خود پاسخ دهد. فیلدهای دیگر extraBody در prompt کپی نمی‌شوند.

Fusion عمدا کندتر است. OpenRouter ممکن است همان prompt OpenClaw را به چندین مدل تحلیل بفرستد و سپس یک مرحله نهایی داوری/ترکیب اجرا کند، بنابراین تاخیر معمولا از یک درخواست مستقیم تک‌مدلی بیشتر است. از Fusion برای پاسخ‌های سنجیده و باکیفیت یا مسیرهای escalation استفاده کنید، نه به‌عنوان پیش‌فرض برای چت حساس به تاخیر. برای پاسخ‌های سریع‌تر، پنل را کوچک نگه دارید و مدل‌های تحلیل و داوری سریع‌تر انتخاب کنید.

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

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

احراز هویت و headerها

OpenRouter در پشت صحنه از یک Bearer token همراه با کلید API شما استفاده می‌کند. OpenRouter OAuth یک جریان ورود PKCE است که یک کلید API برای OpenRouter صادر می‌کند، بنابراین OpenClaw نتیجه را به‌عنوان همان پروفایل احراز هویت کلید API با نام openrouter:default ذخیره می‌کند که در مسیر راه‌اندازی دستی با کلید API استفاده می‌شود.

برای یک نصب موجود، بدون اجرای دوباره راه‌اندازی کامل، وارد شوید یا کلید ذخیره‌شده OpenRouter را rotate کنید:

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

وقتی می‌خواهید کلیدی را که به‌صورت دستی در OpenRouter ساخته‌اید بچسبانید، از openclaw models auth login --provider openrouter --method api-key استفاده کنید.

در درخواست‌های واقعی OpenRouter (https://openrouter.ai/api/v1)، OpenClaw همچنین headerهای مستندشده انتساب برنامه در 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,            },          },        },      },    },  },}

مرتبط