From 2ff0e5573673bf57e690cdff288ae97e4670bad9 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Wed, 22 Apr 2026 03:55:24 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/concepts/model-providers.md | 357 +++++++++++---------- docs/zh-CN/concepts/models.md | 122 +++---- docs/zh-CN/plugins/sdk-provider-plugins.md | 292 ++++++++++------- docs/zh-CN/providers/openrouter.md | 45 +-- docs/zh-CN/providers/vercel-ai-gateway.md | 47 ++- 5 files changed, 466 insertions(+), 397 deletions(-) diff --git a/docs/zh-CN/concepts/model-providers.md b/docs/zh-CN/concepts/model-providers.md index ffa87dad9..6d6bb4d2e 100644 --- a/docs/zh-CN/concepts/model-providers.md +++ b/docs/zh-CN/concepts/model-providers.md @@ -1,14 +1,14 @@ --- read_when: - - 你需要一份按提供商逐一说明的模型设置参考。 - - 你想要模型提供商的示例配置或 CLI 新手引导命令。 -summary: 模型提供商概览，包含示例配置 + CLI 流程 + - 你需要一份按提供商分类的模型设置参考资料 + - 你想要模型提供商的示例配置或 CLI 新手引导命令 +summary: 模型提供商概览，附示例配置与 CLI 流程 title: 模型提供商 x-i18n: - generated_at: "2026-04-21T20:53:28Z" + generated_at: "2026-04-22T03:53:25Z" model: gpt-5.4 provider: openai - source_hash: 6cbb8c9caf148c8db124638a036503fc4d4d3cce947ad99cffdf68a137edaab7 + source_hash: c195cf5eafe277212aefb82483fe5daa6705a7e6534cf3612e7b5b20ac67adb7 source_path: concepts/model-providers.md workflow: 15 --- @@ -21,129 +21,129 @@ x-i18n: ## 快速规则 - 模型引用使用 `provider/model`（示例：`opencode/claude-opus-4-6`）。 -- 如果你设置了 `agents.defaults.models`，它就会成为允许列表。 +- 如果你设置了 `agents.defaults.models`，它会成为允许列表。 - CLI 辅助命令：`openclaw onboard`、`openclaw models list`、`openclaw models set `。 -- 回退运行时规则、冷却探测和会话覆盖持久化记录在 [/concepts/model-failover](/zh-CN/concepts/model-failover) 中。 -- `models.providers.*.models[].contextWindow` 是模型原生元数据；`models.providers.*.models[].contextTokens` 是运行时生效的上限。 -- 提供商插件可以通过 `registerProvider({ catalog })` 注入模型目录；OpenClaw 会在写入 `models.json` 之前，将该输出合并到 `models.providers` 中。 -- 提供商清单可以声明 `providerAuthEnvVars` 和 `providerAuthAliases`，这样通用的基于环境变量的凭证探测和提供商变体就不需要加载插件运行时。当前剩余的核心环境变量映射现在仅用于非插件/核心提供商，以及少数通用优先级场景，例如 Anthropic API 密钥优先的新手引导。 -- 提供商插件还可以通过 `normalizeModelId`、`normalizeTransport`、`normalizeConfig`、`applyNativeStreamingUsageCompat`、`resolveConfigApiKey`、`resolveSyntheticAuth`、`shouldDeferSyntheticProfileAuth`、`resolveDynamicModel`、`prepareDynamicModel`、`normalizeResolvedModel`、`contributeResolvedModelCompat`、`capabilities`、`normalizeToolSchemas`、`inspectToolSchemas`、`resolveReasoningOutputMode`、`prepareExtraParams`、`createStreamFn`、`wrapStreamFn`、`resolveTransportTurnState`、`resolveWebSocketSessionPolicy`、`createEmbeddingProvider`、`formatApiKey`、`refreshOAuth`、`buildAuthDoctorHint`、`matchesContextOverflowError`、`classifyFailoverReason`、`isCacheTtlEligible`、`buildMissingAuthMessage`、`suppressBuiltInModel`、`augmentModelCatalog`、`resolveThinkingProfile`、`isBinaryThinking`、`supportsXHighThinking`、`resolveDefaultThinkingLevel`、`applyConfigDefaults`、`isModernModelRef`、`prepareRuntimeAuth`、`resolveUsageAuth`、`fetchUsageSnapshot` 和 `onModelSelected` 来负责提供商运行时行为。 -- 注意：提供商运行时 `capabilities` 是共享运行器元数据（提供商家族、转录记录/工具行为差异、传输/缓存提示）。它不同于 [公共能力模型](/zh-CN/plugins/architecture#public-capability-model)，后者描述的是插件注册了什么能力（文本推理、语音等）。 -- 内置的 `codex` 提供商与内置 Codex 智能体 harness 配套使用。当你需要 Codex 自有登录、模型发现、原生线程恢复和应用服务器执行时，请使用 `codex/gpt-*`。普通的 `openai/gpt-*` 引用仍然会使用 OpenAI 提供商和标准 OpenClaw 提供商传输。仅使用 Codex 的部署可以通过设置 `agents.defaults.embeddedHarness.fallback: "none"` 禁用自动 PI 回退；参见 [Codex Harness](/zh-CN/plugins/codex-harness)。 +- 回退运行时规则、冷却探测和会话覆盖持久化记录在 [/concepts/model-failover](/zh-CN/concepts/model-failover)。 +- `models.providers.*.models[].contextWindow` 是原生模型元数据；`models.providers.*.models[].contextTokens` 是实际运行时上限。 +- 提供商插件可以通过 `registerProvider({ catalog })` 注入模型目录；OpenClaw 会在写入 `models.json` 之前将该输出合并到 `models.providers` 中。 +- 提供商清单可以声明 `providerAuthEnvVars` 和 `providerAuthAliases`，这样通用的基于环境变量的凭证探测和提供商变体就不需要加载插件运行时。现在剩余的核心环境变量映射仅用于非插件/核心提供商，以及少数通用优先级场景，例如 Anthropic API 密钥优先的新手引导。 +- 提供商插件还可以通过以下能力拥有提供商运行时行为：`normalizeModelId`、`normalizeTransport`、`normalizeConfig`、`applyNativeStreamingUsageCompat`、`resolveConfigApiKey`、`resolveSyntheticAuth`、`shouldDeferSyntheticProfileAuth`、`resolveDynamicModel`、`prepareDynamicModel`、`normalizeResolvedModel`、`contributeResolvedModelCompat`、`capabilities`、`normalizeToolSchemas`、`inspectToolSchemas`、`resolveReasoningOutputMode`、`prepareExtraParams`、`createStreamFn`、`wrapStreamFn`、`resolveTransportTurnState`、`resolveWebSocketSessionPolicy`、`createEmbeddingProvider`、`formatApiKey`、`refreshOAuth`、`buildAuthDoctorHint`、`matchesContextOverflowError`、`classifyFailoverReason`、`isCacheTtlEligible`、`buildMissingAuthMessage`、`suppressBuiltInModel`、`augmentModelCatalog`、`resolveThinkingProfile`、`isBinaryThinking`、`supportsXHighThinking`、`resolveDefaultThinkingLevel`、`applyConfigDefaults`、`isModernModelRef`、`prepareRuntimeAuth`、`resolveUsageAuth`、`fetchUsageSnapshot` 和 `onModelSelected`。 +- 注意：提供商运行时 `capabilities` 是共享运行器元数据（提供商家族、转录/工具怪癖、传输/缓存提示）。它与[公共能力模型](/zh-CN/plugins/architecture#public-capability-model)不同，后者描述的是一个插件注册了什么内容（文本推理、语音等）。 +- 内置的 `codex` 提供商与内置的 Codex 智能体 harness 配对使用。当你希望使用 Codex 自有登录、模型发现、原生线程恢复和 app-server 执行时，请使用 `codex/gpt-*`。普通的 `openai/gpt-*` 引用仍然会使用 OpenAI 提供商和正常的 OpenClaw 提供商传输。仅使用 Codex 的部署可以通过设置 `agents.defaults.embeddedHarness.fallback: "none"` 来禁用自动 PI 回退；请参见 [Codex Harness](/zh-CN/plugins/codex-harness)。 -## 插件自有的提供商行为 +## 插件拥有的提供商行为 -现在，提供商插件可以拥有大多数提供商特定逻辑，而 OpenClaw 保留通用推理循环。 +提供商插件现在可以拥有大多数提供商特定逻辑，而 OpenClaw 保留通用推理循环。 -典型划分： +典型拆分如下： -- `auth[].run` / `auth[].runNonInteractive`：提供商负责 `openclaw onboard`、`openclaw models auth` 和无头设置的引导/登录流程 -- `wizard.setup` / `wizard.modelPicker`：提供商负责凭证选择标签、旧版别名、新手引导允许列表提示，以及新手引导/模型选择器中的设置项 -- `catalog`：提供商出现在 `models.providers` 中 -- `normalizeModelId`：提供商在查找或规范化之前，规范化旧版/预览模型 id -- `normalizeTransport`：提供商在通用模型组装之前规范化传输族的 `api` / `baseUrl`；OpenClaw 会先检查匹配的提供商，然后检查其他支持该 hook 的提供商插件，直到某个插件实际修改了传输 -- `normalizeConfig`：提供商在运行时使用前规范化 `models.providers.` 配置；OpenClaw 会先检查匹配的提供商，然后检查其他支持该 hook 的提供商插件，直到某个插件实际修改了配置。如果没有提供商 hook 重写配置，内置的 Google 家族辅助逻辑仍会规范化受支持的 Google 提供商条目。 -- `applyNativeStreamingUsageCompat`：提供商为配置型提供商应用由端点驱动的原生流式使用量兼容性重写 -- `resolveConfigApiKey`：提供商为配置型提供商解析环境变量标记凭证，而无需强制加载完整运行时凭证。`amazon-bedrock` 在这里也有一个内置的 AWS 环境变量标记解析器，尽管 Bedrock 运行时凭证使用的是 AWS SDK 默认链。 -- `resolveSyntheticAuth`：提供商可以暴露本地/自托管或其他基于配置的可用凭证，而无需持久化明文密钥 -- `shouldDeferSyntheticProfileAuth`：提供商可以将已存储的合成配置档占位凭证标记为低于环境变量/配置支持凭证的优先级 -- `resolveDynamicModel`：提供商接受尚未出现在本地静态目录中的模型 id +- `auth[].run` / `auth[].runNonInteractive`：提供商拥有 `openclaw onboard`、`openclaw models auth` 和无头设置的 新手引导/登录流程 +- `wizard.setup` / `wizard.modelPicker`：提供商拥有凭证选择标签、旧版别名、新手引导允许列表提示，以及新手引导/模型选择器中的设置项 +- `catalog`：提供商会出现在 `models.providers` 中 +- `normalizeModelId`：提供商会在查找或规范化之前标准化旧版/预览模型 ID +- `normalizeTransport`：提供商会在通用模型组装之前标准化传输族的 `api` / `baseUrl`；OpenClaw 会先检查匹配的提供商，然后再检查其他支持此钩子的提供商插件，直到其中一个实际更改了传输 +- `normalizeConfig`：提供商会在运行时使用之前标准化 `models.providers.` 配置；OpenClaw 会先检查匹配的提供商，然后再检查其他支持此钩子的提供商插件，直到其中一个实际更改了配置。如果没有提供商钩子重写配置，内置的 Google 系列辅助逻辑仍会标准化受支持的 Google 提供商条目。 +- `applyNativeStreamingUsageCompat`：提供商会对配置提供商应用由端点驱动的原生流式用量兼容性重写 +- `resolveConfigApiKey`：提供商会为配置提供商解析环境变量标记凭证，而无需强制加载完整运行时凭证。`amazon-bedrock` 这里也有一个内置的 AWS 环境变量标记解析器，即使 Bedrock 运行时凭证使用的是 AWS SDK 默认链。 +- `resolveSyntheticAuth`：提供商可以公开本地/自托管或其他基于配置的凭证可用性，而无需持久化明文密钥 +- `shouldDeferSyntheticProfileAuth`：提供商可以将已存储的合成配置文件占位符标记为优先级低于基于环境变量/配置的凭证 +- `resolveDynamicModel`：提供商可以接受尚未出现在本地静态目录中的模型 ID - `prepareDynamicModel`：提供商在重试动态解析之前需要刷新元数据 -- `normalizeResolvedModel`：提供商需要重写传输或 base URL -- `contributeResolvedModelCompat`：即使供应商模型是通过其他兼容传输接入的，提供商也能为其贡献兼容性标记 -- `capabilities`：提供商发布转录记录/工具/提供商家族相关的行为差异 -- `normalizeToolSchemas`：提供商在内置运行器看到工具 schema 之前对其进行清理 -- `inspectToolSchemas`：提供商在规范化后暴露传输特定的 schema 警告 +- `normalizeResolvedModel`：提供商需要进行传输或 base URL 重写 +- `contributeResolvedModelCompat`：即使其厂商模型是通过其他兼容传输到达的，提供商也可以为其贡献兼容标志 +- `capabilities`：提供商发布转录/工具/提供商家族怪癖 +- `normalizeToolSchemas`：提供商会在内置运行器看到工具 schema 之前先清理它们 +- `inspectToolSchemas`：提供商会在标准化后公开传输特定的 schema 警告 - `resolveReasoningOutputMode`：提供商选择原生或带标签的推理输出契约 -- `prepareExtraParams`：提供商为每个模型的请求参数设置默认值或进行规范化 +- `prepareExtraParams`：提供商为每个模型的请求参数设置默认值或进行标准化 - `createStreamFn`：提供商用完全自定义的传输替换正常流式路径 - `wrapStreamFn`：提供商应用请求头/请求体/模型兼容性包装器 -- `resolveTransportTurnState`：提供商提供每轮原生传输头或元数据 +- `resolveTransportTurnState`：提供商为每个回合提供原生传输头或元数据 - `resolveWebSocketSessionPolicy`：提供商提供原生 WebSocket 会话头或会话冷却策略 -- `createEmbeddingProvider`：当记忆嵌入行为应归属于提供商插件而不是核心嵌入切换板时，由提供商负责 -- `formatApiKey`：提供商将已存储的凭证配置档格式化为传输所期望的运行时 `apiKey` 字符串 -- `refreshOAuth`：当共享的 `pi-ai` 刷新器不足以处理时，由提供商负责 OAuth 刷新 +- `createEmbeddingProvider`：当内存嵌入行为应归属于提供商插件而不是核心嵌入切换层时，由提供商拥有 +- `formatApiKey`：提供商将已存储的凭证配置文件格式化为传输所期望的运行时 `apiKey` 字符串 +- `refreshOAuth`：当共享的 `pi-ai` 刷新器不够用时，由提供商负责 OAuth 刷新 - `buildAuthDoctorHint`：当 OAuth 刷新失败时，提供商追加修复指引 -- `matchesContextOverflowError`：提供商识别通用启发式规则无法发现的提供商特定上下文窗口溢出错误 +- `matchesContextOverflowError`：提供商识别通用启发式方法会漏掉的提供商特定上下文窗口溢出错误 - `classifyFailoverReason`：提供商将提供商特定的原始传输/API 错误映射为回退原因，例如速率限制或过载 -- `isCacheTtlEligible`：提供商决定哪些上游模型 id 支持提示缓存 TTL -- `buildMissingAuthMessage`：提供商用提供商特定的恢复提示替换通用的凭证存储错误 -- `suppressBuiltInModel`：提供商隐藏过时的上游条目，并可在直接解析失败时返回由供应商自有的错误 -- `augmentModelCatalog`：提供商在发现和配置合并后追加合成/最终目录条目 -- `resolveThinkingProfile`：提供商负责所选模型精确的 `/think` 级别集合、可选显示标签和默认级别 -- `isBinaryThinking`：用于二元开/关思考 UX 的兼容性 hook -- `supportsXHighThinking`：用于选定 `xhigh` 模型的兼容性 hook -- `resolveDefaultThinkingLevel`：用于默认 `/think` 策略的兼容性 hook -- `applyConfigDefaults`：提供商在配置具体化期间，基于凭证模式、环境变量或模型家族应用提供商特定的全局默认值 -- `isModernModelRef`：提供商负责 live/smoke 首选模型匹配 -- `prepareRuntimeAuth`：提供商将已配置凭证转换为短时效运行时令牌 +- `isCacheTtlEligible`：提供商决定哪些上游模型 ID 支持提示缓存 TTL +- `buildMissingAuthMessage`：提供商用提供商特定的恢复提示替换通用凭证存储错误 +- `suppressBuiltInModel`：提供商隐藏过时的上游条目，并且可以在直接解析失败时返回厂商自有错误 +- `augmentModelCatalog`：提供商会在发现和配置合并之后追加合成/最终目录条目 +- `resolveThinkingProfile`：提供商拥有精确的 `/think` 级别集合、可选显示标签，以及所选模型的默认级别 +- `isBinaryThinking`：用于二元开/关思考 UX 的兼容性钩子 +- `supportsXHighThinking`：用于选定 `xhigh` 模型的兼容性钩子 +- `resolveDefaultThinkingLevel`：用于默认 `/think` 策略的兼容性钩子 +- `applyConfigDefaults`：提供商会在基于凭证模式、环境变量或模型家族生成配置时应用提供商特定的全局默认值 +- `isModernModelRef`：提供商拥有 live/smoke 首选模型匹配逻辑 +- `prepareRuntimeAuth`：提供商将已配置的凭证转换为短期有效的运行时令牌 - `resolveUsageAuth`：提供商为 `/usage` 及相关状态/报告界面解析用量/配额凭证 -- `fetchUsageSnapshot`：提供商负责用量端点的获取/解析，而核心仍负责摘要外壳和格式化 -- `onModelSelected`：提供商在模型选定后运行副作用，例如遥测或提供商自有的会话记账 +- `fetchUsageSnapshot`：提供商拥有用量端点的抓取/解析逻辑，而核心仍拥有摘要外壳和格式化 +- `onModelSelected`：提供商运行模型选中后的副作用，例如遥测或提供商自有会话记账 当前内置示例： -- `anthropic`：Claude 4.6 前向兼容回退、凭证修复提示、用量端点获取、缓存 TTL/提供商家族元数据，以及具备凭证感知能力的全局配置默认值 -- `amazon-bedrock`：由提供商自有的上下文溢出匹配，以及针对 Bedrock 特有节流/未就绪错误的回退原因分类，外加共享的 `anthropic-by-model` 重放家族，用于 Anthropic 流量上仅限 Claude 的重放策略保护 -- `anthropic-vertex`：针对 Anthropic-message 流量的仅限 Claude 的重放策略保护 -- `openrouter`：透传模型 id、请求包装器、提供商能力提示、代理 Gemini 流量上的 Gemini thought-signature 清理、通过 `openrouter-thinking` 流家族进行的代理推理注入、路由元数据转发，以及缓存 TTL 策略 -- `github-copilot`：新手引导/设备登录、前向兼容模型回退、Claude-thinking 转录提示、运行时令牌交换，以及用量端点获取 -- `openai`：GPT-5.4 前向兼容回退、直接 OpenAI 传输规范化、具备 Codex 感知能力的缺失凭证提示、Spark 屏蔽、合成 OpenAI/Codex 目录条目、thinking/live-model 策略、用量令牌别名规范化（`input` / `output` 和 `prompt` / `completion` 家族）、用于原生 OpenAI/Codex 包装器的共享 `openai-responses-defaults` 流家族、提供商家族元数据、为 `gpt-image-2` 注册的内置图像生成提供商，以及为 `sora-2` 注册的内置视频生成提供商 -- `google` 和 `google-gemini-cli`：Gemini 3.1 前向兼容回退、原生 Gemini 重放校验、引导重放清理、带标签的推理输出模式、现代模型匹配、为 Gemini image-preview 模型注册的内置图像生成提供商，以及为 Veo 模型注册的内置视频生成提供商；Gemini CLI OAuth 还负责凭证配置档令牌格式化、用量令牌解析，以及用于用量界面的配额端点获取 -- `moonshot`：共享传输，插件自有的 thinking 负载规范化 -- `kilocode`：共享传输、插件自有请求头、推理负载规范化、代理 Gemini thought-signature 清理，以及缓存 TTL 策略 -- `zai`：GLM-5 前向兼容回退、`tool_stream` 默认值、缓存 TTL 策略、二元思考/live-model 策略，以及用量凭证 + 配额获取；未知的 `glm-5*` id 会基于内置的 `glm-4.7` 模板进行合成 -- `xai`：原生 Responses 传输规范化、针对 Grok 快速变体的 `/fast` 别名重写、默认 `tool_stream`、xAI 特有的工具 schema / 推理负载清理，以及为 `grok-imagine-video` 注册的内置视频生成提供商 -- `mistral`：插件自有能力元数据 -- `opencode` 和 `opencode-go`：插件自有能力元数据，外加代理 Gemini thought-signature 清理 -- `alibaba`：针对直接 Wan 模型引用（例如 `alibaba/wan2.6-t2v`）的插件自有视频生成目录 -- `byteplus`：插件自有目录，外加为 Seedance 文生视频/图生视频模型注册的内置视频生成提供商 -- `fal`：为托管第三方图像模型注册的内置图像生成提供商（FLUX 图像模型），外加为托管第三方视频模型注册的内置视频生成提供商 -- `cloudflare-ai-gateway`、`huggingface`、`kimi`、`nvidia`、`qianfan`、`stepfun`、`synthetic`、`venice`、`vercel-ai-gateway` 和 `volcengine`：仅插件自有目录 -- `qwen`：文本模型的插件自有目录，外加针对其多模态能力的共享媒体理解和视频生成提供商注册；Qwen 视频生成使用标准 DashScope 视频端点和内置 Wan 模型，例如 `wan2.6-t2v` 和 `wan2.7-r2v` -- `runway`：针对原生 Runway 任务型模型（例如 `gen4.5`）的插件自有视频生成提供商注册 -- `minimax`：插件自有目录、为 Hailuo 视频模型注册的内置视频生成提供商、为 `image-01` 注册的内置图像生成提供商、混合 Anthropic/OpenAI 重放策略选择，以及用量凭证/快照逻辑 -- `together`：插件自有目录，外加为 Wan 视频模型注册的内置视频生成提供商 -- `xiaomi`：插件自有目录，外加用量凭证/快照逻辑 +- `anthropic`：Claude 4.6 前向兼容回退、凭证修复提示、用量端点抓取、缓存 TTL/提供商家族元数据，以及带凭证感知的全局配置默认值 +- `amazon-bedrock`：由提供商拥有的上下文溢出匹配，以及针对 Bedrock 特有的限流/未就绪错误的回退原因分类，另加共享的 `anthropic-by-model` 重放家族，用于 Anthropic 流量上仅限 Claude 的重放策略保护 +- `anthropic-vertex`：针对 Anthropic 消息流量的仅限 Claude 的重放策略保护 +- `openrouter`：透传模型 ID、请求包装器、提供商能力提示、代理 Gemini 流量上的 Gemini thought-signature 清理、通过 `openrouter-thinking` 流家族进行的代理推理注入、路由元数据转发，以及缓存 TTL 策略 +- `github-copilot`：新手引导/设备登录、前向兼容模型回退、Claude 思考转录提示、运行时令牌交换，以及用量端点抓取 +- `openai`：GPT-5.4 前向兼容回退、直接 OpenAI 传输标准化、感知 Codex 的缺失凭证提示、Spark 抑制、合成 OpenAI/Codex 目录条目、thinking/live-model 策略、用量令牌别名标准化（`input` / `output` 和 `prompt` / `completion` 家族）、用于原生 OpenAI/Codex 包装器的共享 `openai-responses-defaults` 流家族、提供商家族元数据、为 `gpt-image-2` 注册的内置图像生成提供商，以及为 `sora-2` 注册的内置视频生成提供商 +- `google` 和 `google-gemini-cli`：Gemini 3.1 前向兼容回退、原生 Gemini 重放校验、引导重放清理、带标签的推理输出模式、现代模型匹配、为 Gemini 图像预览模型注册的内置图像生成提供商，以及为 Veo 模型注册的内置视频生成提供商；Gemini CLI OAuth 还拥有凭证配置文件令牌格式化、用量令牌解析，以及用于用量界面的配额端点抓取 +- `moonshot`：共享传输、由插件拥有的 thinking 载荷标准化 +- `kilocode`：共享传输、由插件拥有的请求头、推理载荷标准化、代理 Gemini thought-signature 清理，以及缓存 TTL 策略 +- `zai`：GLM-5 前向兼容回退、`tool_stream` 默认值、缓存 TTL 策略、二元 thinking/live-model 策略，以及用量凭证 + 配额抓取；未知的 `glm-5*` ID 会基于内置的 `glm-4.7` 模板进行合成 +- `xai`：原生 Responses 传输标准化、针对 Grok fast 变体的 `/fast` 别名重写、默认 `tool_stream`、xAI 特有的工具 schema / 推理载荷清理，以及为 `grok-imagine-video` 注册的内置视频生成提供商 +- `mistral`：由插件拥有的能力元数据 +- `opencode` 和 `opencode-go`：由插件拥有的能力元数据，另加代理 Gemini thought-signature 清理 +- `alibaba`：针对直接 Wan 模型引用（如 `alibaba/wan2.6-t2v`）的由插件拥有的视频生成目录 +- `byteplus`：由插件拥有的目录，另加为 Seedance 文生视频/图生视频模型注册的内置视频生成提供商 +- `fal`：为托管第三方图像生成 FLUX 图像模型注册的内置图像生成提供商，另加为托管第三方视频模型注册的内置视频生成提供商 +- `cloudflare-ai-gateway`、`huggingface`、`kimi`、`nvidia`、`qianfan`、`stepfun`、`synthetic`、`venice`、`vercel-ai-gateway` 和 `volcengine`：仅由插件拥有目录 +- `qwen`：文本模型的由插件拥有目录，以及为其多模态能力注册的共享媒体理解和视频生成提供商；Qwen 视频生成使用 Standard DashScope 视频端点和内置 Wan 模型，例如 `wan2.6-t2v` 和 `wan2.7-r2v` +- `runway`：为原生 Runway 基于任务的模型（如 `gen4.5`）注册的由插件拥有的视频生成提供商 +- `minimax`：由插件拥有的目录、为 Hailuo 视频模型注册的内置视频生成提供商、为 `image-01` 注册的内置图像生成提供商、混合 Anthropic/OpenAI 重放策略选择，以及用量凭证/快照逻辑 +- `together`：由插件拥有的目录，另加为 Wan 视频模型注册的内置视频生成提供商 +- `xiaomi`：由插件拥有的目录，另加用量凭证/快照逻辑 -内置的 `openai` 插件现在同时负责两个提供商 id：`openai` 和 `openai-codex`。 +内置的 `openai` 插件现在同时拥有两个提供商 ID：`openai` 和 `openai-codex`。 -以上涵盖了仍适合 OpenClaw 常规传输方式的提供商。若某个提供商需要完全自定义的请求执行器，那就是一个单独且更深层的扩展接口。 +以上涵盖了仍然适配 OpenClaw 常规传输的提供商。若某个提供商需要完全自定义的请求执行器，那就是另一类更深层的扩展接口。 ## API 密钥轮换 -- 支持对选定提供商进行通用提供商轮换。 +- 支持针对选定提供商的通用提供商轮换。 - 可通过以下方式配置多个密钥： - `OPENCLAW_LIVE__KEY`（单个 live 覆盖，最高优先级） - `_API_KEYS`（逗号或分号分隔列表） - `_API_KEY`（主密钥） - `_API_KEY_*`（编号列表，例如 `_API_KEY_1`） -- 对于 Google 提供商，`GOOGLE_API_KEY` 也会作为回退项包含在内。 -- 密钥选择顺序会保留优先级并对值去重。 -- 只有在收到速率限制响应时，才会使用下一个密钥重试请求（例如 `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`，或周期性的用量限制消息）。 +- 对于 Google 提供商，还会将 `GOOGLE_API_KEY` 作为回退项。 +- 密钥选择顺序会保留优先级并去重。 +- 仅在遇到速率限制响应时，请求才会使用下一个密钥重试（例如 `429`、`rate_limit`、`quota`、`resource exhausted`、“Too many concurrent requests”、`ThrottlingException`、“concurrency limit reached”、`workers_ai ... quota limit exceeded`，或周期性的用量限制消息）。 - 非速率限制失败会立即失败；不会尝试密钥轮换。 -- 当所有候选密钥都失败时，返回最后一次尝试的最终错误。 +- 当所有候选密钥都失败时，将返回最后一次尝试的最终错误。 ## 内置提供商（pi-ai 目录） -OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** `models.providers` 配置；只需设置凭证并选择模型。 +OpenClaw 附带 pi‑ai 目录。这些提供商**无需**配置 `models.providers`；只需设置凭证并选择模型。 ### OpenAI - 提供商：`openai` - 凭证：`OPENAI_API_KEY` -- 可选轮换：`OPENAI_API_KEYS`、`OPENAI_API_KEY_1`、`OPENAI_API_KEY_2`，以及 `OPENCLAW_LIVE_OPENAI_KEY`（单一覆盖） +- 可选轮换：`OPENAI_API_KEYS`、`OPENAI_API_KEY_1`、`OPENAI_API_KEY_2`，以及 `OPENCLAW_LIVE_OPENAI_KEY`（单个覆盖） - 示例模型：`openai/gpt-5.4`、`openai/gpt-5.4-pro` - CLI：`openclaw onboard --auth-choice openai-api-key` -- 默认传输是 `auto`（优先 WebSocket，回退 SSE） +- 默认传输为 `auto`（优先 WebSocket，回退到 SSE） - 可通过 `agents.defaults.models["openai/"].params.transport` 为每个模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`） -- OpenAI Responses WebSocket 预热默认通过 `params.openaiWsWarmup` 启用（`true`/`false`） -- 可通过 `agents.defaults.models["openai/"].params.serviceTier` 启用 OpenAI 优先级处理 -- `/fast` 和 `params.fastMode` 会将直接 `openai/*` Responses 请求映射到 `api.openai.com` 上的 `service_tier=priority` -- 当你想使用显式层级而不是共享的 `/fast` 开关时，请使用 `params.serviceTier` +- OpenAI Responses WebSocket 预热默认通过 `params.openaiWsWarmup`（`true`/`false`）启用 +- 可通过 `agents.defaults.models["openai/"].params.serviceTier` 启用 OpenAI 优先处理 +- `/fast` 和 `params.fastMode` 会将直接 `openai/*` Responses 请求映射为 `api.openai.com` 上的 `service_tier=priority` +- 如果你想使用显式层级而不是共享的 `/fast` 开关，请使用 `params.serviceTier` - 隐藏的 OpenClaw 归因请求头（`originator`、`version`、`User-Agent`）仅适用于发往 `api.openai.com` 的原生 OpenAI 流量，不适用于通用 OpenAI 兼容代理 -- 原生 OpenAI 路由还会保留 Responses `store`、提示缓存提示和 OpenAI 推理兼容负载整形；代理路由则不会 -- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意屏蔽，因为 live OpenAI API 会拒绝它；Spark 被视为仅限 Codex +- 原生 OpenAI 路由还会保留 Responses `store`、提示缓存提示和 OpenAI 推理兼容载荷整形；代理路由则不会 +- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中会被有意抑制，因为 live OpenAI API 会拒绝它；Spark 被视为仅限 Codex ```json5 { @@ -155,12 +155,12 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** `models.providers` - 提供商：`anthropic` - 凭证：`ANTHROPIC_API_KEY` -- 可选轮换：`ANTHROPIC_API_KEYS`、`ANTHROPIC_API_KEY_1`、`ANTHROPIC_API_KEY_2`，以及 `OPENCLAW_LIVE_ANTHROPIC_KEY`（单一覆盖） +- 可选轮换：`ANTHROPIC_API_KEYS`、`ANTHROPIC_API_KEY_1`、`ANTHROPIC_API_KEY_2`，以及 `OPENCLAW_LIVE_ANTHROPIC_KEY`（单个覆盖） - 示例模型：`anthropic/claude-opus-4-6` - CLI：`openclaw onboard --auth-choice apiKey` -- 直接公共 Anthropic 请求支持共享的 `/fast` 开关和 `params.fastMode`，包括发送到 `api.anthropic.com` 的基于 API 密钥和 OAuth 认证的流量；OpenClaw 会将其映射为 Anthropic `service_tier`（`auto` 与 `standard_only`） -- Anthropic 说明：Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允许，因此除非 Anthropic 发布新政策，否则 OpenClaw 将 Claude CLI 复用和 `claude -p` 用法视为此集成的受支持方式。 -- Anthropic setup-token 仍作为受支持的 OpenClaw 令牌路径保留，但 OpenClaw 现在在可用时优先使用 Claude CLI 复用和 `claude -p`。 +- 直接公共 Anthropic 请求支持共享的 `/fast` 开关和 `params.fastMode`，包括发送到 `api.anthropic.com` 的 API 密钥和 OAuth 认证流量；OpenClaw 会将其映射到 Anthropic `service_tier`（`auto` 与 `standard_only`） +- Anthropic 说明：Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 使用方式再次被允许，因此除非 Anthropic 发布新政策，否则 OpenClaw 会将 Claude CLI 复用和 `claude -p` 用法视为此集成下被认可的方式。 +- Anthropic setup-token 仍可作为受支持的 OpenClaw 令牌路径使用，但 OpenClaw 现在在可用时更倾向于使用 Claude CLI 复用和 `claude -p`。 ```json5 { @@ -174,14 +174,14 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** `models.providers` - 凭证：OAuth（ChatGPT） - 示例模型：`openai-codex/gpt-5.4` - CLI：`openclaw onboard --auth-choice openai-codex` 或 `openclaw models auth login --provider openai-codex` -- 默认传输是 `auto`（优先 WebSocket，回退 SSE） +- 默认传输为 `auto`（优先 WebSocket，回退到 SSE） - 可通过 `agents.defaults.models["openai-codex/"].params.transport` 为每个模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`） -- `params.serviceTier` 也会转发到原生 Codex Responses 请求（`chatgpt.com/backend-api`）上 +- `params.serviceTier` 也会在原生 Codex Responses 请求（`chatgpt.com/backend-api`）上转发 - 隐藏的 OpenClaw 归因请求头（`originator`、`version`、`User-Agent`）仅附加到发往 `chatgpt.com/backend-api` 的原生 Codex 流量，不适用于通用 OpenAI 兼容代理 -- 与直接 `openai/*` 共享同一个 `/fast` 开关和 `params.fastMode` 配置；OpenClaw 会将其映射到 `service_tier=priority` -- 当 Codex OAuth 目录暴露该模型时，`openai-codex/gpt-5.3-codex-spark` 仍然可用；取决于授权资格 -- `openai-codex/gpt-5.4` 保持原生 `contextWindow = 1050000` 和默认运行时 `contextTokens = 272000`；可通过 `models.providers.openai-codex.models[].contextTokens` 覆盖运行时上限 -- 策略说明：OpenAI Codex OAuth 明确支持像 OpenClaw 这样的外部工具/工作流。 +- 与直接 `openai/*` 共用相同的 `/fast` 开关和 `params.fastMode` 配置；OpenClaw 会将其映射到 `service_tier=priority` +- 当 Codex OAuth 目录公开它时，`openai-codex/gpt-5.3-codex-spark` 仍可用；是否可用取决于权限 +- `openai-codex/gpt-5.4` 保留原生 `contextWindow = 1050000` 和默认运行时 `contextTokens = 272000`；可通过 `models.providers.openai-codex.models[].contextTokens` 覆盖运行时上限 +- 策略说明：OpenAI Codex OAuth 明确支持用于 OpenClaw 这类外部工具/工作流。 ```json5 { @@ -203,7 +203,7 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** `models.providers` ### 其他订阅式托管选项 -- [Qwen Cloud](/zh-CN/providers/qwen)：Qwen Cloud 提供商接口，以及 Alibaba DashScope 和 Coding Plan 端点映射 +- [Qwen Cloud](/zh-CN/providers/qwen)：Qwen Cloud 提供商界面，以及 Alibaba DashScope 和 Coding Plan 端点映射 - [MiniMax](/zh-CN/providers/minimax)：MiniMax Coding Plan OAuth 或 API 密钥访问 - [GLM Models](/zh-CN/providers/glm)：Z.AI Coding Plan 或通用 API 端点 @@ -225,9 +225,9 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** `models.providers` - 提供商：`google` - 凭证：`GEMINI_API_KEY` -- 可选轮换：`GEMINI_API_KEYS`、`GEMINI_API_KEY_1`、`GEMINI_API_KEY_2`、`GOOGLE_API_KEY` 回退项，以及 `OPENCLAW_LIVE_GEMINI_KEY`（单一覆盖） +- 可选轮换：`GEMINI_API_KEYS`、`GEMINI_API_KEY_1`、`GEMINI_API_KEY_2`、`GOOGLE_API_KEY` 回退，以及 `OPENCLAW_LIVE_GEMINI_KEY`（单个覆盖） - 示例模型：`google/gemini-3.1-pro-preview`、`google/gemini-3-flash-preview` -- 兼容性：使用 `google/gemini-3.1-flash-preview` 的旧版 OpenClaw 配置会被规范化为 `google/gemini-3-flash-preview` +- 兼容性：使用 `google/gemini-3.1-flash-preview` 的旧版 OpenClaw 配置会被标准化为 `google/gemini-3-flash-preview` - CLI：`openclaw onboard --auth-choice gemini-api-key` - 直接 Gemini 运行还接受 `agents.defaults.models["google/"].params.cachedContent`（或旧版 `cached_content`），用于转发提供商原生的 `cachedContents/...` 句柄；Gemini 缓存命中会显示为 OpenClaw `cacheRead` @@ -235,7 +235,7 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** `models.providers` - 提供商：`google-vertex`、`google-gemini-cli` - 凭证：Vertex 使用 gcloud ADC；Gemini CLI 使用其 OAuth 流程 -- 注意：OpenClaw 中的 Gemini CLI OAuth 是非官方集成。一些用户报告称，在使用第三方客户端后其 Google 账号受到了限制。请先查看 Google 条款，并在你决定继续时使用非关键账号。 +- 注意：OpenClaw 中的 Gemini CLI OAuth 是非官方集成。一些用户报告称，在使用第三方客户端后，其 Google 账号受到了限制。请查看 Google 条款，如果你选择继续，请使用非关键账号。 - Gemini CLI OAuth 作为内置 `google` 插件的一部分提供。 - 先安装 Gemini CLI： - `brew install gemini-cli` @@ -243,9 +243,9 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** `models.providers` - 启用：`openclaw plugins enable google` - 登录：`openclaw models auth login --provider google-gemini-cli --set-default` - 默认模型：`google-gemini-cli/gemini-3-flash-preview` - - 注意：你**不需要**将 client id 或 secret 粘贴到 `openclaw.json` 中。CLI 登录流程会将令牌存储在 Gateway 网关主机上的凭证配置档中。 + - 注意：你**不需要**将 client id 或 secret 粘贴到 `openclaw.json` 中。CLI 登录流程会将令牌存储在 Gateway 网关主机上的凭证配置文件中。 - 如果登录后请求失败，请在 Gateway 网关主机上设置 `GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_CLOUD_PROJECT_ID`。 - - Gemini CLI JSON 回复从 `response` 解析；用量会回退到 `stats`，其中 `stats.cached` 会被规范化为 OpenClaw `cacheRead`。 + - Gemini CLI JSON 回复会从 `response` 中解析；用量会回退到 `stats`，其中 `stats.cached` 会被标准化为 OpenClaw `cacheRead`。 ### Z.AI（GLM） @@ -253,43 +253,45 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** `models.providers` - 凭证：`ZAI_API_KEY` - 示例模型：`zai/glm-5.1` - CLI：`openclaw onboard --auth-choice zai-api-key` - - 别名：`z.ai/*` 和 `z-ai/*` 会被规范化为 `zai/*` - - `zai-api-key` 会自动检测匹配的 Z.AI 端点；`zai-coding-global`、`zai-coding-cn`、`zai-global` 和 `zai-cn` 会强制使用特定接口 + - 别名：`z.ai/*` 和 `z-ai/*` 会标准化为 `zai/*` + - `zai-api-key` 会自动检测匹配的 Z.AI 端点；`zai-coding-global`、`zai-coding-cn`、`zai-global` 和 `zai-cn` 会强制使用特定界面 -### Vercel AI Gateway +### Vercel AI Gateway 网关 - 提供商：`vercel-ai-gateway` - 凭证：`AI_GATEWAY_API_KEY` -- 示例模型：`vercel-ai-gateway/anthropic/claude-opus-4.6` +- 示例模型：`vercel-ai-gateway/anthropic/claude-opus-4.6`、 + `vercel-ai-gateway/moonshotai/kimi-k2.6` - CLI：`openclaw onboard --auth-choice ai-gateway-api-key` -### Kilo Gateway +### Kilo Gateway 网关 - 提供商：`kilocode` - 凭证：`KILOCODE_API_KEY` - 示例模型：`kilocode/kilo/auto` - CLI：`openclaw onboard --auth-choice kilocode-api-key` - Base URL：`https://api.kilo.ai/api/gateway/` -- 静态回退目录附带 `kilocode/kilo/auto`；实时 `https://api.kilo.ai/api/gateway/models` 发现还可以进一步扩展运行时目录。 -- `kilocode/kilo/auto` 背后的精确上游路由由 Kilo Gateway 负责，不是 OpenClaw 中硬编码的。 +- 静态回退目录附带 `kilocode/kilo/auto`；live + `https://api.kilo.ai/api/gateway/models` 发现还可以进一步扩展运行时目录。 +- `kilocode/kilo/auto` 背后的确切上游路由由 Kilo Gateway 网关负责，不会在 OpenClaw 中硬编码。 有关设置详情，请参见 [/providers/kilocode](/zh-CN/providers/kilocode)。 ### 其他内置提供商插件 - OpenRouter：`openrouter`（`OPENROUTER_API_KEY`） -- 示例模型：`openrouter/auto` -- 只有当请求实际发往 `openrouter.ai` 时，OpenClaw 才会应用 OpenRouter 文档中的应用归因请求头 -- OpenRouter 特有的 Anthropic `cache_control` 标记同样只会在已验证的 OpenRouter 路由上启用，而不是任意代理 URL -- OpenRouter 仍然走代理风格的 OpenAI 兼容路径，因此原生仅限 OpenAI 的请求整形（`serviceTier`、Responses `store`、提示缓存提示、OpenAI 推理兼容负载）不会被转发 -- 基于 Gemini 的 OpenRouter 引用仅保留代理 Gemini thought-signature 清理；原生 Gemini 重放校验和引导重写保持关闭 -- Kilo Gateway：`kilocode`（`KILOCODE_API_KEY`） +- 示例模型：`openrouter/auto`、`openrouter/moonshotai/kimi-k2.6` +- 仅当请求实际发往 `openrouter.ai` 时，OpenClaw 才会应用 OpenRouter 文档中说明的应用归因请求头 +- OpenRouter 特有的 Anthropic `cache_control` 标记同样仅限已验证的 OpenRouter 路由，而不是任意代理 URL +- OpenRouter 仍然使用代理风格的 OpenAI 兼容路径，因此不会转发仅适用于原生 OpenAI 的请求整形（`serviceTier`、Responses `store`、提示缓存提示、OpenAI 推理兼容载荷） +- 基于 Gemini 的 OpenRouter 引用仅保留代理 Gemini thought-signature 清理；原生 Gemini 重放校验和引导重写仍保持关闭 +- Kilo Gateway 网关：`kilocode`（`KILOCODE_API_KEY`） - 示例模型：`kilocode/kilo/auto` - 基于 Gemini 的 Kilo 引用保留相同的代理 Gemini thought-signature 清理路径；`kilocode/kilo/auto` 和其他不支持代理推理的提示会跳过代理推理注入 - MiniMax：`minimax`（API 密钥）和 `minimax-portal`（OAuth） - 凭证：`minimax` 使用 `MINIMAX_API_KEY`；`minimax-portal` 使用 `MINIMAX_OAUTH_TOKEN` 或 `MINIMAX_API_KEY` - 示例模型：`minimax/MiniMax-M2.7` 或 `minimax-portal/MiniMax-M2.7` -- MiniMax 新手引导/API 密钥设置会写入显式 M2.7 模型定义，并包含 `input: ["text", "image"]`；在该提供商配置具体化之前，内置提供商目录会将聊天引用保持为仅文本 +- MiniMax 新手引导/API 密钥设置会写入显式的 M2.7 模型定义，并带有 `input: ["text", "image"]`；内置提供商目录会在该提供商配置生成之前，将聊天引用保留为仅文本 - Moonshot：`moonshot`（`MOONSHOT_API_KEY`） - 示例模型：`moonshot/kimi-k2.6` - Kimi Coding：`kimi`（`KIMI_API_KEY` 或 `KIMICODE_API_KEY`） @@ -307,37 +309,42 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** `models.providers` - Venice：`venice`（`VENICE_API_KEY`） - Xiaomi：`xiaomi`（`XIAOMI_API_KEY`） - 示例模型：`xiaomi/mimo-v2-flash` -- Vercel AI Gateway：`vercel-ai-gateway`（`AI_GATEWAY_API_KEY`） +- Vercel AI Gateway 网关：`vercel-ai-gateway`（`AI_GATEWAY_API_KEY`） - Hugging Face Inference：`huggingface`（`HUGGINGFACE_HUB_TOKEN` 或 `HF_TOKEN`） -- Cloudflare AI Gateway：`cloudflare-ai-gateway`（`CLOUDFLARE_AI_GATEWAY_API_KEY`） +- Cloudflare AI Gateway 网关：`cloudflare-ai-gateway`（`CLOUDFLARE_AI_GATEWAY_API_KEY`） - Volcengine：`volcengine`（`VOLCANO_ENGINE_API_KEY`） - 示例模型：`volcengine-plan/ark-code-latest` -- BytePlus（国际版）：`byteplus`（`BYTEPLUS_API_KEY`） +- BytePlus：`byteplus`（`BYTEPLUS_API_KEY`） - 示例模型：`byteplus-plan/ark-code-latest` - xAI：`xai`（`XAI_API_KEY`） - 原生内置 xAI 请求使用 xAI Responses 路径 - - `/fast` 或 `params.fastMode: true` 会将 `grok-3`、`grok-3-mini`、`grok-4` 和 `grok-4-0709` 重写为它们的 `*-fast` 变体 - - `tool_stream` 默认开启；将 `agents.defaults.models["xai/"].params.tool_stream` 设为 `false` 可关闭它 + - `/fast` 或 `params.fastMode: true` 会将 `grok-3`、`grok-3-mini`、 + `grok-4` 和 `grok-4-0709` 重写为其 `*-fast` 变体 + - `tool_stream` 默认开启；设置 + `agents.defaults.models["xai/"].params.tool_stream` 为 `false` 可 + 禁用它 - Mistral：`mistral`（`MISTRAL_API_KEY`） - 示例模型：`mistral/mistral-large-latest` - CLI：`openclaw onboard --auth-choice mistral-api-key` - Groq：`groq`（`GROQ_API_KEY`） - Cerebras：`cerebras`（`CEREBRAS_API_KEY`） - - Cerebras 上的 GLM 模型使用 id `zai-glm-4.7` 和 `zai-glm-4.6`。 + - Cerebras 上的 GLM 模型使用 ID `zai-glm-4.7` 和 `zai-glm-4.6`。 - OpenAI 兼容 Base URL：`https://api.cerebras.ai/v1`。 - GitHub Copilot：`github-copilot`（`COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN`） -- Hugging Face Inference 示例模型：`huggingface/deepseek-ai/DeepSeek-R1`；CLI：`openclaw onboard --auth-choice huggingface-api-key`。参见 [Hugging Face（Inference）](/zh-CN/providers/huggingface)。 +- Hugging Face Inference 示例模型：`huggingface/deepseek-ai/DeepSeek-R1`；CLI：`openclaw onboard --auth-choice huggingface-api-key`。请参见 [Hugging Face（Inference）](/zh-CN/providers/huggingface)。 ## 通过 `models.providers` 配置的提供商（自定义/Base URL） -使用 `models.providers`（或 `models.json`）添加**自定义**提供商或 OpenAI/Anthropic 兼容代理。 +使用 `models.providers`（或 `models.json`）添加**自定义**提供商或 +OpenAI/Anthropic 兼容代理。 下面许多内置提供商插件已经发布了默认目录。 -只有当你想覆盖默认 Base URL、请求头或模型列表时，才使用显式 `models.providers.` 条目。 +仅当你想覆盖默认的 base URL、headers 或模型列表时，才使用显式的 `models.providers.` 条目。 ### Moonshot AI（Kimi） -Moonshot 作为内置提供商插件提供。默认使用内置提供商，只有在你需要覆盖 Base URL 或模型元数据时，才添加显式 `models.providers.moonshot` 条目： +Moonshot 作为内置提供商插件提供。默认使用内置提供商，只有在你 +需要覆盖 base URL 或模型元数据时，才添加显式的 `models.providers.moonshot` 条目： - 提供商：`moonshot` - 凭证：`MOONSHOT_API_KEY` @@ -392,13 +399,13 @@ Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点： } ``` -旧版 `kimi/k2p5` 仍然作为兼容模型 id 被接受。 +旧版 `kimi/k2p5` 仍然接受，作为兼容模型 ID。 ### Volcano Engine（Doubao） -Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访问。 +Volcano Engine（火山引擎）提供对 Doubao 和中国其他模型的访问。 -- 提供商：`volcengine`（编程方案：`volcengine-plan`） +- 提供商：`volcengine`（编码方案：`volcengine-plan`） - 凭证：`VOLCANO_ENGINE_API_KEY` - 示例模型：`volcengine-plan/ark-code-latest` - CLI：`openclaw onboard --auth-choice volcengine-api-key` @@ -411,9 +418,12 @@ Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访 } ``` -新手引导默认使用编程接口，但通用的 `volcengine/*` 目录会同时注册。 +新手引导默认使用编码界面，但通用 `volcengine/*` +目录也会同时注册。 -在新手引导/配置模型选择器中，Volcengine 凭证选项会优先显示 `volcengine/*` 和 `volcengine-plan/*` 条目。如果这些模型尚未加载，OpenClaw 会回退到未筛选的目录，而不是显示一个空的提供商范围选择器。 +在新手引导/配置模型选择器中，Volcengine 凭证选项会优先显示 +`volcengine/*` 和 `volcengine-plan/*` 条目。如果这些模型尚未加载， +OpenClaw 会回退到未筛选的目录，而不是显示一个空的提供商范围选择器。 可用模型： @@ -423,7 +433,7 @@ Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访 - `volcengine/glm-4-7-251222`（GLM 4.7） - `volcengine/deepseek-v3-2-251201`（DeepSeek V3.2 128K） -编程模型（`volcengine-plan`）： +编码模型（`volcengine-plan`）： - `volcengine-plan/ark-code-latest` - `volcengine-plan/doubao-seed-code` @@ -435,7 +445,7 @@ Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访 BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问。 -- 提供商：`byteplus`（编程方案：`byteplus-plan`） +- 提供商：`byteplus`（编码方案：`byteplus-plan`） - 凭证：`BYTEPLUS_API_KEY` - 示例模型：`byteplus-plan/ark-code-latest` - CLI：`openclaw onboard --auth-choice byteplus-api-key` @@ -448,9 +458,12 @@ BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问。 } ``` -新手引导默认使用编程接口，但通用的 `byteplus/*` 目录会同时注册。 +新手引导默认使用编码界面，但通用 `byteplus/*` +目录也会同时注册。 -在新手引导/配置模型选择器中，BytePlus（国际版）凭证选项会优先显示 `byteplus/*` 和 `byteplus-plan/*` 条目。如果这些模型尚未加载，OpenClaw 会回退到未筛选的目录，而不是显示一个空的提供商范围选择器。 +在新手引导/配置模型选择器中，BytePlus（国际版）凭证选项会优先显示 +`byteplus/*` 和 `byteplus-plan/*` 条目。如果这些模型尚未加载， +OpenClaw 会回退到未筛选的目录，而不是显示一个空的提供商范围选择器。 可用模型： @@ -458,7 +471,7 @@ BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问。 - `byteplus/kimi-k2-5-260127`（Kimi K2.5） - `byteplus/glm-4-7-251222`（GLM 4.7） -编程模型（`byteplus-plan`）： +编码模型（`byteplus-plan`）： - `byteplus-plan/ark-code-latest` - `byteplus-plan/doubao-seed-code` @@ -502,22 +515,25 @@ MiniMax 通过 `models.providers` 配置，因为它使用自定义端点： - MiniMax OAuth（CN）：`--auth-choice minimax-cn-oauth` - MiniMax API 密钥（Global）：`--auth-choice minimax-global-api` - MiniMax API 密钥（CN）：`--auth-choice minimax-cn-api` -- 凭证：`minimax` 使用 `MINIMAX_API_KEY`；`minimax-portal` 使用 `MINIMAX_OAUTH_TOKEN` 或 `MINIMAX_API_KEY` +- 凭证：`minimax` 使用 `MINIMAX_API_KEY`；`minimax-portal` 使用 `MINIMAX_OAUTH_TOKEN` 或 + `MINIMAX_API_KEY` 有关设置详情、模型选项和配置片段，请参见 [/providers/minimax](/zh-CN/providers/minimax)。 -在 MiniMax 的 Anthropic 兼容流式路径上，OpenClaw 默认禁用 thinking，除非你显式设置它；而 `/fast on` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。 +在 MiniMax 的 Anthropic 兼容流式路径上，OpenClaw 默认禁用 thinking， +除非你显式设置它；并且 `/fast on` 会将 +`MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。 -插件自有能力划分： +由插件拥有的能力拆分： -- 文本/聊天默认保持在 `minimax/MiniMax-M2.7` +- 文本/聊天默认仍使用 `minimax/MiniMax-M2.7` - 图像生成使用 `minimax/image-01` 或 `minimax-portal/image-01` -- 图像理解由两个 MiniMax 凭证路径上的插件自有 `MiniMax-VL-01` 负责 -- Web 搜索仍使用提供商 id `minimax` +- 图像理解在两种 MiniMax 凭证路径上都使用由插件拥有的 `MiniMax-VL-01` +- Web 搜索仍使用提供商 ID `minimax` ### LM Studio -LM Studio 作为一个使用原生 API 的内置提供商插件提供： +LM Studio 作为内置提供商插件提供，并使用原生 API： - 提供商：`lmstudio` - 凭证：`LM_API_TOKEN` @@ -533,7 +549,8 @@ LM Studio 作为一个使用原生 API 的内置提供商插件提供： } ``` -OpenClaw 使用 LM Studio 原生的 `/api/v1/models` 和 `/api/v1/models/load` 进行发现 + 自动加载，并默认使用 `/v1/chat/completions` 进行推理。 +OpenClaw 使用 LM Studio 原生的 `/api/v1/models` 和 `/api/v1/models/load` +进行发现 + 自动加载，并默认使用 `/v1/chat/completions` 进行推理。 有关设置和故障排除，请参见 [/providers/lmstudio](/zh-CN/providers/lmstudio)。 ### Ollama @@ -546,7 +563,7 @@ Ollama 作为内置提供商插件提供，并使用 Ollama 的原生 API： - 安装：[https://ollama.com/download](https://ollama.com/download) ```bash -# Install Ollama, then pull a model: +# 安装 Ollama，然后拉取一个模型： ollama pull llama3.3 ``` @@ -558,17 +575,19 @@ ollama pull llama3.3 } ``` -当你通过 `OLLAMA_API_KEY` 明确启用时，系统会在 `http://127.0.0.1:11434` 本地检测 Ollama，并且内置提供商插件会将 Ollama 直接加入 `openclaw onboard` 和模型选择器。有关新手引导、云端/本地模式和自定义配置，请参见 [/providers/ollama](/zh-CN/providers/ollama)。 +当你通过 `OLLAMA_API_KEY` 选择启用时，系统会在本地 `http://127.0.0.1:11434` 检测 Ollama，并且内置提供商插件会将 Ollama 直接添加到 +`openclaw onboard` 和模型选择器中。有关新手引导、云端/本地模式和自定义配置，请参见 [/providers/ollama](/zh-CN/providers/ollama)。 ### vLLM -vLLM 作为内置提供商插件提供，适用于本地/自托管的 OpenAI 兼容服务器： +vLLM 作为内置提供商插件提供，适用于本地/自托管的 OpenAI 兼容 +服务器： - 提供商：`vllm` - 凭证：可选（取决于你的服务器） -- 默认 Base URL：`http://127.0.0.1:8000/v1` +- 默认 base URL：`http://127.0.0.1:8000/v1` -要在本地启用自动发现（如果你的服务器不强制要求凭证，任意值都可以）： +要在本地选择启用自动发现（如果你的服务器不强制要求凭证，则任意值都可）： ```bash export VLLM_API_KEY="vllm-local" @@ -588,13 +607,15 @@ export VLLM_API_KEY="vllm-local" ### SGLang -SGLang 作为内置提供商插件提供，适用于高速自托管的 OpenAI 兼容服务器： +SGLang 作为内置提供商插件提供，适用于快速的自托管 +OpenAI 兼容服务器： - 提供商：`sglang` - 凭证：可选（取决于你的服务器） -- 默认 Base URL：`http://127.0.0.1:30000/v1` +- 默认 base URL：`http://127.0.0.1:30000/v1` -要在本地启用自动发现（如果你的服务器不强制要求凭证，任意值都可以）： +要在本地选择启用自动发现（如果你的服务器不强制要求 +凭证，则任意值都可）： ```bash export SGLANG_API_KEY="sglang-local" @@ -621,7 +642,7 @@ export SGLANG_API_KEY="sglang-local" agents: { defaults: { model: { primary: "lmstudio/my-local-model" }, - models: { "lmstudio/my-local-model": { alias: "Local" } }, + models: { "lmstudio/my-local-model": { alias: "本地" } }, }, }, models: { @@ -633,7 +654,7 @@ export SGLANG_API_KEY="sglang-local" models: [ { id: "my-local-model", - name: "Local Model", + name: "本地模型", reasoning: false, input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, @@ -649,18 +670,18 @@ export SGLANG_API_KEY="sglang-local" 说明： -- 对于自定义提供商，`reasoning`、`input`、`cost`、`contextWindow` 和 `maxTokens` 都是可选的。 +- 对于自定义提供商，`reasoning`、`input`、`cost`、`contextWindow` 和 `maxTokens` 都是可选项。 省略时，OpenClaw 默认值为： - `reasoning: false` - `input: ["text"]` - `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }` - `contextWindow: 200000` - `maxTokens: 8192` -- 建议：设置与你的代理/模型限制一致的显式值。 -- 对于非原生端点上的 `api: "openai-completions"`（任何 host 不是 `api.openai.com` 的非空 `baseUrl`），OpenClaw 会强制 `compat.supportsDeveloperRole: false`，以避免提供商因不支持 `developer` 角色而返回 400 错误。 -- 代理风格的 OpenAI 兼容路由也会跳过原生 OpenAI 专用的请求整形：没有 `service_tier`，没有 Responses `store`，没有提示缓存提示，没有 OpenAI 推理兼容负载整形，也没有隐藏的 OpenClaw 归因请求头。 -- 如果 `baseUrl` 为空或省略，OpenClaw 会保留默认 OpenAI 行为（其解析结果为 `api.openai.com`）。 -- 为了安全起见，在非原生 `openai-completions` 端点上，显式的 `compat.supportsDeveloperRole: true` 仍然会被覆盖。 +- 建议：设置与你的代理/模型限制相匹配的显式值。 +- 对于非原生端点上的 `api: "openai-completions"`（任意非空 `baseUrl`，且其主机不是 `api.openai.com`），OpenClaw 会强制设置 `compat.supportsDeveloperRole: false`，以避免提供商因不支持 `developer` 角色而返回 400 错误。 +- 代理风格的 OpenAI 兼容路由也会跳过仅适用于原生 OpenAI 的请求整形：没有 `service_tier`、没有 Responses `store`、没有提示缓存提示、没有 OpenAI 推理兼容载荷整形，也没有隐藏的 OpenClaw 归因请求头。 +- 如果 `baseUrl` 为空/省略，OpenClaw 会保留默认的 OpenAI 行为（会解析为 `api.openai.com`）。 +- 出于安全考虑，即使显式设置了 `compat.supportsDeveloperRole: true`，在非原生 `openai-completions` 端点上仍会被覆盖。 ## CLI 示例 @@ -670,11 +691,11 @@ openclaw models set opencode/claude-opus-4-6 openclaw models list ``` -另请参见：[/gateway/configuration](/zh-CN/gateway/configuration) 了解完整配置示例。 +另请参见：[/gateway/configuration](/zh-CN/gateway/configuration)，了解完整配置示例。 ## 相关内容 -- [Models](/zh-CN/concepts/models) — 模型配置和别名 -- [Model Failover](/zh-CN/concepts/model-failover) — 回退链和重试行为 -- [Configuration Reference](/zh-CN/gateway/configuration-reference#agent-defaults) — 模型配置键 -- [Providers](/zh-CN/providers) — 按提供商划分的设置指南 +- [Models](/zh-CN/concepts/models) —— 模型配置与别名 +- [Model Failover](/zh-CN/concepts/model-failover) —— 回退链与重试行为 +- [Configuration Reference](/zh-CN/gateway/configuration-reference#agent-defaults) —— 模型配置键 +- [Providers](/zh-CN/providers) —— 各提供商设置指南 diff --git a/docs/zh-CN/concepts/models.md b/docs/zh-CN/concepts/models.md index 03438765d..5b62ae1df 100644 --- a/docs/zh-CN/concepts/models.md +++ b/docs/zh-CN/concepts/models.md @@ -1,47 +1,47 @@ --- read_when: - - 添加或修改模型 CLI（models list/set/scan/aliases/fallbacks） + - 添加或修改模型 CLI（`models list`/`set`/`scan`/`aliases`/`fallbacks`） - 更改模型回退行为或选择 UX - 更新模型扫描探测（工具/图像） -summary: 模型 CLI：列出、设置、别名、回退、扫描、状态 +summary: 模型 CLI：列表、设置、别名、回退、扫描、状态 title: 模型 CLI x-i18n: - generated_at: "2026-04-06T00:52:21Z" + generated_at: "2026-04-22T03:53:27Z" model: gpt-5.4 provider: openai - source_hash: 299602ccbe0c3d6bbdb2deab22bc60e1300ef6843ed0b8b36be574cc0213c155 + source_hash: 0cf7a17a20bea66e5e8dce134ed08b483417bc70ed875e796609d850aa79280e source_path: concepts/models.md workflow: 15 --- # 模型 CLI -有关凭证配置轮换、冷却时间及其与回退机制如何交互，请参阅 [/concepts/model-failover](/zh-CN/concepts/model-failover)。 -有关提供商的快速概览和示例，请参阅 [/concepts/model-providers](/zh-CN/concepts/model-providers)。 +关于凭证配置文件轮换、冷却时间，以及它们如何与回退机制交互，请参见 [/concepts/model-failover](/zh-CN/concepts/model-failover)。 +提供商快速概览与示例：[/concepts/model-providers](/zh-CN/concepts/model-providers)。 -## 模型选择的工作方式 +## 模型选择如何工作 OpenClaw 按以下顺序选择模型： -1. **主** 模型（`agents.defaults.model.primary` 或 `agents.defaults.model`）。 -2. `agents.defaults.model.fallbacks` 中的 **回退** 模型（按顺序）。 -3. **提供商凭证故障切换** 会先在提供商内部发生，然后才会切换到下一个模型。 +1. **主模型**（`agents.defaults.model.primary` 或 `agents.defaults.model`）。 +2. `agents.defaults.model.fallbacks` 中的**回退模型**（按顺序）。 +3. **提供商凭证回退**会在提供商内部发生，然后才会切换到下一个模型。 相关项： - `agents.defaults.models` 是 OpenClaw 可使用模型的允许列表/目录（以及别名）。 -- `agents.defaults.imageModel` **仅在** 主模型无法接受图像时使用。 -- `agents.defaults.pdfModel` 由 `pdf` 工具使用。如果省略，该工具会依次回退到 `agents.defaults.imageModel`，然后是已解析的会话/默认模型。 -- `agents.defaults.imageGenerationModel` 由共享图像生成功能使用。如果省略，`image_generate` 仍可推断出一个由凭证支持的提供商默认值。它会先尝试当前默认提供商，再按提供商 ID 顺序尝试其余已注册的图像生成提供商。如果你设置了特定的提供商/模型，也请同时配置该提供商的凭证/API 密钥。 -- `agents.defaults.musicGenerationModel` 由共享音乐生成功能使用。如果省略，`music_generate` 仍可推断出一个由凭证支持的提供商默认值。它会先尝试当前默认提供商，再按提供商 ID 顺序尝试其余已注册的音乐生成提供商。如果你设置了特定的提供商/模型，也请同时配置该提供商的凭证/API 密钥。 -- `agents.defaults.videoGenerationModel` 由共享视频生成功能使用。如果省略，`video_generate` 仍可推断出一个由凭证支持的提供商默认值。它会先尝试当前默认提供商，再按提供商 ID 顺序尝试其余已注册的视频生成提供商。如果你设置了特定的提供商/模型，也请同时配置该提供商的凭证/API 密钥。 -- 每个智能体的默认值可通过 `agents.list[].model` 及绑定覆盖 `agents.defaults.model`（参见 [/concepts/multi-agent](/zh-CN/concepts/multi-agent)）。 +- `agents.defaults.imageModel` **仅在**主模型不能接受图像时使用。 +- `agents.defaults.pdfModel` 由 `pdf` 工具使用。如果省略，该工具会回退到 `agents.defaults.imageModel`，然后回退到已解析的会话/默认模型。 +- `agents.defaults.imageGenerationModel` 用于共享的图像生成功能。如果省略，`image_generate` 仍可推断出一个由凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的图像生成提供商。如果你设置了特定的提供商/模型，也请配置该提供商的凭证/API 密钥。 +- `agents.defaults.musicGenerationModel` 用于共享的音乐生成功能。如果省略，`music_generate` 仍可推断出一个由凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的音乐生成提供商。如果你设置了特定的提供商/模型，也请配置该提供商的凭证/API 密钥。 +- `agents.defaults.videoGenerationModel` 用于共享的视频生成功能。如果省略，`video_generate` 仍可推断出一个由凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的视频生成提供商。如果你设置了特定的提供商/模型，也请配置该提供商的凭证/API 密钥。 +- 每个智能体的默认值可以通过 `agents.list[].model` 加上绑定来覆盖 `agents.defaults.model`（参见 [/concepts/multi-agent](/zh-CN/concepts/multi-agent)）。 ## 快速模型策略 -- 将主模型设置为你可用的最强最新一代模型。 -- 对成本/延迟敏感的任务和风险较低的聊天使用回退模型。 -- 对启用了工具的智能体或不受信任的输入，避免使用较旧/较弱的模型层级。 +- 将你的主模型设为你可用的、最新一代中能力最强的模型。 +- 对成本/延迟敏感的任务和风险较低的聊天，使用回退模型。 +- 对于启用工具的智能体或不可信输入，避免使用较旧/较弱的模型层级。 ## 新手引导（推荐） @@ -65,18 +65,18 @@ openclaw onboard 模型引用会被规范化为小写。像 `z.ai/*` 这样的提供商别名会规范化为 `zai/*`。 -提供商配置示例（包括 OpenCode）见 +提供商配置示例（包括 OpenCode）位于 [/providers/opencode](/zh-CN/providers/opencode)。 ## “Model is not allowed”（以及为什么回复会停止） -如果设置了 `agents.defaults.models`，它就会成为 `/model` 和会话覆盖的**允许列表**。当用户选择的模型不在该允许列表中时，OpenClaw 会返回： +如果设置了 `agents.defaults.models`，它就会成为 `/model` 和会话覆盖的**允许列表**。当用户选择了不在该允许列表中的模型时，OpenClaw 会返回： ``` Model "provider/model" is not allowed. Use /model to list available models. ``` -这会发生在生成正常回复**之前**，因此消息看起来会像“没有响应”。修复方法是执行以下任一操作： +这会发生在生成正常回复**之前**，所以消息看起来可能像是“没有响应”。解决方法是： - 将该模型添加到 `agents.defaults.models`，或 - 清除允许列表（移除 `agents.defaults.models`），或 @@ -98,7 +98,7 @@ Model "provider/model" is not allowed. Use /model to list available models. ## 在聊天中切换模型（`/model`） -你可以为当前会话切换模型，而无需重启： +你可以在不重启的情况下为当前会话切换模型： ``` /model @@ -111,22 +111,22 @@ Model "provider/model" is not allowed. Use /model to list available models. 说明： - `/model`（以及 `/model list`）是一个紧凑的编号选择器（模型家族 + 可用提供商）。 -- 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，其中包含提供商和模型下拉菜单，以及提交步骤。 -- `/model <#>` 会从该选择器中进行选择。 +- 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，其中包含提供商和模型下拉菜单，以及一个提交步骤。 +- `/model <#>` 会从该选择器中选择。 - `/model` 会立即持久化新的会话选择。 - 如果智能体处于空闲状态，下一次运行会立即使用新模型。 -- 如果某次运行已经处于活动状态，OpenClaw 会将实时切换标记为待处理，并且仅在一个干净的重试点重启到新模型。 -- 如果工具活动或回复输出已经开始，待处理切换可能会一直排队，直到稍后的重试机会或下一次用户轮次。 +- 如果某次运行已处于活动状态，OpenClaw 会将实时切换标记为待处理，并且只会在一个干净的重试点重启到新模型。 +- 如果工具活动或回复输出已经开始，待处理切换可能会一直排队，直到后续重试机会或下一个用户轮次。 - `/model status` 是详细视图（凭证候选项，以及在已配置时显示提供商端点 `baseUrl` + `api` 模式）。 -- 模型引用会通过按**第一个** `/` 拆分来解析。输入 `/model ` 时请使用 `provider/model`。 +- 模型引用通过按**第一个** `/` 分割来解析。输入 `/model ` 时，请使用 `provider/model`。 - 如果模型 ID 本身包含 `/`（OpenRouter 风格），你必须包含提供商前缀（例如：`/model openrouter/moonshotai/kimi-k2`）。 - 如果你省略提供商，OpenClaw 会按以下顺序解析输入： 1. 别名匹配 - 2. 该精确无前缀模型 ID 的唯一已配置提供商匹配 - 3. 已弃用的回退行为：回退到已配置的默认提供商 + 2. 该确切无前缀模型 ID 的唯一已配置提供商匹配 + 3. 已弃用的回退：使用已配置的默认提供商 如果该提供商不再公开已配置的默认模型，OpenClaw 会改为回退到第一个已配置的提供商/模型，以避免暴露过时的、已移除提供商默认值。 -完整命令行为/配置： [斜杠命令](/zh-CN/tools/slash-commands)。 +完整命令行为/配置： [Slash commands](/zh-CN/tools/slash-commands)。 ## CLI 命令 @@ -155,7 +155,7 @@ openclaw models image-fallbacks clear ### `models list` -默认显示已配置的模型。有用的标志： +默认显示已配置的模型。常用标志： - `--all`：完整目录 - `--local`：仅本地提供商 @@ -163,16 +163,18 @@ openclaw models image-fallbacks clear - `--plain`：每行一个模型 - `--json`：机器可读输出 +`--all` 会在配置凭证之前包含内置的、由提供商拥有的静态目录条目，因此仅发现用途的视图也可以显示那些在你添加匹配提供商凭证之前不可用的模型。 + ### `models status` -显示已解析的主模型、回退模型、图像模型，以及已配置提供商的凭证概览。它还会显示在凭证存储中找到的配置文件的 OAuth 过期状态（默认在 24 小时内到期时警告）。`--plain` 仅打印已解析的主模型。 -OAuth 状态始终会显示（并包含在 `--json` 输出中）。如果某个已配置提供商没有凭证，`models status` 会打印 **Missing auth** 部分。 -JSON 包含 `auth.oauth`（警告窗口 + 配置文件）和 `auth.providers`（每个提供商的实际凭证，包括由环境变量支持的凭证）。`auth.oauth` 仅表示凭证存储配置文件的健康状态；仅使用环境变量的提供商不会出现在其中。 -对自动化场景请使用 `--check`（缺失/已过期时退出 `1`，即将过期时退出 `2`）。 -使用 `--probe` 可进行实时凭证检查；探测行可能来自凭证配置文件、环境变量凭证或 `models.json`。 -如果显式的 `auth.order.` 省略了某个已存储配置文件，探测会报告 `excluded_by_auth_order`，而不是尝试它。如果存在凭证，但无法为该提供商解析出可探测的模型，探测会报告 `status: no_model`。 +显示已解析的主模型、回退模型、图像模型，以及已配置提供商的凭证概览。它还会显示在凭证存储中找到的配置文件的 OAuth 过期状态（默认会在 24 小时内到期时发出警告）。`--plain` 仅打印已解析的主模型。 +OAuth 状态始终会显示（并包含在 `--json` 输出中）。如果某个已配置的提供商没有凭证，`models status` 会打印一个 **Missing auth** 部分。 +JSON 包含 `auth.oauth`（警告窗口 + 配置文件）和 `auth.providers`（每个提供商的生效凭证，包括基于环境变量的凭证）。`auth.oauth` 仅表示凭证存储中配置文件的健康状态；仅使用环境变量的提供商不会出现在其中。 +将 `--check` 用于自动化（缺失/已过期时退出码为 `1`，即将过期时为 `2`）。 +将 `--probe` 用于实时凭证检查；探测行可能来自凭证配置文件、环境变量凭证或 `models.json`。 +如果显式的 `auth.order.` 省略了某个已存储配置文件，探测会报告 `excluded_by_auth_order`，而不是尝试它。如果凭证存在，但该提供商无法解析出可探测的模型，探测会报告 `status: no_model`。 -凭证选择取决于提供商/账户。对于始终在线的 Gateway 网关主机，API 密钥通常最可预测；也支持复用 Claude CLI 以及现有的 Anthropic OAuth/token 配置文件。 +凭证选择取决于提供商/账户。对于始终在线的 Gateway 网关主机，API 密钥通常是最可预测的；也支持复用 Claude CLI 和现有 Anthropic OAuth/令牌配置文件。 示例（Claude CLI）： @@ -192,13 +194,13 @@ openclaw models status - `--max-age-days `：跳过较旧模型 - `--provider `：提供商前缀筛选 - `--max-candidates `：回退列表大小 -- `--set-default`：将 `agents.defaults.model.primary` 设置为第一个选择项 -- `--set-image`：将 `agents.defaults.imageModel.primary` 设置为第一个图像选择项 +- `--set-default`：将 `agents.defaults.model.primary` 设为第一个选中项 +- `--set-image`：将 `agents.defaults.imageModel.primary` 设为第一个图像选中项 -探测需要 OpenRouter API 密钥（来自凭证配置文件或 -`OPENROUTER_API_KEY`）。如果没有密钥，请使用 `--no-probe` 仅列出候选项。 +探测需要 OpenRouter API 密钥（来自凭证配置文件或 `OPENROUTER_API_KEY`）。 +如果没有密钥，请使用 `--no-probe` 仅列出候选项。 -扫描结果按以下规则排序： +扫描结果按以下顺序排序： 1. 图像支持 2. 工具延迟 @@ -209,32 +211,32 @@ openclaw models status - OpenRouter `/models` 列表（筛选 `:free`） - 需要来自凭证配置文件或 `OPENROUTER_API_KEY` 的 OpenRouter API 密钥（参见 [/environment](/zh-CN/help/environment)） -- 可选筛选条件：`--max-age-days`、`--min-params`、`--provider`、`--max-candidates` +- 可选筛选项：`--max-age-days`、`--min-params`、`--provider`、`--max-candidates` - 探测控制：`--timeout`、`--concurrency` -在 TTY 中运行时，你可以以交互方式选择回退模型。在非交互模式下，传入 `--yes` 以接受默认值。 +在 TTY 中运行时，你可以交互式选择回退模型。在非交互模式下，传入 `--yes` 以接受默认值。 ## 模型注册表（`models.json`） -`models.providers` 中的自定义提供商会被写入智能体目录下的 `models.json`（默认为 `~/.openclaw/agents//agent/models.json`）。除非将 `models.mode` 设置为 `replace`，否则默认会合并该文件。 +`models.providers` 中的自定义提供商会写入智能体目录下的 `models.json`（默认是 `~/.openclaw/agents//agent/models.json`）。默认情况下，该文件会被合并，除非 `models.mode` 被设置为 `replace`。 -匹配提供商 ID 的合并模式优先级： +对于匹配的提供商 ID，合并模式优先级如下： - 智能体 `models.json` 中已存在的非空 `baseUrl` 优先。 -- 智能体 `models.json` 中的非空 `apiKey` 仅在该提供商在当前配置/凭证配置文件上下文中不受 SecretRef 管理时优先。 -- 受 SecretRef 管理的提供商 `apiKey` 值会根据源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`），而不是持久化已解析的密钥。 -- 受 SecretRef 管理的提供商请求头值会根据源标记刷新（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`）。 +- 智能体 `models.json` 中非空的 `apiKey` 仅在该提供商在当前配置/凭证配置文件上下文中不是 SecretRef 管理时优先。 +- SecretRef 管理的提供商 `apiKey` 值会从源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`），而不是持久化已解析的密钥。 +- SecretRef 管理的提供商请求头值会从源标记刷新（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`）。 - 智能体中为空或缺失的 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。 -- 其他提供商字段会根据配置和规范化后的目录数据进行刷新。 +- 其他提供商字段会从配置和规范化目录数据中刷新。 -标记持久化以源为准：OpenClaw 会根据活动源配置快照（预解析）写入标记，而不是根据已解析的运行时密钥值写入。 -这适用于 OpenClaw 重新生成 `models.json` 的所有场景，包括 `openclaw agent` 这样的命令驱动路径。 +标记持久化以源为准：OpenClaw 会根据活动源配置快照（解析前）写入标记，而不是根据运行时已解析的密钥值写入。 +这适用于 OpenClaw 重新生成 `models.json` 的任何场景，包括像 `openclaw agent` 这样的命令驱动路径。 ## 相关内容 -- [模型提供商](/zh-CN/concepts/model-providers) — 提供商路由与凭证 -- [模型故障切换](/zh-CN/concepts/model-failover) — 回退链 -- [图像生成](/zh-CN/tools/image-generation) — 图像模型配置 -- [音乐生成](/zh-CN/tools/music-generation) — 音乐模型配置 -- [视频生成](/zh-CN/tools/video-generation) — 视频模型配置 -- [配置参考](/zh-CN/gateway/configuration-reference#agent-defaults) — 模型配置键名 +- [Model Providers](/zh-CN/concepts/model-providers) — 提供商路由与凭证 +- [Model Failover](/zh-CN/concepts/model-failover) — 回退链 +- [Image Generation](/zh-CN/tools/image-generation) — 图像模型配置 +- [Music Generation](/zh-CN/tools/music-generation) — 音乐模型配置 +- [Video Generation](/zh-CN/tools/video-generation) — 视频模型配置 +- [Configuration Reference](/zh-CN/gateway/configuration-reference#agent-defaults) — 模型配置键名 diff --git a/docs/zh-CN/plugins/sdk-provider-plugins.md b/docs/zh-CN/plugins/sdk-provider-plugins.md index d0f8afcc1..e24b9d1df 100644 --- a/docs/zh-CN/plugins/sdk-provider-plugins.md +++ b/docs/zh-CN/plugins/sdk-provider-plugins.md @@ -1,37 +1,37 @@ --- read_when: - 你正在构建一个新的模型提供商插件 - - 你想为 OpenClaw 添加一个兼容 OpenAI 的代理或自定义 LLM + - 你想将与 OpenAI 兼容的代理或自定义 LLM 添加到 OpenClaw 中 - 你需要了解提供商认证、目录和运行时钩子 sidebarTitle: Provider Plugins summary: 为 OpenClaw 构建模型提供商插件的分步指南 title: 构建提供商插件 x-i18n: - generated_at: "2026-04-21T08:24:18Z" + generated_at: "2026-04-22T03:53:26Z" model: gpt-5.4 provider: openai - source_hash: 08494658def4a003a1e5752f68d9232bfbbbf76348cf6f319ea1a6855c2ae439 + source_hash: 99376d2abfc968429ed19f03451beb0f3597d57c703f2ce60c6c51220656e850 source_path: plugins/sdk-provider-plugins.md workflow: 15 --- # 构建提供商插件 -本指南将带你构建一个提供商插件，为 OpenClaw 添加一个模型提供商（LLM）。完成后，你将拥有一个带有模型目录、API 密钥认证和动态模型解析的提供商。 +本指南将带你构建一个提供商插件，为 OpenClaw 添加一个模型提供商（LLM）。完成后，你将拥有一个具备模型目录、API 密钥认证和动态模型解析能力的提供商。 - 如果你之前没有构建过任何 OpenClaw 插件，请先阅读 [入门指南](/zh-CN/plugins/building-plugins)，了解基本的软件包结构和清单设置。 + 如果你之前没有构建过任何 OpenClaw 插件，请先阅读 [入门指南](/zh-CN/plugins/building-plugins)，了解基础包结构和清单设置。 - 提供商插件会将模型添加到 OpenClaw 的常规推理循环中。如果该模型必须通过一个原生智能体守护进程来运行，并由它负责线程、压缩或工具事件，请将该提供商与一个 [智能体 harness](/zh-CN/plugins/sdk-agent-harness) 搭配使用，而不是把守护进程协议细节放进核心中。 + 提供商插件会将模型接入 OpenClaw 的常规推理循环。如果模型必须通过一个拥有线程、压缩或工具事件控制权的原生智能体守护进程运行，请将该提供商与一个 [agent harness](/zh-CN/plugins/sdk-agent-harness) 搭配使用，而不是把守护进程协议细节放进核心中。 ## 演练 - + ```json package.json { @@ -89,12 +89,12 @@ x-i18n: ``` - 清单声明了 `providerAuthEnvVars`，这样 OpenClaw 就可以在不加载你的插件运行时的情况下检测凭证。当某个提供商变体应复用另一个提供商 id 的认证时，添加 `providerAuthAliases`。`modelSupport` 是可选的，它允许 OpenClaw 在运行时钩子存在之前，就通过像 `acme-large` 这样的简写模型 id 自动加载你的提供商插件。如果你要在 ClawHub 上发布该提供商，那么 `package.json` 中的这些 `openclaw.compat` 和 `openclaw.build` 字段是必需的。 + 该清单声明了 `providerAuthEnvVars`，这样 OpenClaw 无需加载你的插件运行时就能检测凭证。若某个提供商变体应复用另一个提供商 id 的认证，请添加 `providerAuthAliases`。`modelSupport` 是可选项，它允许 OpenClaw 在运行时钩子存在之前，就根据诸如 `acme-large` 这样的简写模型 id 自动加载你的提供商插件。如果你要在 ClawHub 上发布该提供商，则 `package.json` 中必须包含这些 `openclaw.compat` 和 `openclaw.build` 字段。 - 一个最小化的提供商需要 `id`、`label`、`auth` 和 `catalog`： + 一个最小可用的提供商需要 `id`、`label`、`auth` 和 `catalog`： ```typescript index.ts import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; @@ -103,7 +103,7 @@ x-i18n: export default definePluginEntry({ id: "acme-ai", name: "Acme AI", - description: "Acme AI 模型提供商", + description: "Acme AI model provider", register(api) { api.registerProvider({ id: "acme-ai", @@ -115,12 +115,12 @@ x-i18n: createProviderApiKeyAuthMethod({ providerId: "acme-ai", methodId: "api-key", - label: "Acme AI API 密钥", - hint: "来自你的 Acme AI 控制台的 API 密钥", + label: "Acme AI API key", + hint: "API key from your Acme AI dashboard", optionKey: "acmeAiApiKey", flagName: "--acme-ai-api-key", envVar: "ACME_AI_API_KEY", - promptMessage: "输入你的 Acme AI API 密钥", + promptMessage: "Enter your Acme AI API key", defaultModel: "acme-ai/acme-large", }), ], @@ -165,9 +165,11 @@ x-i18n: }); ``` - 这就是一个可工作的提供商。用户现在可以运行 `openclaw onboard --acme-ai-api-key `，并选择 `acme-ai/acme-large` 作为他们的模型。 + 这样就得到一个可用的提供商了。用户现在可以执行 + `openclaw onboard --acme-ai-api-key `，并选择 + `acme-ai/acme-large` 作为他们的模型。 - 如果上游提供商使用的控制令牌与 OpenClaw 不同，请添加一个小型的双向文本转换，而不是替换流路径： + 如果上游提供商使用的控制令牌与 OpenClaw 不同，请添加一个小型双向文本转换，而不是替换流式传输路径： ```typescript api.registerTextTransforms({ @@ -184,9 +186,9 @@ x-i18n: }); ``` - `input` 会在传输之前重写最终系统提示和文本消息内容。`output` 会在 OpenClaw 解析其自身控制标记或进行渠道投递之前，重写助手文本增量和最终文本。 + `input` 会在传输前重写最终系统提示词和文本消息内容。`output` 会在 OpenClaw 解析它自己的控制标记或进行渠道投递之前，重写助手文本增量和最终文本。 - 对于那些只注册一个带 API 密钥认证且附带单个目录支持运行时的文本提供商的内置提供商，优先使用更窄的 `defineSingleProviderPluginEntry(...)` 辅助函数： + 对于仅注册一个带 API 密钥认证的文本提供商，并带有单个基于目录的运行时的内置提供商，优先使用更窄的 `defineSingleProviderPluginEntry(...)` 辅助函数： ```typescript import { defineSingleProviderPluginEntry } from "openclaw/plugin-sdk/provider-entry"; @@ -194,19 +196,19 @@ x-i18n: export default defineSingleProviderPluginEntry({ id: "acme-ai", name: "Acme AI", - description: "Acme AI 模型提供商", + description: "Acme AI model provider", provider: { label: "Acme AI", docsPath: "/providers/acme-ai", auth: [ { methodId: "api-key", - label: "Acme AI API 密钥", - hint: "来自你的 Acme AI 控制台的 API 密钥", + label: "Acme AI API key", + hint: "API key from your Acme AI dashboard", optionKey: "acmeAiApiKey", flagName: "--acme-ai-api-key", envVar: "ACME_AI_API_KEY", - promptMessage: "输入你的 Acme AI API 密钥", + promptMessage: "Enter your Acme AI API key", defaultModel: "acme-ai/acme-large", }, ], @@ -216,23 +218,34 @@ x-i18n: baseUrl: "https://api.acme-ai.com/v1", models: [{ id: "acme-large", name: "Acme Large" }], }), + buildStaticProvider: () => ({ + api: "openai-completions", + baseUrl: "https://api.acme-ai.com/v1", + models: [{ id: "acme-large", name: "Acme Large" }], + }), }, }, }); ``` - 如果你的认证流程在新手引导期间还需要修补 `models.providers.*`、别名以及智能体默认模型，请使用 `openclaw/plugin-sdk/provider-onboard` 中的预设辅助函数。最窄的辅助函数包括 `createDefaultModelPresetAppliers(...)`、`createDefaultModelsPresetAppliers(...)` 和 `createModelCatalogPresetAppliers(...)`。 + `buildProvider` 是实时目录路径，在 OpenClaw 能解析真实提供商认证时使用。它可以执行提供商特定的发现逻辑。仅在需要展示安全的离线条目且尚未配置认证时使用 `buildStaticProvider`；它不能依赖凭证，也不能发起网络请求。OpenClaw 当前的 `models list --all` 显示只会对内置提供商插件执行静态目录，并且会使用空配置、空环境以及无智能体 / 工作区路径的上下文。 - 当某个提供商的原生端点在常规 `openai-completions` 传输上支持流式 usage 块时，优先使用 `openclaw/plugin-sdk/provider-catalog-shared` 中的共享目录辅助函数，而不是硬编码提供商 id 检查。`supportsNativeStreamingUsageCompat(...)` 和 `applyProviderNativeStreamingUsageCompat(...)` 会根据端点能力映射检测支持情况，因此原生 Moonshot/DashScope 风格的端点即使插件使用的是自定义提供商 id，也仍然可以选择启用。 + 如果你的认证流程在新手引导期间还需要修补 `models.providers.*`、别名以及智能体默认模型，请使用 `openclaw/plugin-sdk/provider-onboard` 中的预设辅助函数。最窄的辅助函数包括 + `createDefaultModelPresetAppliers(...)`、 + `createDefaultModelsPresetAppliers(...)` 和 + `createModelCatalogPresetAppliers(...)`。 + + 当某个提供商的原生端点在常规 `openai-completions` 传输上支持流式使用量块时，优先使用 `openclaw/plugin-sdk/provider-catalog-shared` 中的共享目录辅助函数，而不是硬编码提供商 id 判断。`supportsNativeStreamingUsageCompat(...)` 和 + `applyProviderNativeStreamingUsageCompat(...)` 会根据端点能力映射检测支持情况，因此即使插件使用自定义提供商 id，原生 Moonshot / DashScope 风格的端点也仍能选择启用。 - 如果你的提供商接受任意模型 id（比如代理或路由器），请添加 `resolveDynamicModel`： + 如果你的提供商接受任意模型 id（例如代理或路由器），请添加 `resolveDynamicModel`： ```typescript api.registerProvider({ - // ... 上面的 id、label、auth、catalog + // ... id, label, auth, catalog from above resolveDynamicModel: (ctx) => ({ id: ctx.modelId, @@ -249,14 +262,14 @@ x-i18n: }); ``` - 如果解析需要进行网络调用，请使用 `prepareDynamicModel` 来进行异步预热——在它完成后，`resolveDynamicModel` 会再次运行。 + 如果解析需要发起网络请求，请使用 `prepareDynamicModel` 进行异步预热——完成后会再次运行 `resolveDynamicModel`。 - + 大多数提供商只需要 `catalog` + `resolveDynamicModel`。随着你的提供商需求增加，再逐步添加钩子。 - 共享辅助构建器现在已经覆盖了最常见的重放/工具兼容性家族，因此插件通常不需要再逐个手动连接每个钩子： + 共享辅助构建器现在已覆盖最常见的回放 / 工具兼容性族，因此插件通常不需要手动逐个接线每个钩子： ```typescript import { buildProviderReplayFamilyHooks } from "openclaw/plugin-sdk/provider-model-shared"; @@ -276,15 +289,15 @@ x-i18n: }); ``` - 当前可用的重放家族： + 当前可用的回放族如下： - | 家族 | 会接入的内容 | + | 族 | 会接入的内容 | | --- | --- | - | `openai-compatible` | 面向兼容 OpenAI 的传输的共享 OpenAI 风格重放策略，包括工具调用 id 清理、assistant 优先顺序修复，以及传输所需的通用 Gemini 轮次校验 | - | `anthropic-by-model` | 按 `modelId` 选择的 Claude 感知重放策略，因此基于 Anthropic 消息的传输只有在解析后的模型确实是 Claude id 时，才会获得 Claude 专用的思维块清理 | - | `google-gemini` | 原生 Gemini 重放策略，加上 bootstrap 重放清理和带标签的推理输出模式 | - | `passthrough-gemini` | 面向通过兼容 OpenAI 的代理传输运行的 Gemini 模型的 Gemini thought-signature 清理；不会启用原生 Gemini 重放校验或 bootstrap 重写 | - | `hybrid-anthropic-openai` | 用于在一个插件中混合 Anthropic 消息和兼容 OpenAI 模型表面的提供商的混合策略；可选的仅 Claude 思维块丢弃仍然限定在 Anthropic 一侧 | + | `openai-compatible` | 面向与 OpenAI 兼容传输的共享 OpenAI 风格回放策略，包括工具调用 id 清洗、助手优先顺序修正，以及在传输需要时进行通用 Gemini 轮次校验 | + | `anthropic-by-model` | 根据 `modelId` 选择的 Claude 感知型回放策略，因此基于 Anthropic 消息的传输只会在解析出的模型实际是 Claude id 时才应用 Claude 特有的思考块清理 | + | `google-gemini` | 原生 Gemini 回放策略，加上引导回放清洗和带标签的推理输出模式 | + | `passthrough-gemini` | 适用于通过与 OpenAI 兼容的代理传输运行的 Gemini 模型的 Gemini thought-signature 清洗；不会启用原生 Gemini 回放校验或引导重写 | + | `hybrid-anthropic-openai` | 适用于在一个插件中混合 Anthropic 消息面和与 OpenAI 兼容模型面的提供商的混合策略；可选的仅 Claude 思考块丢弃仍然只作用于 Anthropic 一侧 | 真实的内置示例： @@ -294,17 +307,17 @@ x-i18n: - `minimax`：`hybrid-anthropic-openai` - `moonshot`、`ollama`、`xai` 和 `zai`：`openai-compatible` - 当前可用的流家族： + 当前可用的流式传输族如下： - | 家族 | 会接入的内容 | + | 族 | 会接入的内容 | | --- | --- | - | `google-thinking` | 在共享流路径上进行 Gemini thinking 负载规范化 | - | `kilocode-thinking` | 在共享代理流路径上为 Kilo 推理提供包装器，并且会为 `kilo/auto` 和不支持的代理推理 id 跳过注入的 thinking | - | `moonshot-thinking` | 根据配置和 `/think` 级别，对 Moonshot 二进制原生 thinking 负载进行映射 | - | `minimax-fast-mode` | 在共享流路径上进行 MiniMax fast-mode 模型重写 | - | `openai-responses-defaults` | 共享的原生 OpenAI/Codex Responses 包装器：归因头、`/fast`/`serviceTier`、文本详细程度、原生 Codex web 搜索、推理兼容负载整形，以及 Responses 上下文管理 | - | `openrouter-thinking` | 面向代理路由的 OpenRouter 推理包装器，并集中处理不支持模型/`auto` 跳过 | - | `tool-stream-default-on` | 面向像 Z.AI 这样希望默认启用工具流式传输、除非显式禁用的提供商的默认开启 `tool_stream` 包装器 | + | `google-thinking` | 在共享流式传输路径上进行 Gemini 思考负载规范化 | + | `kilocode-thinking` | 在共享代理流式传输路径上进行 Kilo 推理包装，其中 `kilo/auto` 和不受支持的代理推理 id 会跳过注入的 thinking | + | `moonshot-thinking` | 根据配置和 `/think` 级别进行 Moonshot 二进制原生 thinking 负载映射 | + | `minimax-fast-mode` | 在共享流式传输路径上进行 MiniMax 快速模式模型重写 | + | `openai-responses-defaults` | 共享原生 OpenAI / Codex Responses 包装器：归因请求头、`/fast` / `serviceTier`、文本详细程度、原生 Codex web 搜索、推理兼容负载整形，以及 Responses 上下文管理 | + | `openrouter-thinking` | 面向代理路由的 OpenRouter 推理包装器，并由中心统一处理不受支持模型 / `auto` 跳过逻辑 | + | `tool-stream-default-on` | 面向像 Z.AI 这类除非显式禁用否则希望启用工具流式传输的提供商的默认开启 `tool_stream` 包装器 | 真实的内置示例： @@ -316,44 +329,65 @@ x-i18n: - `openrouter`：`openrouter-thinking` - `zai`：`tool-stream-default-on` - `openclaw/plugin-sdk/provider-model-shared` 还导出了 replay family 枚举，以及这些家族所基于的共享辅助函数。常见的公共导出包括： + `openclaw/plugin-sdk/provider-model-shared` 还导出了 replay 族枚举，以及这些族所基于的共享辅助函数。常见的公共导出包括： - `ProviderReplayFamily` - `buildProviderReplayFamilyHooks(...)` - - 共享 replay 构建器，例如 `buildOpenAICompatibleReplayPolicy(...)`、`buildAnthropicReplayPolicyForModel(...)`、`buildGoogleGeminiReplayPolicy(...)` 和 `buildHybridAnthropicOrOpenAIReplayPolicy(...)` - - Gemini replay 辅助函数，例如 `sanitizeGoogleGeminiReplayHistory(...)` 和 `resolveTaggedReasoningOutputMode()` - - 端点/模型辅助函数，例如 `resolveProviderEndpoint(...)`、`normalizeProviderId(...)`、`normalizeGooglePreviewModelId(...)` 和 `normalizeNativeXaiModelId(...)` + - 共享 replay 构建器，例如 `buildOpenAICompatibleReplayPolicy(...)`、 + `buildAnthropicReplayPolicyForModel(...)`、 + `buildGoogleGeminiReplayPolicy(...)` 和 + `buildHybridAnthropicOrOpenAIReplayPolicy(...)` + - Gemini replay 辅助函数，例如 `sanitizeGoogleGeminiReplayHistory(...)` + 和 `resolveTaggedReasoningOutputMode()` + - 端点 / 模型辅助函数，例如 `resolveProviderEndpoint(...)`、 + `normalizeProviderId(...)`、`normalizeGooglePreviewModelId(...)` 和 + `normalizeNativeXaiModelId(...)` - `openclaw/plugin-sdk/provider-stream` 同时公开了 family 构建器，以及这些家族复用的公共包装器辅助函数。常见的公共导出包括： + `openclaw/plugin-sdk/provider-stream` 同时公开了族构建器，以及这些族复用的公共包装器辅助函数。常见的公共导出包括： - `ProviderStreamFamily` - `buildProviderStreamFamilyHooks(...)` - `composeProviderStreamWrappers(...)` - - 共享的 OpenAI/Codex 包装器，例如 `createOpenAIAttributionHeadersWrapper(...)`、`createOpenAIFastModeWrapper(...)`、`createOpenAIServiceTierWrapper(...)`、`createOpenAIResponsesContextManagementWrapper(...)` 和 `createCodexNativeWebSearchWrapper(...)` - - 共享的代理/提供商包装器，例如 `createOpenRouterWrapper(...)`、`createToolStreamWrapper(...)` 和 `createMinimaxFastModeWrapper(...)` + - 共享 OpenAI / Codex 包装器，例如 + `createOpenAIAttributionHeadersWrapper(...)`、 + `createOpenAIFastModeWrapper(...)`、 + `createOpenAIServiceTierWrapper(...)`、 + `createOpenAIResponsesContextManagementWrapper(...)` 和 + `createCodexNativeWebSearchWrapper(...)` + - 共享代理 / 提供商包装器，例如 `createOpenRouterWrapper(...)`、 + `createToolStreamWrapper(...)` 和 `createMinimaxFastModeWrapper(...)` - 一些流辅助函数会有意保持为提供商本地。当前的内置示例：`@openclaw/anthropic-provider` 通过其公共 `api.ts` / `contract-api.ts` 接缝导出 `wrapAnthropicProviderStream`、`resolveAnthropicBetas`、`resolveAnthropicFastMode`、`resolveAnthropicServiceTier`，以及更底层的 Anthropic 包装器构建器。这些辅助函数仍然保持 Anthropic 专属，因为它们还编码了 Claude OAuth beta 处理和 `context1m` 门控。 + 有些流式传输辅助函数会有意保留为提供商本地实现。当前内置示例：`@openclaw/anthropic-provider` 从其公共 `api.ts` / + `contract-api.ts` 接缝导出 `wrapAnthropicProviderStream`、 + `resolveAnthropicBetas`、`resolveAnthropicFastMode`、`resolveAnthropicServiceTier`，以及更底层的 Anthropic 包装器构建器。这些辅助函数仍保持为 Anthropic 专用，因为它们还编码了 Claude OAuth beta 处理和 `context1m` 门控。 - 其他内置提供商也会在行为无法在各家族之间清晰共享时，将传输专用包装器保留在本地。当前示例：内置 xAI 插件将原生 xAI Responses 整形保留在自己的 `wrapStreamFn` 中，包括 `/fast` 别名重写、默认 `tool_stream`、不支持的严格工具清理，以及 xAI 专属的推理负载移除。 + 其他内置提供商也会在行为无法在各族之间清晰共享时，将传输专用包装器保留在本地。当前示例：内置 xAI 插件将原生 xAI Responses 整形保留在它自己的 + `wrapStreamFn` 中，包括 `/fast` 别名重写、默认 `tool_stream`、不受支持的严格工具清理，以及移除 xAI 专用推理负载。 - `openclaw/plugin-sdk/provider-tools` 当前公开了一个共享工具模式家族，以及共享的 schema/兼容性辅助函数： + `openclaw/plugin-sdk/provider-tools` 目前公开了一个共享工具模式族，以及共享 schema / 兼容辅助函数： - - `ProviderToolCompatFamily` 记录了当前的共享 family 清单。 + - `ProviderToolCompatFamily` 记录了当前共享族清单。 - `buildProviderToolCompatFamilyHooks("gemini")` 会为需要 Gemini 安全工具 schema 的提供商接入 Gemini schema 清理 + 诊断。 - - `normalizeGeminiToolSchemas(...)` 和 `inspectGeminiToolSchemas(...)` 是底层的公共 Gemini schema 辅助函数。 - - `resolveXaiModelCompatPatch()` 返回内置的 xAI compat patch：`toolSchemaProfile: "xai"`、不支持的 schema 关键字、原生 `web_search` 支持，以及 HTML 实体工具调用参数解码。 - - `applyXaiModelCompat(model)` 会在解析后的模型到达运行器之前，对其应用同一个 xAI compat patch。 + - `normalizeGeminiToolSchemas(...)` 和 `inspectGeminiToolSchemas(...)` + 是底层的公共 Gemini schema 辅助函数。 + - `resolveXaiModelCompatPatch()` 返回内置的 xAI 兼容补丁： + `toolSchemaProfile: "xai"`、不受支持的 schema 关键字、原生 + `web_search` 支持，以及 HTML 实体工具调用参数解码。 + - `applyXaiModelCompat(model)` 会在解析出的模型到达运行器之前，将同一个 xAI 兼容补丁应用到该模型上。 - 真实的内置示例：xAI 插件使用 `normalizeResolvedModel` 加上 `contributeResolvedModelCompat`，以便让这份兼容性元数据由提供商自己维护，而不是在核心中硬编码 xAI 规则。 + 真实的内置示例：xAI 插件使用 `normalizeResolvedModel` 加上 + `contributeResolvedModelCompat`，以便让这些兼容元数据由提供商负责，而不是在核心中硬编码 xAI 规则。 - 同样的软件包根模式也支撑着其他内置提供商： + 同样的包根模式也支撑着其他内置提供商： - - `@openclaw/openai-provider`：`api.ts` 导出提供商构建器、默认模型辅助函数以及实时提供商构建器 - - `@openclaw/openrouter-provider`：`api.ts` 导出提供商构建器以及新手引导/配置辅助函数 + - `@openclaw/openai-provider`：`api.ts` 导出提供商构建器、 + 默认模型辅助函数，以及实时提供商构建器 + - `@openclaw/openrouter-provider`：`api.ts` 导出提供商构建器， + 以及新手引导 / 配置辅助函数 - 对于那些需要在每次推理调用之前进行令牌交换的提供商： + 对于那些在每次推理调用前都需要进行令牌交换的提供商： ```typescript prepareRuntimeAuth: async (ctx) => { @@ -384,8 +418,8 @@ x-i18n: }, ``` - - 对于那些需要在通用 HTTP 或 WebSocket 传输上添加原生请求/会话头或元数据的提供商： + + 对于那些需要在通用 HTTP 或 WebSocket 传输上附加原生请求 / 会话请求头或元数据的提供商： ```typescript resolveTransportTurnState: (ctx) => ({ @@ -405,8 +439,8 @@ x-i18n: }), ``` - - 对于那些暴露用量/计费数据的提供商： + + 对于那些公开使用量 / 计费数据的提供商： ```typescript resolveUsageAuth: async (ctx) => { @@ -421,73 +455,77 @@ x-i18n: - OpenClaw 会按这个顺序调用钩子。大多数提供商只会用到 2–3 个： + OpenClaw 会按如下顺序调用这些钩子。大多数提供商只会用到 2–3 个： - | # | 钩子 | 何时使用 | + | # | Hook | 何时使用 | | --- | --- | --- | - | 1 | `catalog` | 模型目录或默认 `baseUrl` | - | 2 | `applyConfigDefaults` | 在配置实体化期间应用由提供商拥有的全局默认值 | - | 3 | `normalizeModelId` | 在查找前清理旧版/预览版模型 id 别名 | - | 4 | `normalizeTransport` | 在通用模型组装前清理 provider-family `api` / `baseUrl` | + | 1 | `catalog` | 模型目录或基础 `baseUrl` 默认值 | + | 2 | `applyConfigDefaults` | 在配置具体化期间应用由提供商负责的全局默认值 | + | 3 | `normalizeModelId` | 在查找前清理旧版 / 预览模型 id 别名 | + | 4 | `normalizeTransport` | 在通用模型组装前清理提供商族的 `api` / `baseUrl` | | 5 | `normalizeConfig` | 规范化 `models.providers.` 配置 | - | 6 | `applyNativeStreamingUsageCompat` | 针对配置提供商的原生流式 usage compat 重写 | - | 7 | `resolveConfigApiKey` | 由提供商拥有的 env-marker 认证解析 | - | 8 | `resolveSyntheticAuth` | 本地/自托管或基于配置的合成认证 | - | 9 | `shouldDeferSyntheticProfileAuth` | 让 env/config 认证优先于较低级别的合成已存储配置文件占位符 | + | 6 | `applyNativeStreamingUsageCompat` | 针对配置提供商的原生流式使用量兼容重写 | + | 7 | `resolveConfigApiKey` | 由提供商负责的环境标记认证解析 | + | 8 | `resolveSyntheticAuth` | 本地 / 自托管或基于配置的合成认证 | + | 9 | `shouldDeferSyntheticProfileAuth` | 将合成的已存储配置文件占位符置于环境 / 配置认证之后 | | 10 | `resolveDynamicModel` | 接受任意上游模型 id | - | 11 | `prepareDynamicModel` | 解析前异步获取元数据 | - | 12 | `normalizeResolvedModel` | 在进入运行器之前进行传输重写 | + | 11 | `prepareDynamicModel` | 在解析前异步获取元数据 | + | 12 | `normalizeResolvedModel` | 在运行器之前进行传输重写 | 运行时回退说明： - - `normalizeConfig` 会先检查匹配的提供商，然后检查其他支持钩子的提供商插件，直到有一个实际更改了配置。 - 如果没有任何提供商钩子重写受支持的 Google family 配置项，内置的 Google 配置规范化器仍会生效。 - - `resolveConfigApiKey` 在提供商暴露该钩子时会使用提供商钩子。内置的 `amazon-bedrock` 路径在这里也有一个内建的 AWS env-marker 解析器，尽管 Bedrock 运行时认证本身仍然使用 AWS SDK 默认链。 - | 13 | `contributeResolvedModelCompat` | 为通过其他兼容传输提供的厂商模型提供 compat 标志 | + - `normalizeConfig` 会先检查匹配的提供商，然后再检查其他具备钩子能力的提供商插件，直到某个插件实际修改配置为止。 + 如果没有任何提供商钩子重写受支持的 Google 族配置项， + 仍会应用内置的 Google 配置规范化逻辑。 + - `resolveConfigApiKey` 在提供商暴露该钩子时会使用提供商钩子。内置的 + `amazon-bedrock` 路径在这里还带有内建的 AWS 环境标记解析器， + 尽管 Bedrock 运行时认证本身仍然使用 AWS SDK 默认链。 + | 13 | `contributeResolvedModelCompat` | 为运行在另一种兼容传输之后的厂商模型提供兼容标志 | | 14 | `capabilities` | 旧版静态能力包；仅用于兼容性 | - | 15 | `normalizeToolSchemas` | 在注册前进行由提供商拥有的工具 schema 清理 | - | 16 | `inspectToolSchemas` | 由提供商拥有的工具 schema 诊断 | + | 15 | `normalizeToolSchemas` | 在注册前进行由提供商负责的工具 schema 清理 | + | 16 | `inspectToolSchemas` | 由提供商负责的工具 schema 诊断 | | 17 | `resolveReasoningOutputMode` | 带标签与原生推理输出契约 | | 18 | `prepareExtraParams` | 默认请求参数 | - | 19 | `createStreamFn` | 完全自定义的 StreamFn 传输 | - | 20 | `wrapStreamFn` | 常规流路径上的自定义头/请求体包装器 | - | 21 | `resolveTransportTurnState` | 原生逐轮请求头/元数据 | - | 22 | `resolveWebSocketSessionPolicy` | 原生 WS 会话头/冷却时间 | + | 19 | `createStreamFn` | 完全自定义的 `StreamFn` 传输 | + | 20 | `wrapStreamFn` | 在常规流式传输路径上包装自定义请求头 / 请求体 | + | 21 | `resolveTransportTurnState` | 原生逐轮请求头 / 元数据 | + | 22 | `resolveWebSocketSessionPolicy` | 原生 WS 会话请求头 / 冷却策略 | | 23 | `formatApiKey` | 自定义运行时令牌形态 | | 24 | `refreshOAuth` | 自定义 OAuth 刷新 | | 25 | `buildAuthDoctorHint` | 认证修复指引 | - | 26 | `matchesContextOverflowError` | 由提供商拥有的溢出检测 | - | 27 | `classifyFailoverReason` | 由提供商拥有的限流/过载分类 | - | 28 | `isCacheTtlEligible` | 提示缓存 TTL 门控 | + | 26 | `matchesContextOverflowError` | 由提供商负责的上下文溢出检测 | + | 27 | `classifyFailoverReason` | 由提供商负责的限流 / 过载分类 | + | 28 | `isCacheTtlEligible` | 提示词缓存 TTL 门控 | | 29 | `buildMissingAuthMessage` | 自定义缺失认证提示 | | 30 | `suppressBuiltInModel` | 隐藏过时的上游条目 | | 31 | `augmentModelCatalog` | 合成的前向兼容条目 | - | 32 | `resolveThinkingProfile` | 模型专属 `/think` 选项集 | - | 33 | `isBinaryThinking` | 二进制 thinking 开/关兼容性 | + | 32 | `resolveThinkingProfile` | 模型特定的 `/think` 选项集 | + | 33 | `isBinaryThinking` | 二进制 thinking 开 / 关兼容性 | | 34 | `supportsXHighThinking` | `xhigh` 推理支持兼容性 | | 35 | `resolveDefaultThinkingLevel` | 默认 `/think` 策略兼容性 | - | 36 | `isModernModelRef` | 实时/smoke 模型匹配 | - | 37 | `prepareRuntimeAuth` | 推理前进行令牌交换 | - | 38 | `resolveUsageAuth` | 自定义用量凭证解析 | - | 39 | `fetchUsageSnapshot` | 自定义用量端点 | - | 40 | `createEmbeddingProvider` | 用于 memory/search 的提供商自有嵌入适配器 | - | 41 | `buildReplayPolicy` | 自定义转录重放/压缩策略 | - | 42 | `sanitizeReplayHistory` | 在通用清理之后进行提供商专属 replay 重写 | - | 43 | `validateReplayTurns` | 在嵌入式运行器之前进行严格的 replay-turn 校验 | + | 36 | `isModernModelRef` | 实时 / smoke 模型匹配 | + | 37 | `prepareRuntimeAuth` | 推理前的令牌交换 | + | 38 | `resolveUsageAuth` | 自定义使用量凭证解析 | + | 39 | `fetchUsageSnapshot` | 自定义使用量端点 | + | 40 | `createEmbeddingProvider` | 由提供商负责的 embedding 适配器，用于记忆 / 搜索 | + | 41 | `buildReplayPolicy` | 自定义转录 replay / 压缩策略 | + | 42 | `sanitizeReplayHistory` | 通用清理后的提供商专用 replay 重写 | + | 43 | `validateReplayTurns` | 在嵌入式运行器之前进行严格 replay 轮次校验 | | 44 | `onModelSelected` | 选择模型后的回调（例如遥测） | - 提示调优说明： + 提示词调优说明： - - `resolveSystemPromptContribution` 允许提供商为某个模型 family 注入具备缓存感知能力的系统提示指引。如果该行为属于某个单独的提供商/模型 family，并且应保留稳定/动态缓存拆分，优先使用它，而不是 `before_prompt_build`。 + - `resolveSystemPromptContribution` 允许提供商为某个模型族注入具备缓存感知能力的系统提示词指导。当某项行为属于单一提供商 / 模型族，并且需要保留稳定 / 动态缓存拆分时，优先使用它，而不是 `before_prompt_build`。 - 如需详细说明和真实示例，请参阅 [内部机制：提供商运行时钩子](/zh-CN/plugins/architecture#provider-runtime-hooks)。 + 如需查看详细说明和真实示例，请参见 + [Internals: Provider Runtime Hooks](/zh-CN/plugins/architecture#provider-runtime-hooks)。 - 提供商插件除了文本推理之外，还可以注册语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取和 web 搜索： + 提供商插件除了文本推理外，还可以注册语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取和 web 搜索： ```typescript register(api) { @@ -570,7 +608,7 @@ x-i18n: api.registerWebFetchProvider({ id: "acme-ai-fetch", label: "Acme Fetch", - hint: "通过 Acme 的渲染后端抓取页面。", + hint: "Fetch pages through Acme's rendering backend.", envVars: ["ACME_FETCH_API_KEY"], placeholder: "acme-...", signupUrl: "https://acme.example.com/fetch", @@ -581,7 +619,7 @@ x-i18n: acme.apiKey = value; }, createTool: () => ({ - description: "通过 Acme Fetch 抓取页面。", + description: "Fetch a page through Acme Fetch.", parameters: {}, execute: async (args) => ({ content: [] }), }), @@ -595,11 +633,16 @@ x-i18n: } ``` - OpenClaw 将这类插件归类为 **hybrid-capability** 插件。这是公司级插件（每个厂商一个插件）的推荐模式。参见 [内部机制：能力归属](/zh-CN/plugins/architecture#capability-ownership-model)。 + OpenClaw 会将其归类为 **hybrid-capability** 插件。这是公司插件（每个供应商一个插件）的推荐模式。参见 + [Internals: Capability Ownership](/zh-CN/plugins/architecture#capability-ownership-model)。 - 对于视频生成，优先使用上面展示的按模式区分的能力结构：`generate`、`imageToVideo` 和 `videoToVideo`。像 `maxInputImages`、`maxInputVideos` 和 `maxDurationSeconds` 这样的扁平聚合字段不足以清晰地声明变换模式支持或已禁用模式。 + 对于视频生成，优先使用上面展示的具备模式感知能力的能力结构： + `generate`、`imageToVideo` 和 `videoToVideo`。像 + `maxInputImages`、`maxInputVideos` 和 `maxDurationSeconds` 这样的扁平聚合字段，不足以清晰表达变换模式支持或已禁用模式。 - 音乐生成提供商也应遵循相同模式：`generate` 用于仅基于提示词的生成，`edit` 用于基于参考图像的生成。像 `maxInputImages`、`supportsLyrics` 和 `supportsFormat` 这样的扁平聚合字段不足以声明 edit 支持；显式的 `generate` / `edit` 块才是预期契约。 + 音乐生成提供商也应遵循相同模式： + `generate` 用于仅基于提示词的生成，`edit` 用于基于参考图像的生成。像 `maxInputImages`、 + `supportsLyrics` 和 `supportsFormat` 这样的扁平聚合字段，不足以表达编辑支持；显式的 `generate` / `edit` 块才是预期契约。 @@ -640,41 +683,42 @@ x-i18n: ## 发布到 ClawHub -提供商插件的发布方式与其他外部代码插件相同： +提供商插件的发布方式与任何其他外部代码插件相同： ```bash clawhub package publish your-org/your-plugin --dry-run clawhub package publish your-org/your-plugin ``` -这里不要使用旧版的仅限 skill 的发布别名；插件包应使用 `clawhub package publish`。 +这里不要使用旧版仅 Skills 的发布别名；插件包应使用 +`clawhub package publish`。 ## 文件结构 ``` /acme-ai/ -├── package.json # openclaw.providers 元数据 -├── openclaw.plugin.json # 带提供商认证元数据的清单 +├── package.json # openclaw.providers metadata +├── openclaw.plugin.json # 带有提供商认证元数据的清单 ├── index.ts # definePluginEntry + registerProvider └── src/ ├── provider.test.ts # 测试 - └── usage.ts # 用量端点（可选） + └── usage.ts # 使用量端点（可选） ``` ## 目录顺序参考 -`catalog.order` 控制你的目录相对于内置提供商何时合并： +`catalog.order` 控制你的目录相对于内置提供商的合并时机： -| 顺序 | 时机 | 使用场景 | +| Order | 时机 | 使用场景 | | --------- | ------------- | ----------------------------------------------- | -| `simple` | 第一轮 | 纯 API 密钥提供商 | -| `profile` | 在 simple 之后 | 受认证配置文件控制的提供商 | -| `paired` | 在 profile 之后 | 合成多个相关条目 | -| `late` | 最后一轮 | 覆盖现有提供商（冲突时胜出） | +| `simple` | 第一轮 | 普通 API 密钥提供商 | +| `profile` | 在 `simple` 之后 | 受认证配置文件控制的提供商 | +| `paired` | 在 `profile` 之后 | 合成多个相关条目 | +| `late` | 最后一轮 | 覆盖现有提供商（冲突时获胜） | ## 后续步骤 - [渠道插件](/zh-CN/plugins/sdk-channel-plugins) — 如果你的插件也提供一个渠道 -- [SDK 概览](/zh-CN/plugins/sdk-runtime) — `api.runtime` 辅助函数（TTS、搜索、子智能体） +- [SDK 运行时](/zh-CN/plugins/sdk-runtime) — `api.runtime` 辅助函数（TTS、搜索、subagent） - [SDK 概览](/zh-CN/plugins/sdk-overview) — 完整的子路径导入参考 -- [插件内部机制](/zh-CN/plugins/architecture#provider-runtime-hooks) — 钩子细节和内置示例 +- [Plugin Internals](/zh-CN/plugins/architecture#provider-runtime-hooks) — 钩子细节和内置示例 diff --git a/docs/zh-CN/providers/openrouter.md b/docs/zh-CN/providers/openrouter.md index dae8e5e5c..7a6e529ff 100644 --- a/docs/zh-CN/providers/openrouter.md +++ b/docs/zh-CN/providers/openrouter.md @@ -1,21 +1,21 @@ --- read_when: - - 你想用一个 API 密钥访问多个 LLM】【。 - - 你想在 OpenClaw 中通过 OpenRouter 运行模型】【。 + - 你希望用一个 API 密钥访问多种 LLM + - 你希望在 OpenClaw 中通过 OpenRouter 运行模型 summary: 使用 OpenRouter 的统一 API 在 OpenClaw 中访问多种模型 title: OpenRouter x-i18n: - generated_at: "2026-04-12T10:38:57Z" + generated_at: "2026-04-22T03:53:24Z" model: gpt-5.4 provider: openai - source_hash: 9083c30b9e9846a9d4ef071c350576d4c3083475f4108871eabbef0b9bb9a368 + source_hash: 3a8d1e6191d98e3f5284ebc77e0b8b855a04f3fbed09786d6125b622333ac807 source_path: providers/openrouter.md workflow: 15 --- # OpenRouter -OpenRouter 提供了一个**统一 API**，可通过单个端点和 API 密钥将请求路由到多种模型。它兼容 OpenAI，因此大多数 OpenAI SDK 只需切换基础 URL 即可使用。 +OpenRouter 提供**统一 API**，可通过单个端点和 API 密钥将请求路由到多种模型。它兼容 OpenAI，因此大多数 OpenAI SDK 只需切换基础 URL 即可使用。 ## 入门指南 @@ -29,7 +29,7 @@ OpenRouter 提供了一个**统一 API**，可通过单个端点和 API 密钥 ``` - 新手引导默认使用 `openrouter/auto`。你稍后可以选择一个具体模型： + 新手引导默认使用 `openrouter/auto`。你之后可以改为选择具体模型： ```bash openclaw models set openrouter// @@ -54,14 +54,23 @@ OpenRouter 提供了一个**统一 API**，可通过单个端点和 API 密钥 ## 模型引用 -模型引用遵循 `openrouter//` 模式。完整的可用提供商和模型列表，请参阅 [/concepts/model-providers](/zh-CN/concepts/model-providers)。 +模型引用遵循 `openrouter//` 格式。有关可用提供商和模型的完整列表，请参阅 [/concepts/model-providers](/zh-CN/concepts/model-providers)。 -## 身份验证和请求头 +内置回退示例： -OpenRouter 在底层使用你的 API 密钥作为 Bearer token。 +| Model ref | 说明 | +| ------------------------------------ | ----------------------------- | +| `openrouter/auto` | OpenRouter 自动路由 | +| `openrouter/moonshotai/kimi-k2.6` | 通过 MoonshotAI 使用 Kimi K2.6 | +| `openrouter/openrouter/healer-alpha` | OpenRouter Healer Alpha 路由 | +| `openrouter/openrouter/hunter-alpha` | OpenRouter Hunter Alpha 路由 | -对于真实的 OpenRouter 请求（`https://openrouter.ai/api/v1`），OpenClaw 还会添加 OpenRouter 文档中说明的应用归因请求头： +## 身份验证和标头 + +OpenRouter 在底层使用带有你的 API 密钥的 Bearer token。 + +对于真实的 OpenRouter 请求（`https://openrouter.ai/api/v1`），OpenClaw 还会添加 OpenRouter 文档中说明的应用归因标头： | Header | Value | | ------------------------- | --------------------- | @@ -70,30 +79,30 @@ OpenRouter 在底层使用你的 API 密钥作为 Bearer token。 | `X-OpenRouter-Categories` | `cli-agent` | -如果你将 OpenRouter 提供商重新指向其他代理或基础 URL，OpenClaw **不会**注入这些 OpenRouter 特有的请求头或 Anthropic 缓存标记。 +如果你将 OpenRouter 提供商重新指向其他代理或基础 URL，OpenClaw **不会**注入这些 OpenRouter 专用标头或 Anthropic 缓存标记。 ## 高级说明 - 在经过验证的 OpenRouter 路由上，Anthropic 模型引用会保留 OpenClaw 使用的 OpenRouter 特有 Anthropic `cache_control` 标记，以更好地复用系统 / 开发者提示块的提示缓存。 + 在经过验证的 OpenRouter 路由上，Anthropic 模型引用会保留 OpenClaw 使用的 OpenRouter 专用 Anthropic `cache_control` 标记，以更好地复用 system/developer prompt 块上的提示词缓存。 - - 在受支持的非 `auto` 路由上，OpenClaw 会将所选的 thinking 级别映射为 OpenRouter 代理推理负载。不受支持的模型提示和 `openrouter/auto` 会跳过该推理注入。 + + 在受支持的非 `auto` 路由上，OpenClaw 会将所选的 thinking 级别映射为 OpenRouter 代理推理负载。不受支持的模型提示以及 `openrouter/auto` 会跳过该推理注入。 - - OpenRouter 仍然通过代理式的 OpenAI 兼容路径运行，因此原生仅限 OpenAI 的请求塑形（如 `serviceTier`、Responses `store`、OpenAI 推理兼容负载和提示缓存提示）不会被转发。 + + OpenRouter 仍通过代理式的 OpenAI 兼容路径运行，因此原生仅限 OpenAI 的请求整形（例如 `serviceTier`、Responses `store`、OpenAI reasoning-compat 负载和提示词缓存提示）不会被转发。 - 由 Gemini 支持的 OpenRouter 引用会保留在代理 Gemini 路径上：OpenClaw 会继续在那里进行 Gemini thought-signature 清理，但不会启用原生 Gemini 重放验证或引导重写。 + 由 Gemini 支持的 OpenRouter 引用会保留在代理 Gemini 路径上：OpenClaw 会继续在该路径上执行 Gemini thought-signature 清理，但不会启用原生 Gemini 重放验证或引导重写。 - 如果你在模型参数下传递 OpenRouter 提供商路由，OpenClaw 会在共享流包装器运行之前，将其作为 OpenRouter 路由元数据进行转发。 + 如果你在模型参数下传入 OpenRouter 提供商路由信息，OpenClaw 会在共享流包装器运行之前将其作为 OpenRouter 路由元数据转发。 diff --git a/docs/zh-CN/providers/vercel-ai-gateway.md b/docs/zh-CN/providers/vercel-ai-gateway.md index c1f2e6a8a..5e1718aa2 100644 --- a/docs/zh-CN/providers/vercel-ai-gateway.md +++ b/docs/zh-CN/providers/vercel-ai-gateway.md @@ -1,40 +1,38 @@ --- read_when: - - 你想在 OpenClaw 中使用 Vercel AI Gateway + - 你想将 Vercel AI Gateway 与 OpenClaw 一起使用 - 你需要 API 密钥环境变量或 CLI 认证选项 summary: Vercel AI Gateway 设置（认证 + 模型选择） -title: Vercel AI Gateway +title: Vercel AI Gateway 网关 x-i18n: - generated_at: "2026-04-12T10:36:59Z" + generated_at: "2026-04-22T03:53:30Z" model: gpt-5.4 provider: openai - source_hash: 48c206a645d7a62e201a35ae94232323c8570fdae63129231c38d363ea78a60b + source_hash: 11c0f764d4c35633d0fbfc189bae0fc451dc799002fc1a6d0c84fc73842bbe31 source_path: providers/vercel-ai-gateway.md workflow: 15 --- -# Vercel AI Gateway +# Vercel AI Gateway 网关 -[Vercel AI Gateway](https://vercel.com/ai-gateway) 提供统一的 API，让你通过单一端点访问数百种模型。 +[Vercel AI Gateway](https://vercel.com/ai-gateway) 提供统一的 API，让你通过单个端点访问数百种模型。 -| 属性 | 值 | +| Property | Value | | ------------- | -------------------------------- | | 提供商 | `vercel-ai-gateway` | | 认证 | `AI_GATEWAY_API_KEY` | -| API | 兼容 Anthropic Messages | +| API | 与 Anthropic Messages 兼容 | | 模型目录 | 通过 `/v1/models` 自动发现 | -OpenClaw 会自动发现 Gateway 网关的 `/v1/models` 目录，因此 -`/models vercel-ai-gateway` 会包含当前的模型引用，例如 -`vercel-ai-gateway/openai/gpt-5.4`。 +OpenClaw 会自动发现 Gateway 网关 的 `/v1/models` 目录，因此 `/models vercel-ai-gateway` 会包含当前的模型引用，例如 `vercel-ai-gateway/openai/gpt-5.4` 和 `vercel-ai-gateway/moonshotai/kimi-k2.6`。 ## 入门指南 - 运行新手引导并选择 AI Gateway 认证选项： + 运行新手引导并选择 AI Gateway 网关 认证选项： ```bash openclaw onboard --auth-choice ai-gateway-api-key @@ -42,7 +40,7 @@ OpenClaw 会自动发现 Gateway 网关的 `/v1/models` 目录，因此 - 将模型添加到你的 OpenClaw 配置中： + 将该模型添加到你的 OpenClaw 配置中： ```json5 { @@ -64,7 +62,7 @@ OpenClaw 会自动发现 Gateway 网关的 `/v1/models` 目录，因此 ## 非交互式示例 -对于脚本化或 CI 设置，在命令行中传入所有值： +对于脚本化或 CI 设置，请在命令行中传递所有值： ```bash openclaw onboard --non-interactive \ @@ -75,36 +73,31 @@ openclaw onboard --non-interactive \ ## 模型 ID 简写 -OpenClaw 接受 Vercel Claude 简写模型引用，并会在运行时将其规范化： +OpenClaw 接受 Vercel Claude 的简写模型引用，并会在运行时将其标准化： -| 简写输入 | 规范化后的模型引用 | +| 简写输入 | 标准化后的模型引用 | | ----------------------------------- | --------------------------------------------- | | `vercel-ai-gateway/claude-opus-4.6` | `vercel-ai-gateway/anthropic/claude-opus-4.6` | | `vercel-ai-gateway/opus-4.6` | `vercel-ai-gateway/anthropic/claude-opus-4-6` | -你可以在配置中使用简写或完全限定的模型引用。OpenClaw 会自动解析为规范形式。 +你可以在配置中使用简写或完整限定的模型引用。OpenClaw 会自动解析为规范形式。 ## 高级说明 - - 如果 OpenClaw Gateway 网关以守护进程（launchd/systemd）方式运行，请确保 - `AI_GATEWAY_API_KEY` 对该进程可用。 + + 如果 OpenClaw Gateway 网关 以守护进程（launchd/systemd）方式运行，请确保 `AI_GATEWAY_API_KEY` 可供该进程使用。 - 如果某个密钥只设置在 `~/.profile` 中，除非显式导入该环境，否则 launchd/systemd - 守护进程将无法看到它。请在 `~/.openclaw/.env` 中设置该密钥，或通过 - `env.shellEnv` 设置，以确保 Gateway 网关进程可以读取它。 + 如果密钥只设置在 `~/.profile` 中，除非显式导入该环境，否则 launchd/systemd 守护进程将无法看到它。请在 `~/.openclaw/.env` 中设置该密钥，或通过 `env.shellEnv` 设置，以确保 Gateway 网关 进程可以读取它。 - Vercel AI Gateway 会根据模型引用前缀将请求路由到上游提供商。例如，`vercel-ai-gateway/anthropic/claude-opus-4.6` 会通过 - Anthropic 路由，而 `vercel-ai-gateway/openai/gpt-5.4` 会通过 - OpenAI 路由。你的单个 `AI_GATEWAY_API_KEY` 可用于所有上游提供商的认证。 + Vercel AI Gateway 网关 会根据模型引用前缀将请求路由到上游提供商。例如，`vercel-ai-gateway/anthropic/claude-opus-4.6` 会通过 Anthropic 路由，`vercel-ai-gateway/openai/gpt-5.4` 会通过 OpenAI 路由，而 `vercel-ai-gateway/moonshotai/kimi-k2.6` 会通过 Moonshot AI 路由。单个 `AI_GATEWAY_API_KEY` 即可处理所有上游提供商的认证。 @@ -112,7 +105,7 @@ OpenClaw 接受 Vercel Claude 简写模型引用，并会在运行时将其规 - 选择提供商、模型引用和故障转移行为。 + 选择提供商、模型引用和故障切换行为。 常规故障排除和常见问题。