跳转至

OpenRouter

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

快速开始

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

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

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

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

1. 运行 OAuth 引导

openclaw onboard --auth-choice openrouter-oauth

OpenClaw 会打开 OpenRouter 的浏览器登录流程(PKCE),用代码交换 OpenRouter API 密钥,并将其存储在默认 OpenRouter 身份验证配置文件中。在远程/无头主机上,OpenClaw 会打印登录 URL,并要求你在登录后粘贴重定向 URL。

2.(可选)切换到特定模型

引导默认使用 openrouter/auto。稍后选择一个具体模型:

openclaw models set openrouter/<provider>/<model>

1. 获取你的 API 密钥

在 openrouter.ai/keys 创建一个 API 密钥。

2. 运行 API 密钥引导

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

3.(可选)切换到特定模型

引导默认使用 openrouter/auto。稍后选择一个具体模型:

openclaw models set openrouter/<provider>/<model>

配置示例

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

模型引用

Note

模型引用遵循 openrouter/<provider>/<model> 模式。要查看 OpenRouter 路由到的提供商和模型的完整列表,请参阅 OpenRouter 模型目录。要了解 OpenClaw 如何解析模型引用和故障转移,请参阅 模型选择。

捆绑的初始模型会补充非空的公共目录。失败的实时请求会报告发现失败,而不是替换这些行;成功的空响应保持为空:

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

任何其他 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 以 JSON 形式发送 OpenRouter STT 请求,其中 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 密钥入门配置;如果使用 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 密钥的 Bearer token。OpenRouter OAuth 是一个 PKCE 登录流程,会签发一个 OpenRouter API 密钥,因此 OpenClaw 将结果存储在与手动 API 密钥设置使用的同一个 openrouter:default API 密钥身份验证配置文件中。

要在现有安装中登录或轮换存储的密钥,而无需重新运行完整入门:

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 的自定义 provider id:

请求头 值
HTTP-Referer https://openclaw.ai
X-OpenRouter-Title OpenClaw
X-OpenRouter-Categories personal-agent,cli-agent

Warning

如果你将 OpenRouter 提供商重新指向其他代理或基础 URL,OpenClaw 不会注入这些 OpenRouter 特定请求头或 Anthropic 缓存标记。

高级配置

响应缓存

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)同样被接受,不带 Seconds 后缀的 responseCacheTtl / response_cache_ttl 也可以。TTL 值会被截断并限制在 1–86400 秒内;非有限值会被忽略。

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

Anthropic 缓存标记

在已验证的 OpenRouter 路由上,Anthropic 模型引用会保留 OpenRouter 的 Anthropic cache_control 标记,以便在 system/developer 提示块上更好地复用提示缓存。

Anthropic 推理预填充

在已验证的 OpenRouter 路由上,启用了推理的 Anthropic 模型引用会在请求到达 OpenRouter 之前丢弃末尾的 assistant 预填充轮次,以符合 Anthropic 关于推理对话必须以用户轮次结束的要求。

思考 / 推理注入

OpenClaw 使用所选模型公布的推理努力级别来决定其思考选项和请求负载。需要推理的模型会省略“关闭”选项。Agent 轮次和独立补全共享这些控制以及推理重放规则。在受支持的非 auto 路由上,OpenClaw 会将所选的思考水平映射到 OpenRouter 代理推理负载。openrouter/auto 和不受支持的模型提示会跳过该注入。陈旧的 openrouter/hunter-alpha 引用也会跳过它,因为在该已退役路由上,OpenRouter 可能在推理字段中返回最终答案文本。

没有努力级别选择器的模型会显示开/关控制,或者当推理为强制时显示 始终开启。这些模型接收二元推理控制,不带有标量努力级别。省略思考请求会使其原生推理默认值保持不变;已配置的推理预算会被保留。

DeepSeek V4 推理重放

在已验证的 OpenRouter 路由上,openrouter/deepseek/deepseek-v4-flash 和 openrouter/deepseek/deepseek-v4-pro 会在重放的 assistant 轮次中填充缺失的 reasoning_content,使思考/工具对话保持 DeepSeek V4 要求的后续形状。OpenClaw 会为这些路由发送 OpenRouter 支持的 reasoning.effort 值:xhigh/max 映射为 xhigh,所有其他非关闭级别映射为 high。/think off 会显式发送 reasoning.effort: "none" 并移除推理重放字段,而不是回退到提供商的推理默认值。

仅 OpenAI 请求整形

OpenRouter 通过代理风格的 OpenAI 兼容路径运行,因此诸如 serviceTier、Responses store、OpenAI 推理兼容负载和提示缓存提示等原生 OpenAI 独有的请求整形不会被转发。

Gemini 支持的路由

由 Gemini 支持的 OpenRouter 引用保持在代理-Gemini 路径上:OpenClaw 会在那里保留 Gemini 思维签名清理,但不会启用原生 Gemini 重放验证或引导重写。

提供商路由元数据

OpenRouter 支持一个 provider 请求对象,用于底层提供商路由。使用 models.providers.openrouter.params.provider 为所有 OpenRouter 文本模型请求配置默认策略:

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

OpenClaw 会将这个对象作为请求的 provider 负载转发给 OpenRouter。请使用 OpenRouter 文档化的 snake_case 字段,包括 sort、only、ignore、order、allow_fallbacks、require_parameters、data_collection、quantizations、max_price、preferred_max_latency、preferred_min_throughput、zdr 和 enforce_distillable_text。

按模型设置的参数会覆盖提供商级的路由对象:

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

这仅适用于 OpenRouter 的 chat-completions 路由。直接的 Anthropic、Google、OpenAI 或自定义提供商路由会忽略 OpenRouter 路由参数。

模型选择

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

配置参考

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

Arcee

可通过 OpenRouter 密钥访问的 Arcee 模型。

图像生成

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

视频生成

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

音乐生成

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

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw