OpenClaw 接入 OpenRouter：统一 API、模型名与常见错误排查

OpenRouter 适合在 OpenClaw 中用一个 API Key 统一访问多家模型，并支持图片、视频、音乐生成和语音识别。配置时最关键的是：环境变量使用 OPENROUTER_API_KEY，模型名写成 openrouter/<provider>/<model>，不要把 OpenAI 原生的 openai/... 模型前缀和 OpenRouter 的 openrouter/... 混用。验证方法：运行 openclaw onboard --auth-choice openrouter-api-key 后执行 openclaw doctor 检查 provider 状态。

OpenRouter 提供一个统一 API，通过单一端点和 API Key 路由到多个模型。它兼容 OpenAI 格式，只需切换 base URL 即可在大多数 OpenAI SDK 中使用。

快速开始

获取 API Key：在 openrouter.ai/keys 创建。

运行配置向导：

bash

openclaw onboard --auth-choice openrouter-api-key

（可选）切换具体模型：默认使用 openrouter/auto，之后可改为特定模型：
bash
```
openclaw models set openrouter/<provider>/<model>
```

配置示例

json5

{
  env: { OPENROUTER_API_KEY: "sk-or-..." },
  agents: {
    defaults: {
      model: { primary: "openrouter/auto" },
    },
  },
}

模型引用

模型引用格式为 openrouter/<provider>/<model>。完整供应商和模型列表见 /openclaw/concepts/model-providers。

内置回退示例：

模型引用	说明
`openrouter/auto`	OpenRouter 自动路由
`openrouter/moonshotai/kimi-k2.6`	Kimi K2.6（MoonshotAI）
`openrouter/moonshotai/kimi-k2.5`	Kimi K2.5（MoonshotAI）

图片生成

OpenRouter 可以驱动 image_generate 工具。在 agents.defaults.imageGenerationModel 下使用 OpenRouter 图片模型：

json5

{
  env: { OPENROUTER_API_KEY: "sk-or-..." },
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "openrouter/google/gemini-3.1-flash-image-preview",
        timeoutMs: 180_000,
      },
    },
  },
}

OpenClaw 向 OpenRouter 的聊天补全图片 API 发送请求，携带 modalities: ["image", "text"]。Gemini 图片模型通过 OpenRouter 的 image_config 接收 aspectRatio 和 resolution 提示。timeoutMs 参数用于应对较慢的模型；image_generate 工具的每次调用 timeoutMs 参数优先级更高。

视频生成

OpenRouter 可以通过其异步 /videos API 驱动 video_generate 工具。在 agents.defaults.videoGenerationModel 下使用 OpenRouter 视频模型：

json5

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

OpenClaw 向 OpenRouter 提交文本转视频和图片转视频任务，轮询返回的 polling_url，并从 OpenRouter 的 unsigned_urls 或任务内容端点下载完成视频。参考图片默认作为首尾帧发送；标记为 reference_image 的图片作为输入参考发送。内置 google/veo-3.1-fast 默认支持 4/6/8 秒时长、720P/1080P 分辨率、16:9/9:16 宽高比。OpenRouter 视频生成 API 目前只接受文本和图片参考，未注册视频转视频功能。

音乐生成

OpenRouter 可以通过聊天补全音频输出驱动 music_generate 工具。在 agents.defaults.musicGenerationModel 下使用 OpenRouter 音频模型：

json5

