跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

OpenRouter 提供一个统一 API，可通过单一端点和 API key 将请求路由到多个模型。它兼容 OpenAI，因此大多数 OpenAI SDK 只需切换 base URL 即可使用。

​
入门指南

1

获取你的 API key

在 openrouter.ai/keys 创建 API key。
2

运行新手引导

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

（可选）切换到特定模型

新手引导默认使用 openrouter/auto。之后可选择一个具体模型：
openclaw models set openrouter/<provider>/<model>

​
配置示例

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

​
模型引用

模型引用遵循 openrouter/<provider>/<model> 模式。完整的可用提供商和模型列表，请参阅 /concepts/model-providers。
内置回退示例：
模型引用说明
openrouter/autoOpenRouter 自动路由
openrouter/moonshotai/kimi-k2.6通过 MoonshotAI 使用 Kimi K2.6
openrouter/moonshotai/kimi-k2.5通过 MoonshotAI 使用 Kimi K2.5

​
图像生成

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 会将图像请求发送到 OpenRouter 的 chat completions 图像 API，并带上 modalities: ["image", "text"]。Gemini 图像模型会通过 OpenRouter 的 image_config 接收受支持的 aspectRatio 和 resolution 提示。对于较慢的 OpenRouter 图像模型，请使用 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 会向 OpenRouter 提交文生视频和图生视频任务，轮询返回的 polling_url，并从 OpenRouter 的 unsigned_urls 或文档化的任务内容端点下载已完成的视频。默认情况下，参考图像会作为首帧/末帧图像发送；标记为 reference_image 的图像会作为 OpenRouter 输入引用发送。内置的 google/veo-3.1-fast 默认值声明了当前支持的 4/6/8 秒时长、720P/1080P 分辨率，以及 16:9/9:16 宽高比。OpenRouter 未注册视频到视频功能，因为上游视频生成 API 目前接受文本和图像引用。

​
文本转语音

OpenRouter 也可以通过其 OpenAI 兼容的 /audio/speech 端点用作 TTS 提供商。 
{
  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。

​
语音转文本（入站音频）

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 发送，并在 input_audio 下携带 base64 音频（OpenRouter STT 契约），而不是作为 multipart OpenAI 表单上传。

​
身份验证和标头

OpenRouter 在底层使用带有你的 API key 的 Bearer token。 在真实 OpenRouter 请求（https://openrouter.ai/api/v1）中，OpenClaw 还会添加 OpenRouter 文档化的应用归因标头：
标头值
HTTP-Refererhttps://openclaw.ai
X-OpenRouter-TitleOpenClaw
X-OpenRouter-Categoriescli-agent,cloud-agent,programming-app,creative-writing,writing-assistant,general-chat,personal-agent
如果你将 OpenRouter 提供商重新指向其他代理或 base URL，OpenClaw 不会注入这些 OpenRouter 专用标头或 Anthropic 缓存标记。

​
高级配置

OpenRouter 响应缓存是选择启用的。通过模型参数为每个 OpenRouter 模型启用：
{
  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）。这独立于提供商提示词缓存，也独立于 OpenRouter 的 Anthropic cache_control 标记。它只会应用于已验证的 openrouter.ai 路由，而不会应用于自定义代理 base URL。
在已验证的 OpenRouter 路由上，Anthropic 模型引用会保留 OpenRouter 专用的 Anthropic cache_control 标记，OpenClaw 使用这些标记来更好地复用 system/developer 提示词块的提示词缓存。
在已验证的 OpenRouter 路由上，启用 reasoning 的 Anthropic 模型引用会在请求到达 OpenRouter 前丢弃末尾的 assistant 预填充轮次，以匹配 Anthropic 要求 reasoning 对话以用户轮次结束的约束。
在受支持的非 auto 路由上，OpenClaw 会将所选 thinking 级别映射到 OpenRouter 代理 reasoning payload。不受支持的模型提示和 openrouter/auto 会跳过该 reasoning 注入。Hunter Alpha 也会针对过期配置的模型引用跳过代理 reasoning，因为 OpenRouter 可能会在该已退役路由的 reasoning 字段中返回最终答案文本。
在已验证的 OpenRouter 路由上，openrouter/deepseek/deepseek-v4-flash 和 openrouter/deepseek/deepseek-v4-pro 会在重放的 assistant 轮次中填充缺失的 reasoning_content，使 thinking/tool 对话保持 DeepSeek V4 所需的后续形态。OpenClaw 会为这些路由发送 OpenRouter 支持的 reasoning_effort 值；xhigh 是已声明的最高级别，过期的 max 覆盖值会映射到 xhigh。
OpenRouter 仍会通过代理风格的 OpenAI 兼容路径运行，因此不会转发仅原生 OpenAI 支持的请求整形，例如 serviceTier、Responses store、OpenAI reasoning 兼容 payload 和提示词缓存提示。
Gemini 后端的 OpenRouter 引用会保留在代理 Gemini 路径上：OpenClaw 会在那里保留 Gemini thought-signature 清理，但不会启用原生 Gemini 重放验证或 bootstrap 重写。
如果你在模型参数下传递 OpenRouter 提供商路由，OpenClaw 会在共享流包装器运行前将其作为 OpenRouter 路由元数据转发。

​
相关

模型选择

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

配置参考

智能体、模型和提供商的完整配置参考。