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 格式，并将 base64 音频放在 input_audio 下（遵循 OpenRouter 的 STT 契约），而不是使用 multipart OpenAI 表单上传。

Fusion 路由器

OpenRouter Fusion 会将一个 OpenClaw 模型引用并行发送给多个 OpenRouter 模型，由 OpenRouter 评判它们的回答，再通过常规 OpenRouter 端点返回一个最终响应。上游模型 slug 为 openrouter/fusion，因此 OpenClaw 模型引用同时包含 OpenClaw 提供商前缀和上游 OpenRouter 命名空间：

openclaw models set openrouter/openrouter/fusion

通过模型的 params.extraBody 配置 Fusion 的模型组和评判模型；这些字段会直接转发到 OpenRouter 聊天补全请求正文中。Fusion 支持 OAuth 或 API key 新手引导；如果使用 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 是评判模型。在常规智能体/聊天轮次中， 不要为了强制使用 Fusion 而将顶层 tool_choice 设置为 "required"：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 key 的 Bearer 令牌。OpenRouter OAuth 是一种 PKCE 登录流程， 会签发 OpenRouter API key，因此 OpenClaw 会将结果存储在手动设置 API key 时使用的同一个 openrouter:default API key 身份验证配置文件中。

若要在现有安装中登录或轮换已存储的密钥，而不重新运行完整的新手引导：

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,            },          },        },      },    },  },}

相关内容