OpenRouter

OpenRouter 将请求路由到许多模型，背后只需一个 API 和一个密钥。它兼容 OpenAI，因此 OpenClaw 通过与其他代理提供商相同的 openai-completions 风格传输与其通信。

快速开始¶

在私聊中，发送 /login openrouter 或从 /login 中选择 OpenRouter。 选择 使用 OpenRouter 登录，在浏览器中批准访问，然后返回聊天。OpenClaw 会接收浏览器回调，并在报告成功之前保存凭据。使用 /login cancel 取消待处理的登录。

登录会保存访问权限，而不选择入门模型。如果当前模型限制隐藏了 OpenRouter 模型，请选择 显示所有 OpenRouter 模型 或 保留当前限制。无论哪种方式，凭据都会保持已保存状态。在 Control UI 中，使用 设置 → 模型 → 连接 执行相同的仅凭据流程，然后使用模型菜单从 Gateway 的目录中选择一个模型。

聊天浏览器登录使用 Gateway 管理的 Tailscale HTTPS 地址。 使用 Tailscale Serve 时，你的浏览器必须能够访问同一个 tailnet。如果没有可用的管理 HTTPS 地址，请启用 Serve 并重试，或使用下面的 CLI 流程。该回调不会将你登录到 Control UI。

Control UI 会在管理的 HTTPS 地址处自动接收返回，或者在直接通过本地 Gateway 的环回地址和端口打开时接收。 其他地址使用手动重定向完成。如果粘贴的输入不完整或无效，请在同一次登录尝试中更正并重新提交。

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: { vars: { OPENROUTER_API_KEY: "sk-or-..." } },
  agents: {
    defaults: {
      model: { primary: "openrouter/auto" },
    },
  },
}

模型引用¶

内置入门模型会补充非空的公共目录。失败的实时请求会报告发现失败，而不是替换这些行；成功的空响应保持为空：

任何其他 openrouter/<provider>/<model> 引用，包括 openrouter/openrouter/fusion（参见 Fusion 路由器），都会针对 OpenRouter 的实时模型目录动态解析。

发现的模型使用 OpenRouter 声明的工具支持。当模型的 supported_parameters 列表省略 tools 时，OpenClaw 会发送不带工具定义或工具选择的请求。没有该元数据的模型保持默认工具行为。

图像生成¶

OpenRouter 可以为 image_generate 工具提供支持。在 agents.defaults.mediaModels.image 下设置 OpenRouter 图像模型：

{
  env: { vars: { OPENROUTER_API_KEY: "sk-or-..." } },
  agents: {
    defaults: {
      mediaModels: {
        image: {
          primary: "openrouter/google/gemini-3.1-flash-image-preview",
          timeoutMs: 180000,
        },
      },
    },
  },
}

OpenClaw 会将标准的 OpenRouter 图像请求发送到专用图像 API （POST /api/v1/images）。Gemini 图像模型还会额外接收 aspect_ratio 和 resolution 提示，图像编辑会将源图像作为 input_references 传递。生成的图像以 base64（b64_json）形式返回，并带有可选的 media_type；当 media_type 缺失时，OpenClaw 会从字节中嗅探图像格式。

配置的自定义 OpenRouter baseUrl 目标会保留现有的 chat-completions 图像路由，以兼容未暴露专用端点的代理。对于较慢的模型，请使用 agents.defaults.mediaModels.image.timeoutMs； image_generate 工具的每次调用 timeoutMs 仍然优先。

视频生成¶

OpenRouter 可以通过其异步 /videos API 为 video_generate 工具提供支持。在 agents.defaults.mediaModels.video 下设置 OpenRouter 视频模型：

