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 工具的後端。請在 agents.defaults.imageGenerationModel 下設定 OpenRouter 圖片模型：

{  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"]，將圖片請求傳送至 OpenRouter 的聊天補全圖片 API。Gemini 圖片模型還會透過 OpenRouter 的 image_config 接收 aspectRatio 和 resolution 提示；其他圖片模型則不會。 對於速度較慢的模型，請使用 agents.defaults.imageGenerationModel.timeoutMs； 但 image_generate 工具每次呼叫的 timeoutMs 仍具有較高優先順序。

影片生成

OpenRouter 可透過其非同步 /videos API，作為 video_generate 工具的後端。 請在 agents.defaults.videoGenerationModel 下設定 OpenRouter 影片模型：

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

OpenClaw 會提交文字轉影片和圖片轉影片工作，輪詢傳回的 polling_url，並從 OpenRouter 的 unsigned_urls 或工作內容端點下載完成的影片。 參考圖片預設作為首格／末格圖片；標記為 reference_image 的圖片則會改為作為輸入參照傳送。 內建的 google/veo-3.1-fast 預設模型支援 4／6／8 秒的影片長度、 720P／1080P 解析度，以及 16:9／9:16 長寬比。 不支援影片轉影片：上游 API 僅接受文字與圖片參照。

音樂生成

OpenRouter 可透過聊天補全的音訊輸出，作為 music_generate 工具的後端。 請在 agents.defaults.musicGenerationModel 下設定 OpenRouter 音訊模型：

{  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 可透過其與 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）轉錄傳入的語音／音訊附件。這適用於任何將傳入語音／音訊轉送至媒體理解預檢的頻道外掛。

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

OpenClaw 會依 OpenRouter 的 STT 規格，以 JSON 傳送 OpenRouter STT 請求，並將 base64 音訊置於 input_audio 下，而非使用 multipart OpenAI 表單上傳。

Fusion 路由器

OpenRouter Fusion 會將一個 OpenClaw 模型參照並行傳送至多個 OpenRouter 模型，讓 OpenRouter 評審其回答，再透過一般的 OpenRouter 端點傳回一個最終回應。上游模型代稱為 openrouter/fusion，因此 OpenClaw 模型參照同時包含 OpenClaw 供應商前綴與上游 OpenRouter 命名空間：

openclaw models set openrouter/openrouter/fusion

請透過模型的 params.extraBody 設定 Fusion 的模型小組與評審；這些欄位會直接轉送至 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 是並行運作的模型小組；Fusion 外掛設定內的 model 是評審模型。在一般代理程式／聊天回合中，請勿將頂層 tool_choice 設為 "required" 來嘗試強制使用 Fusion：OpenClaw 回合可能包含自身的工具定義，而頂層的必要工具選擇可能會選取其中一項工具，而非 Fusion 路由器。存在此 Fusion 外掛設定時，OpenClaw 會新增經過清理的系統提示詞附註，列出已設定的分析模型與評審模型，讓代理程式能回答有關自身 Fusion 模型小組的問題。其他 extraBody 欄位不會複製到提示詞中。

Fusion 本來就設計得較慢：OpenRouter 會將提示詞分送至多個分析模型，再執行評審／統整步驟，因此延遲會高於直接向單一模型發出請求。請將其用於需要審慎、高品質回答或升級處理的路徑，而不要作為對延遲敏感的預設選項。維持精簡的模型小組，並選擇較快的分析／評審模型，以加快回應速度。

使用一次性的本機呼叫測試已設定的參照：

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

驗證與標頭

OpenRouter 使用來自您 API 金鑰的 Bearer 權杖。OpenRouter OAuth 是一種 PKCE 登入流程，會核發 OpenRouter API 金鑰，因此 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,            },          },        },      },    },  },}

相關內容