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 درخواست‌های تصویر را با modalities: ["image", "text"] به API تصویر تکمیل گفت‌وگوی OpenRouter ارسال می‌کند. مدل‌های تصویر Gemini همچنین راهنمایی‌های aspectRatio و resolution را از طریق image_config در 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 کارهای تبدیل متن به ویدئو و تصویر به ویدئو را ارسال می‌کند، نشانی polling_url بازگردانده‌شده را به‌طور دوره‌ای بررسی می‌کند و ویدئوی نهایی را از unsigned_urls در OpenRouter یا نقطه پایانی محتوای کار دانلود می‌کند. تصاویر مرجع به‌طور پیش‌فرض به‌عنوان تصاویر فریم اول/آخر استفاده می‌شوند؛ تصاویری که با reference_image برچسب‌گذاری شده‌اند، در عوض به‌عنوان مراجع ورودی ارسال می‌شوند. پیش‌فرض همراه google/veo-3.1-fast از مدت‌زمان‌های ۴/۶/۸ ثانیه، وضوح‌های 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 محدود می‌شوند (سقف پیش‌فرض صوت ۱۶ مگابایت است).

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

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

{  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

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، مدل داور است. در نوبت‌های عادی عامل/گفت‌وگو، برای وادار کردن Fusion، مقدار سطح‌بالای tool_choice را روی "required" تنظیم نکنید: نوبت‌های 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,            },          },        },      },    },  },}

مرتبط