{
  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=... 参数接受参考图片。

文本转语音（TTS）

OpenRouter 可作为 TTS 供应商使用，通过其兼容 OpenAI 的 /audio/speech 端点：

json5

{
  messages: {
    tts: {
      auto: "always",
      provider: "openrouter",
      providers: {
        openrouter: {
          model: "hexgrad/kokoro-82m",
          voice: "af_alloy",
          responseFormat: "mp3",
        },
      },
    },
  },
}

如果 messages.tts.providers.openrouter.apiKey 省略，TTS 会复用 models.providers.openrouter.apiKey，然后 OPENROUTER_API_KEY。

语音转文本（STT）

OpenRouter 可以通过其 STT 端点（/audio/transcriptions）转写传入的语音/音频附件，通过共享的 tools.media.audio 路径。这适用于任何转发传入语音/音频到媒体理解预检的频道插件：

json5

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

OpenClaw 向 OpenRouter STT 发送 JSON 格式请求，input_audio 字段包含 base64 音频（OpenRouter STT 合约），不使用 multipart OpenAI 表单上传。

认证与请求头

OpenRouter 底层使用 Bearer token 传递 API Key。

在真实的 OpenRouter 请求（https://openrouter.ai/api/v1）上，OpenClaw 还会添加 OpenRouter 要求的应用归属头：

请求头	值
`HTTP-Referer`	`https://openclaw.ai`
`X-OpenRouter-Title`	`OpenClaw`
`X-OpenRouter-Categories`	`cli-agent,cloud-agent,programming-app,creative-writing,writing-assistant,general-chat,personal-agent`

WARNING

如果你将 OpenRouter provider 指向其他代理或 base URL，OpenClaw 不会注入这些 OpenRouter 专属头或 Anthropic 缓存标记。

高级配置

响应缓存

OpenRouter 响应缓存是 opt-in 的。通过模型参数启用：

json5

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

OpenClaw 发送 X-OpenRouter-Cache: true，以及配置后的 X-OpenRouter-Cache-TTL。responseCacheClear: true 强制刷新当前请求并存储替换响应。也接受蛇形别名（response_cache、response_cache_ttl_seconds、response_cache_clear）。此缓存与模型提示缓存以及 OpenRouter 的 Anthropic cache_control 标记互不影响。仅对已验证的 openrouter.ai 路由生效，不自定义代理 base URL。

Anthropic 缓存标记

在已验证的 OpenRouter 路由上，Anthropic 模型引用保留 OpenClaw 使用的 OpenRouter 专属 Anthropic cache_control 标记，以实现更好的提示缓存复用（针对 system/developer 提示块）。

Anthropic 思考预填充

在已验证的 OpenRouter 路由上，启用了思考的 Anthropic 模型引用在请求到达 OpenRouter 之前会丢弃末尾的助手预填充轮次，以匹配 Anthropic 的要求（思考对话必须以用户轮次结尾）。

思考/推理注入

在支持的非 auto 路由上，OpenClaw 将选择的思考层级映射到 OpenRouter 的代理推理负载。不支持的模型提示和 openrouter/auto 跳过此推理注入。对于已弃用的 Hunter Alpha 路由，跳过代理推理（因为 OpenRouter 可能在推理字段中返回最终答案文本）。

DeepSeek V4 推理重放

在已验证的 OpenRouter 路由上，openrouter/deepseek/deepseek-v4-flash 和 openrouter/deepseek/deepseek-v4-pro 会为回放的助手轮次填充缺失的 reasoning_content，以使思考/工具对话保持 DeepSeek V4 所需的后续形状。OpenClaw 发送 OpenRouter 支持的 reasoning_effort 值；xhigh 是最高等级，旧的 max 会被映射为 xhigh。

OpenAI 专属请求塑形

OpenRouter 仍通过代理风格的 OpenAI 兼容路径运行，因此原生的 OpenAI 专属请求塑形（如 serviceTier、Responses store、OpenAI 推理兼容负载、提示缓存提示）不会被转发。

Gemini 后端路由

Gemini 后端的 OpenRouter 引用保持在代理-Gemini 路径上：OpenClaw 保留 Gemini 的思考签名清理，但不启用原生 Gemini 重放验证或引导重写。

供应商路由元数据

OpenRouter 支持 provider 请求对象用于底层供应商路由。通过 models.providers.openrouter.params.provider 配置所有 OpenRouter 文本模型请求的默认策略：

json5

{
  models: {
    providers: {
      openrouter: {
        params: {
          provider: {
            sort: "latency",
            require_parameters: true,
            data_collection: "deny",
          },
        },
      },
    },
  },
}

OpenClaw 将该对象作为请求的 provider 负载转发给 OpenRouter。使用 OpenRouter 文档记录的蛇形字段，包括 sort、only、ignore、order、allow_fallbacks、require_parameters、data_collection、quantizations、max_price、preferred_max_latency、preferred_min_throughput、zdr、enforce_distillable_text。

每个模型的参数仍然覆盖供应商级别的路由对象：

json5

{
  agents: {
    defaults: {
      models: {
        "openrouter/anthropic/claude-sonnet-4-6": {
          params: {
            provider: {
              order: ["anthropic"],
              allow_fallbacks: false,
            },
          },
        },
      },
    },
  },
}

此功能仅作用于 OpenRouter 的聊天补全路由。直接使用 Anthropic、Google、OpenAI 或自定义供应商路由时忽略 OpenRouter 路由参数。

常见问题

OpenRouter 在 OpenClaw 中支持哪些模型类型？

OpenRouter 支持文本对话（通过聊天补全）、图片生成（image_generate）、视频生成（video_generate）、音乐生成（music_generate）、文本转语音（TTS）和语音转文本（STT）。每种都需要在对应配置项下指定模型引用，模型名格式为 openrouter/<provider>/<model>。

如何为 OpenRouter 配置供应商路由元数据？

在 models.providers.openrouter.params.provider 中设置 OpenRouter 支持的 provider 对象，例如 sort: "latency"。每个模型还可以在 agents.defaults.models["openrouter/..."].params.provider 中单独覆盖。注意此功能只对 OpenRouter 聊天补全路由生效。

OpenRouter 的响应缓存和 Anthropic 缓存标记有什么区别？

响应缓存（Response caching）是 OpenRouter 的 opt-in 功能，通过 X-OpenRouter-Cache 头控制，对任何模型都可用。Anthropic 缓存标记是 Anthropic 模型的专属 cache_control，用于提示块复用。OpenClaw 在已验证的 OpenRouter 路由上同时支持两者，但它们是独立的，不会相互影响。

OpenClaw 接入 OpenRouter：统一 API、模型名与常见错误排查 ​

快速开始 ​

配置示例 ​

模型引用 ​

图片生成 ​

视频生成 ​

音乐生成 ​

文本转语音（TTS） ​

语音转文本（STT） ​

认证与请求头 ​

高级配置 ​

响应缓存 ​

Anthropic 缓存标记 ​

Anthropic 思考预填充 ​

思考/推理注入 ​

DeepSeek V4 推理重放 ​

OpenAI 专属请求塑形 ​

Gemini 后端路由 ​

供应商路由元数据 ​

常见问题 ​

OpenRouter 在 OpenClaw 中支持哪些模型类型？ ​

如何为 OpenRouter 配置供应商路由元数据？ ​

OpenRouter 的响应缓存和 Anthropic 缓存标记有什么区别？ ​

OpenClaw 接入 OpenRouter：统一 API、模型名与常见错误排查

快速开始

配置示例

模型引用

图片生成

视频生成

音乐生成

文本转语音（TTS）

语音转文本（STT）

认证与请求头

高级配置

响应缓存

Anthropic 缓存标记

Anthropic 思考预填充

思考/推理注入

DeepSeek V4 推理重放

OpenAI 专属请求塑形

Gemini 后端路由

供应商路由元数据

常见问题

OpenRouter 在 OpenClaw 中支持哪些模型类型？

如何为 OpenRouter 配置供应商路由元数据？

OpenRouter 的响应缓存和 Anthropic 缓存标记有什么区别？