diff --git a/docs/zh-CN/providers/openrouter.md b/docs/zh-CN/providers/openrouter.md index 171521c97..c25ec45a5 100644 --- a/docs/zh-CN/providers/openrouter.md +++ b/docs/zh-CN/providers/openrouter.md @@ -1,34 +1,34 @@ --- read_when: - - 你想为多个大语言模型使用一个 API 密钥 - - 你想要在 OpenClaw 中通过 OpenRouter 运行模型 - - 你想使用 OpenRouter 生成图像 + - 你想用一个 API 密钥访问多种大语言模型 + - 你想通过 OpenRouter 在 OpenClaw 中运行模型 + - 你想使用 OpenRouter 进行图像生成 - 你想使用 OpenRouter 进行视频生成 -summary: 在 OpenClaw 中使用 OpenRouter 的统一 API 访问多个模型 +summary: 使用 OpenRouter 的统一 API 在 OpenClaw 中访问众多模型 title: OpenRouter x-i18n: - generated_at: "2026-05-02T05:52:48Z" + generated_at: "2026-05-02T09:53:05Z" model: gpt-5.5 provider: openai - source_hash: f6f7c6f9c77e2a62866fdeaa65667d3871930be2ce22a638accdb8baa76220fd + source_hash: e98b8b540265b6d11681390c02cb68312f33625bf223823a2dbca17e877c0422 source_path: providers/openrouter.md workflow: 16 --- -OpenRouter 提供一个**统一 API**，可通过单一端点和 API 密钥将请求路由到许多模型。它与 OpenAI 兼容，因此大多数 OpenAI SDK 只需切换基础 URL 即可使用。 +OpenRouter 提供一个**统一 API**，可通过单一端点和 API key 将请求路由到多个模型。它兼容 OpenAI，因此大多数 OpenAI SDK 只需切换 base URL 即可使用。 ## 入门指南 - - 在 [openrouter.ai/keys](https://openrouter.ai/keys) 创建 API 密钥。 + + 在 [openrouter.ai/keys](https://openrouter.ai/keys) 创建 API key。 - + ```bash openclaw onboard --auth-choice openrouter-api-key ``` - + 新手引导默认使用 `openrouter/auto`。之后可以选择一个具体模型： ```bash @@ -54,12 +54,12 @@ OpenRouter 提供一个**统一 API**，可通过单一端点和 API 密钥将 ## 模型引用 -模型引用遵循 `openrouter//` 模式。可用提供商和模型的完整列表请参见 [/concepts/model-providers](/zh-CN/concepts/model-providers)。 +模型引用遵循 `openrouter//` 模式。如需可用提供商和模型的完整列表，请参阅 [/concepts/model-providers](/zh-CN/concepts/model-providers)。 内置回退示例： -| 模型引用 | 说明 | +| 模型引用 | 备注 | | --------------------------------- | ---------------------------- | | `openrouter/auto` | OpenRouter 自动路由 | | `openrouter/moonshotai/kimi-k2.6` | 通过 MoonshotAI 使用 Kimi K2.6 | @@ -82,7 +82,7 @@ OpenRouter 也可以作为 `image_generate` 工具的后端。在 `agents.defaul } ``` -OpenClaw 会使用 `modalities: ["image", "text"]` 将图像请求发送到 OpenRouter 的聊天补全图像 API。Gemini 图像模型通过 OpenRouter 的 `image_config` 接收受支持的 `aspectRatio` 和 `resolution` 提示。对于较慢的 OpenRouter 图像模型，请使用 `agents.defaults.imageGenerationModel.timeoutMs`；`image_generate` 工具每次调用的 `timeoutMs` 参数仍会优先。 +OpenClaw 会使用 `modalities: ["image", "text"]` 将图像请求发送到 OpenRouter 的 chat completions 图像 API。Gemini 图像模型会通过 OpenRouter 的 `image_config` 接收受支持的 `aspectRatio` 和 `resolution` 提示。对于较慢的 OpenRouter 图像模型，请使用 `agents.defaults.imageGenerationModel.timeoutMs`；`image_generate` 工具的单次调用 `timeoutMs` 参数仍然优先。 ## 视频生成 @@ -101,11 +101,11 @@ OpenRouter 也可以通过其异步 `/videos` API 作为 `video_generate` 工具 } ``` -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 目前接受文本和图像参考。 +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 提供商。 +OpenRouter 还可以通过其 OpenAI 兼容的 `/audio/speech` 端点用作 TTS 提供商。 ```json5 { @@ -125,59 +125,63 @@ OpenRouter 也可以通过其兼容 OpenAI 的 `/audio/speech` 端点用作 TTS } ``` -如果省略 `messages.tts.providers.openrouter.apiKey`，TTS 会复用 `models.providers.openrouter.apiKey`，然后使用 `OPENROUTER_API_KEY`。 +如果省略 `messages.tts.providers.openrouter.apiKey`，TTS 会复用 `models.providers.openrouter.apiKey`，然后再使用 `OPENROUTER_API_KEY`。 -## 身份验证和请求头 +## 身份验证和标头 -OpenRouter 底层使用带有你的 API 密钥的 Bearer 令牌。 +OpenRouter 底层使用带有你的 API key 的 Bearer token。 -在真实的 OpenRouter 请求（`https://openrouter.ai/api/v1`）上，OpenClaw 还会添加 OpenRouter 文档中说明的应用归因请求头： +在真实的 OpenRouter 请求（`https://openrouter.ai/api/v1`）中，OpenClaw 还会添加 OpenRouter 文档化的应用归因标头： -| 请求头 | 值 | +| 标头 | 值 | | ------------------------- | --------------------- | | `HTTP-Referer` | `https://openclaw.ai` | | `X-OpenRouter-Title` | `OpenClaw` | | `X-OpenRouter-Categories` | `cli-agent` | -如果你将 OpenRouter 提供商重新指向其他代理或基础 URL，OpenClaw **不会**注入这些 OpenRouter 专用请求头或 Anthropic 缓存标记。 +如果你将 OpenRouter 提供商重新指向其他代理或 base URL，OpenClaw **不会**注入这些 OpenRouter 专用标头或 Anthropic 缓存标记。 ## 高级配置 - - 在已验证的 OpenRouter 路由上，Anthropic 模型引用会保留 OpenRouter 专用的 Anthropic `cache_control` 标记，OpenClaw 使用这些标记来提升系统/开发者提示块的提示缓存复用。 + + 在经过验证的 OpenRouter 路由上，Anthropic 模型引用会保留 OpenRouter 专用的 Anthropic `cache_control` 标记，OpenClaw 会用它们在 system/developer prompt 块上更好地复用 prompt cache。 - - 在已验证的 OpenRouter 路由上，启用推理的 Anthropic 模型引用会在请求到达 OpenRouter 之前丢弃尾随的助手预填充轮次，以匹配 Anthropic 对推理对话必须以用户轮次结束的要求。 + + 在经过验证的 OpenRouter 路由上，启用 reasoning 的 Anthropic 模型引用会在请求到达 OpenRouter 之前丢弃末尾的 assistant prefill 轮次，以符合 Anthropic 要求 reasoning 对话以 user 轮次结束的规则。 - - 在受支持的非 `auto` 路由上，OpenClaw 会将所选思考级别映射到 OpenRouter 代理推理载荷。不受支持的模型提示和 `openrouter/auto` 会跳过该推理注入。Hunter Alpha 也会对过期配置的模型引用跳过代理推理，因为 OpenRouter 可能会在该已停用路由的推理字段中返回最终答案文本。 + + 在受支持的非 `auto` 路由上，OpenClaw 会将所选 thinking 级别映射到 OpenRouter 代理 reasoning 载荷。不受支持的模型提示和 `openrouter/auto` 会跳过该 reasoning 注入。Hunter Alpha 也会对过期配置的模型引用跳过代理 reasoning，因为 OpenRouter 可能会在该退役路由的 reasoning 字段中返回最终答案文本。 - - OpenRouter 仍然会经过代理风格、兼容 OpenAI 的路径，因此不会转发原生仅 OpenAI 的请求塑形，例如 `serviceTier`、Responses `store`、OpenAI 推理兼容载荷和提示缓存提示。 + + 在经过验证的 OpenRouter 路由上，`openrouter/deepseek/deepseek-v4-flash` 和 `openrouter/deepseek/deepseek-v4-pro` 会为重放的 assistant 轮次填充缺失的 `reasoning_content`，从而让 thinking/tool 对话保持 DeepSeek V4 所需的后续形态。 - - Gemini 支持的 OpenRouter 引用会留在代理 Gemini 路径上：OpenClaw 会在那里保留 Gemini 思维签名清理，但不会启用原生 Gemini 重放验证或引导重写。 + + OpenRouter 仍然走代理式 OpenAI 兼容路径，因此不会转发仅原生 OpenAI 支持的请求整理，例如 `serviceTier`、Responses `store`、OpenAI reasoning 兼容载荷和 prompt cache 提示。 - - 如果你在模型参数下传递 OpenRouter 提供商路由，OpenClaw 会在共享流包装器运行之前将其作为 OpenRouter 路由元数据转发。 + + Gemini 后端的 OpenRouter 引用会留在 proxy-Gemini 路径上：OpenClaw 会在那里保留 Gemini thought-signature 清理，但不会启用原生 Gemini 重放验证或 bootstrap 重写。 + + + + 如果你在模型参数下传递 OpenRouter 提供商路由，OpenClaw 会在共享 stream 包装器运行之前将其作为 OpenRouter 路由元数据转发。 ## 相关内容 - + 选择提供商、模型引用和故障转移行为。 - + 智能体、模型和提供商的完整配置参考。