{
  env: { vars: { OPENROUTER_API_KEY: "sk-or-..." } },
  agents: {
    defaults: {
      mediaModels: {
        video: {
          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 可以通过 chat-completions 音频输出为 music_generate 工具提供支持。在 agents.defaults.mediaModels.music 下设置一个 OpenRouter 音频模型：

{
  env: { vars: { OPENROUTER_API_KEY: "sk-or-..." } },
  agents: {
    defaults: {
      mediaModels: {
        music: {
          primary: "openrouter/google/lyria-3-pro-preview",
          timeoutMs: 180000,
        },
      },
    },
  },
}

内置的 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 提供商。

{
  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 路径转录入站语音/音频附件，使用其 STT 端点（/audio/transcriptions）。这适用于任何将入站语音/音频转发到媒体理解预检的频道插件。

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

OpenClaw 将 OpenRouter STT 请求作为 JSON 发送，其中 base64 音频位于 input_audio 下（OpenRouter 的 STT 约定），而不是作为 multipart OpenAI 表单上传。

融合路由器¶

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

openclaw models set openrouter/openrouter/fusion

通过模型的 params.extraBody 配置 Fusion 的评审团和评判模型；这些字段会直接转发到 OpenRouter chat-completions 请求体中。Fusion 支持 OAuth 或 API-key 引导；如果使用 OAuth，请省略下面的 env.vars.OPENROUTER_API_KEY 行。

{
  env: { vars: { 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 是评判模型。不要尝试通过在普通 agent/chat 轮次中将顶层 tool_choice 设置为 "required" 来强制使用 Fusion：OpenClaw 轮次可以包含其自身的工具定义，而顶层必需的工具选择可能会选择其中一个，而不是 Fusion 路由器。当存在此 Fusion 插件配置时，OpenClaw 会添加一条经过清理的系统提示说明，列出已配置的分析模型和评判模型，以便 agent 可以回答关于其自身 Fusion 评审团的问题。其他 extraBody 字段不会复制到提示中。

Fusion 在设计上更慢：OpenRouter 会将提示分发到多个分析模型，然后运行评判/综合步骤，因此延迟会高于直接单模型请求。请将其用于刻意的高质量回答或升级路径，而不是作为延迟敏感的默认设置。保持评审团规模较小，并选择更快的分析/评判模型以获得更快速的响应。

使用一次性本地调用测试已配置的引用：

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

身份验证和请求头¶

OpenRouter 使用来自你的 API key 的 Bearer token。OpenRouter OAuth 是一个 PKCE 登录流程，它会签发一个 OpenRouter API key，因此 OpenClaw 将结果存储在与手动 API-key 设置相同的 openrouter:default API-key 身份验证配置文件中。

要在现有安装上登录或轮换存储的 key，而无需重新运行完整引导：

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

对于发往 OpenRouter 端点（openrouter.ai）的请求，OpenClaw 会添加 OpenRouter 文档中记载的应用归属请求头。这适用于内置的 openrouter 提供商，以及 baseUrl 指向 OpenRouter 的自定义提供商 id：

高级配置¶

json5 { agents: { defaults: { models: { "openrouter/auto": { params: { responseCache: true, responseCacheTtlSeconds: 300, }, }, }, }, }, }

OpenClaw 会发送 `X-OpenRouter-Cache: true`，并在配置后发送
`X-OpenRouter-Cache-TTL`。`responseCacheClear: true` 会强制刷新当前请求，
并存储替换后的响应。Snake_case 别名（`response_cache`、
`response_cache_ttl_seconds`、`response_cache_clear`）同样被接受，
不带 `Seconds` 后缀的 `responseCacheTtl` / `response_cache_ttl` 也被接受。

这与提供商的提示缓存（prompt caching）以及 OpenRouter 的
Anthropic `cache_control` 标记是分开的。它仅适用于已验证的
`openrouter.ai` 路由，不适用于自定义代理 base URL。

相关¶

模型选择

选择提供商、模型引用和故障转移行为。

配置参考

关于 agents、models 和 providers 的完整配置参考。

Arcee

使用 OpenRouter 密钥即可访问的 Arcee 模型。

图像生成

共享的图像工具参数和提供商选择。

视频生成

共享的视频工具参数和提供商选择。

音乐生成

共享的音乐工具参数和提供商选择。