diff --git a/docs/zh-CN/concepts/models.md b/docs/zh-CN/concepts/models.md index e45076809..603bf5a99 100644 --- a/docs/zh-CN/concepts/models.md +++ b/docs/zh-CN/concepts/models.md @@ -1,36 +1,36 @@ --- read_when: - 添加或修改模型 CLI（models list/set/scan/aliases/fallbacks） - - 更改模型回退行为或选择体验 + - 更改模型回退行为或选择用户体验 - 更新模型扫描探针（工具/图像） sidebarTitle: Models CLI summary: Models CLI：列出、设置、别名、回退、扫描、状态 title: Models CLI x-i18n: - generated_at: "2026-05-02T07:45:14Z" + generated_at: "2026-05-04T22:20:04Z" model: gpt-5.5 provider: openai - source_hash: d362c8cc41801b5e480560c8d34be53e1ada53a23c49af99adb7874e265ddb1f + source_hash: 8a1dcdb046b914d35513974d4b69fec03a415118d11860dd1c5107efc754ed4f source_path: concepts/models.md workflow: 16 --- - 凭证配置档案轮换、冷却时间，以及它们如何与后备项交互。 + 凭证配置轮换、冷却时间，以及它们如何与 fallback 交互。 - 提供商快速概览和示例。 + 快速提供商概览和示例。 - Pi、Codex 和其他 Agent loop 运行时。 + PI、Codex 和其他 agent loop 运行时。 模型配置键。 -模型引用会选择提供商和模型。它们通常不会选择底层 Agent 运行时。例如，`openai/gpt-5.5` 可以通过常规 OpenAI provider 路径运行，也可以通过 Codex app-server 运行时运行，具体取决于 `agents.defaults.agentRuntime.id`。在 Codex 运行时模式下，`openai/gpt-*` 引用并不意味着按 API key 计费；凭证可以来自 Codex 账号或 `openai-codex` 凭证配置档案。参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。 +模型引用会选择提供商和模型。它们通常不会选择底层 Agent Runtimes。例如，`openai/gpt-5.5` 可以通过常规 OpenAI provider 路径运行，也可以通过 Codex app-server 运行时运行，具体取决于 `agents.defaults.agentRuntime.id`。在 Codex 运行时模式下，`openai/gpt-*` 引用并不意味着 API key 计费；凭证可以来自 Codex 账号或 `openai-codex` 凭证配置。请参阅 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。 ## 模型选择的工作方式 @@ -40,43 +40,43 @@ OpenClaw 按以下顺序选择模型： `agents.defaults.model.primary`（或 `agents.defaults.model`）。 - + `agents.defaults.model.fallbacks`（按顺序）。 - 凭证故障转移会先在一个提供商内部发生，然后才会移到下一个模型。 + 在移到下一个模型之前，凭证故障转移会先在提供商内部发生。 - - - `agents.defaults.models` 是 OpenClaw 可以使用的模型允许列表/目录（以及别名）。 - - `agents.defaults.imageModel` **仅在**主模型不能接受图片时使用。 - - `agents.defaults.pdfModel` 由 `pdf` 工具使用。如果省略，该工具会回退到 `agents.defaults.imageModel`，然后回退到已解析的会话/默认模型。 - - `agents.defaults.imageGenerationModel` 由共享图片生成能力使用。如果省略，`image_generate` 仍可推断一个有凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的图片生成提供商。如果你设置了特定提供商/模型，也要配置该提供商的凭证/API key。 - - `agents.defaults.musicGenerationModel` 由共享音乐生成能力使用。如果省略，`music_generate` 仍可推断一个有凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的音乐生成提供商。如果你设置了特定提供商/模型，也要配置该提供商的凭证/API key。 - - `agents.defaults.videoGenerationModel` 由共享视频生成能力使用。如果省略，`video_generate` 仍可推断一个有凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的视频生成提供商。如果你设置了特定提供商/模型，也要配置该提供商的凭证/API key。 - - 每个智能体的默认值可以通过 `agents.list[].model` 加绑定覆盖 `agents.defaults.model`（参见[多智能体路由](/zh-CN/concepts/multi-agent)）。 + + - `agents.defaults.models` 是 OpenClaw 可用模型（以及别名）的 allowlist/目录。 + - `agents.defaults.imageModel` **仅在**主模型无法接收图像时使用。 + - `agents.defaults.pdfModel` 由 `pdf` 工具使用。如果省略，该工具会回退到 `agents.defaults.imageModel`，然后回退到解析后的会话/默认模型。 + - `agents.defaults.imageGenerationModel` 由共享的图像生成能力使用。如果省略，`image_generate` 仍可推断由凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按 provider-id 顺序尝试其余已注册的图像生成提供商。如果你设置了特定提供商/模型，也要配置该提供商的凭证/API key。 + - `agents.defaults.musicGenerationModel` 由共享的音乐生成能力使用。如果省略，`music_generate` 仍可推断由凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按 provider-id 顺序尝试其余已注册的音乐生成提供商。如果你设置了特定提供商/模型，也要配置该提供商的凭证/API key。 + - `agents.defaults.videoGenerationModel` 由共享的视频生成能力使用。如果省略，`video_generate` 仍可推断由凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按 provider-id 顺序尝试其余已注册的视频生成提供商。如果你设置了特定提供商/模型，也要配置该提供商的凭证/API key。 + - 每个 agent 的默认值可以通过 `agents.list[].model` 加绑定来覆盖 `agents.defaults.model`（参见[多 agent 路由](/zh-CN/concepts/multi-agent)）。 -## 选择来源和后备行为 +## 选择来源和 fallback 行为 -同一个 `provider/model` 可能根据来源表示不同含义： +同一个 `provider/model` 可能有不同含义，具体取决于它的来源： -- 已配置的默认值（`agents.defaults.model.primary` 和智能体专属主模型）是正常起点，并使用 `agents.defaults.model.fallbacks`。 -- 自动后备选择是临时恢复状态。它们会以 `modelOverrideSource: "auto"` 存储，这样后续轮次可以继续使用后备链，而不必先探测已知不可用的主模型。 -- 用户会话选择是精确的。`/model`、模型选择器、`session_status(model=...)` 和 `sessions.patch` 会存储 `modelOverrideSource: "user"`；如果所选提供商/模型不可达，OpenClaw 会明确失败，而不是继续落到另一个已配置模型。 -- Cron `--model` / 载荷 `model` 是每个作业的主模型。除非作业提供显式载荷 `fallbacks`，否则它仍会使用已配置的后备项（严格 cron 运行可使用 `fallbacks: []`）。 -- CLI 默认模型和允许列表选择器会遵循 `models.mode: "replace"`，列出显式的 `models.providers.*.models`，而不是加载完整内置目录。 -- Control UI 模型选择器会向 Gateway 网关请求其已配置的模型视图：存在时使用 `agents.defaults.models`，否则使用显式的 `models.providers.*.models` 加上具备可用凭证的提供商。完整内置目录仅用于显式浏览视图，例如带 `view: "all"` 的 `models.list` 或 `openclaw models list --all`。 +- 已配置默认值（`agents.defaults.model.primary` 和 agent 专属 primary）是常规起点，并使用 `agents.defaults.model.fallbacks`。 +- 自动 fallback 选择是临时恢复状态。它们会与 `modelOverrideSource: "auto"` 一起存储，因此后续轮次可以继续使用 fallback 链，而无需先探测已知不可用的 primary。 +- 用户会话选择是精确的。`/model`、模型选择器、`session_status(model=...)` 和 `sessions.patch` 会存储 `modelOverrideSource: "user"`；如果所选提供商/模型不可达，OpenClaw 会显式失败，而不是落到另一个已配置模型。 +- Cron `--model` / payload `model` 是每个 job 的 primary。它仍会使用已配置的 fallback，除非该 job 提供显式 payload `fallbacks`（严格 cron 运行可使用 `fallbacks: []`）。 +- CLI 默认模型和 allowlist 选择器会遵循 `models.mode: "replace"`，列出显式的 `models.providers.*.models`，而不是加载完整内置目录。 +- Control UI 模型选择器会向 Gateway 网关请求其已配置的模型视图：存在 `agents.defaults.models` 时使用它，否则使用显式 `models.providers.*.models` 加上有可用凭证的提供商。完整内置目录仅保留给显式浏览视图，例如带 `view: "all"` 的 `models.list` 或 `openclaw models list --all`。 ## 快速模型策略 -- 将主模型设置为你可用的最强最新一代模型。 -- 对成本/延迟敏感任务和较低风险聊天使用后备项。 -- 对启用工具的智能体或不受信任的输入，避免使用较旧/较弱的模型层级。 +- 将 primary 设置为你可用的最强最新一代模型。 +- 对成本/延迟敏感任务和低风险聊天使用 fallback。 +- 对启用了工具的 agent 或不受信任的输入，避免使用较旧/较弱的模型层级。 ## 新手引导（推荐） @@ -95,7 +95,7 @@ openclaw onboard - `agents.defaults.pdfModel.primary` 和 `agents.defaults.pdfModel.fallbacks` - `agents.defaults.imageGenerationModel.primary` 和 `agents.defaults.imageGenerationModel.fallbacks` - `agents.defaults.videoGenerationModel.primary` 和 `agents.defaults.videoGenerationModel.fallbacks` -- `agents.defaults.models`（允许列表 + 别名 + 提供商参数） +- `agents.defaults.models`（allowlist + 别名 + 提供商参数） - `models.providers`（写入 `models.json` 的自定义提供商） @@ -104,9 +104,9 @@ openclaw onboard 提供商配置示例（包括 OpenCode）位于 [OpenCode](/zh-CN/providers/opencode)。 -### 安全编辑允许列表 +### 安全编辑 allowlist -手动更新 `agents.defaults.models` 时使用追加写入： +手动更新 `agents.defaults.models` 时使用增量写入： ```bash openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge @@ -114,36 +114,39 @@ openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json - `openclaw config set` 会保护模型/提供商映射，避免意外覆盖。对 `agents.defaults.models`、`models.providers` 或 `models.providers..models` 进行普通对象赋值时，如果会移除现有条目，将被拒绝。追加更改请使用 `--merge`；仅当提供的值应成为完整目标值时才使用 `--replace`。 + `openclaw config set` 会保护模型/提供商 map，避免意外覆盖。对 `agents.defaults.models`、`models.providers` 或 `models.providers..models` 的普通对象赋值，如果会移除现有条目，就会被拒绝。增量更改请使用 `--merge`；只有在提供的值应成为完整目标值时，才使用 `--replace`。 - 交互式提供商设置和 `openclaw configure --section model` 也会将提供商作用域的选择合并到现有允许列表中，因此添加 Codex、Ollama 或其他提供商不会丢弃无关模型条目。重新应用提供商凭证时，Configure 会保留现有的 `agents.defaults.model.primary`。显式默认值设置命令，例如 `openclaw models auth login --provider --set-default` 和 `openclaw models set `，仍会替换 `agents.defaults.model.primary`。 + 交互式提供商设置和 `openclaw configure --section model` 也会将提供商范围的选择合并到现有 allowlist 中，因此添加 Codex、Ollama 或其他提供商不会删除无关的模型条目。重新应用提供商凭证时，Configure 会保留现有的 `agents.defaults.model.primary`。显式默认值设置命令（例如 `openclaw models auth login --provider --set-default` 和 `openclaw models set `）仍会替换 `agents.defaults.model.primary`。 -## “模型不被允许”（以及回复为何停止） +## “Model is not allowed”（以及为什么回复会停止） -如果设置了 `agents.defaults.models`，它就会成为 `/model` 和会话覆盖的**允许列表**。当用户选择不在该允许列表中的模型时，OpenClaw 会返回： +如果设置了 `agents.defaults.models`，它会成为 `/model` 和会话覆盖的 **allowlist**。当用户选择的模型不在该 allowlist 中时，OpenClaw 会返回： ``` -Model "provider/model" is not allowed. Use /model to list available models. +Model "provider/model" is not allowed. Use /models to list providers, or /models to list models. +Add it with: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge ``` -这会发生在正常回复生成**之前**，因此消息可能会让人觉得它“没有响应”。修复方法是： +这发生在生成正常回复**之前**，因此消息可能感觉像是“没有响应”。修复方式是： - 将该模型添加到 `agents.defaults.models`，或 -- 清空允许列表（移除 `agents.defaults.models`），或 +- 清空 allowlist（移除 `agents.defaults.models`），或 - 从 `/model list` 中选择一个模型。 -对于本地/GGUF 模型，请在允许列表中存储完整的带提供商前缀引用， -例如 `ollama/gemma4:26b`、`lmstudio/Gemma4-26b-a4-it-gguf`，或 -`openclaw models list --provider ` 显示的确切提供商/模型。 -当允许列表处于启用状态时，仅使用裸本地文件名或显示名称是不够的。 +当被拒绝的命令包含运行时覆盖（例如 `/model openai/gpt-5.5 --runtime codex`）时，请先修复 allowlist，然后重试相同的 `/model ... --runtime ...` 命令。对于原生 Codex 执行，所选模型仍是 `openai/gpt-5.5`；`codex` 运行时会选择 harness，并单独使用 Codex 凭证。 -允许列表配置示例： +对于本地/GGUF 模型，请在 allowlist 中存储完整的带提供商前缀引用， +例如 `ollama/gemma4:26b`、`lmstudio/Gemma4-26b-a4-it-gguf`，或 +`openclaw models list --provider ` 显示的精确 provider/model。 +当 allowlist 处于启用状态时，仅使用本地文件名或显示名称是不够的。 + +allowlist 配置示例： ```json5 { @@ -159,7 +162,7 @@ Model "provider/model" is not allowed. Use /model to list available models. ## 在聊天中切换模型（`/model`） -你可以为当前会话切换模型，无需重启： +你可以在不重启的情况下为当前会话切换模型： ``` /model @@ -171,33 +174,33 @@ Model "provider/model" is not allowed. Use /model to list available models. - - `/model`（和 `/model list`）是一个紧凑的编号选择器（模型家族 + 可用提供商）。 - - 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，其中包含提供商和模型下拉框，以及一个提交步骤。 - - 在 Telegram 上，`/models` 选择器的选择限定在会话范围内；它们不会更改 `openclaw.json` 中智能体的持久默认值。 + - `/model`（和 `/model list`）是一个紧凑的编号选择器（模型系列 + 可用提供商）。 + - 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，其中包含提供商和模型下拉菜单以及 Submit 步骤。 + - 在 Telegram 上，`/models` 选择器的选择仅限会话范围；它们不会更改 `openclaw.json` 中该 agent 的持久默认值。 - `/models add` 已弃用，现在会返回弃用消息，而不是从聊天中注册模型。 - `/model <#>` 会从该选择器中选择。 - `/model` 会立即持久化新的会话选择。 - - 如果智能体处于空闲状态，下一次运行会立刻使用新模型。 - - 如果已有运行处于活动状态，OpenClaw 会将实时切换标记为待处理，并且只会在干净的重试点重启到新模型。 - - 如果工具活动或回复输出已经开始，待处理切换可能会保持排队，直到稍后的重试机会或下一次用户轮次。 - - 用户选择的 `/model` 引用对该会话是严格的：如果所选提供商/模型不可达，回复会明确失败，而不是静默地从 `agents.defaults.model.fallbacks` 回答。这不同于已配置默认值和 cron 作业主模型，后两者仍可使用后备链。 - - `/model status` 是详细视图（凭证候选项，以及在配置后显示的提供商端点 `baseUrl` + `api` 模式）。 + - 如果 agent 空闲，下一次运行会立刻使用新模型。 + - 如果运行已经处于活动状态，OpenClaw 会将实时切换标记为 pending，并且只会在干净的重试点重启到新模型。 + - 如果工具活动或回复输出已经开始，pending 切换可能会保持排队状态，直到后续重试机会或下一轮用户输入。 + - 用户选择的 `/model` 引用对该会话是严格的：如果所选提供商/模型不可达，回复会显式失败，而不是悄悄从 `agents.defaults.model.fallbacks` 回答。这不同于已配置默认值和 cron job primary，它们仍可使用 fallback 链。 + - `/model status` 是详细视图（凭证候选项，以及配置后显示的提供商 endpoint `baseUrl` + `api` 模式）。 - - 模型引用通过按**第一个** `/` 分割来解析。输入 `/model ` 时使用 `provider/model`。 - - 如果模型 ID 本身包含 `/`（OpenRouter 风格），你必须包含提供商前缀（示例：`/model openrouter/moonshotai/kimi-k2`）。 + - 模型引用通过按**第一个** `/` 拆分来解析。输入 `/model ` 时请使用 `provider/model`。 + - 如果模型 ID 本身包含 `/`（OpenRouter 风格），则必须包含提供商前缀（示例：`/model openrouter/moonshotai/kimi-k2`）。 - 如果省略提供商，OpenClaw 会按以下顺序解析输入： 1. 别名匹配 - 2. 与该精确无前缀模型 ID 匹配的唯一已配置提供商 - 3. 已弃用的回退方式：回退到已配置的默认提供商 —— 如果该提供商不再暴露已配置的默认模型，OpenClaw 会改为回退到第一个已配置的提供商/模型，以避免暴露陈旧的已移除提供商默认值。 + 2. 对该精确无前缀模型 id 的唯一已配置提供商匹配 + 3. 已弃用的回退到已配置默认提供商 - 如果该提供商不再暴露已配置的默认模型，OpenClaw 会改为回退到第一个已配置 provider/model，以避免暴露过期的已移除提供商默认值。 -完整命令行为/配置：[斜杠命令](/zh-CN/tools/slash-commands)。 +完整命令行为/配置：[Slash commands](/zh-CN/tools/slash-commands)。 ## CLI 命令 @@ -226,16 +229,16 @@ openclaw models image-fallbacks clear ### `models list` -默认显示已配置/凭证可用的模型。实用标志： +默认显示已配置/认证可用的模型。常用标志： - 完整目录。在配置身份验证之前包含内置的提供商拥有的静态目录行，因此仅设备发现视图可以显示在你添加匹配的提供商凭证之前不可用的模型。 + 完整目录。在配置认证之前包含内置的、由提供商拥有的静态目录行，因此仅发现视图可以显示那些在你添加匹配的提供商凭证之前不可用的模型。 仅本地提供商。 - 按提供商 ID 过滤，例如 `moonshot`。不接受交互式选择器中的显示标签。 + 按提供商 id 过滤，例如 `moonshot`。不接受交互式选择器中的显示标签。 每行一个模型。 @@ -246,21 +249,21 @@ openclaw models image-fallbacks clear ### `models status` -显示解析后的主模型、回退模型、图像模型，以及已配置提供商的身份验证概览。它还会显示身份验证存储中找到的配置文件的 OAuth 过期状态（默认在 24 小时内发出警告）。`--plain` 只打印解析后的主模型。 +显示解析后的主模型、回退模型、图像模型，以及已配置提供商的认证概览。它还会显示在认证存储中找到的配置文件的 OAuth 过期状态（默认在 24 小时内警告）。`--plain` 仅打印解析后的主模型。 - - - OAuth 状态始终显示（并包含在 `--json` 输出中）。如果已配置的提供商没有凭证，`models status` 会打印 **缺少身份验证** 部分。 - - JSON 包含 `auth.oauth`（警告窗口 + 配置文件）和 `auth.providers`（每个提供商的有效身份验证，包括由环境变量支持的凭证）。`auth.oauth` 仅表示身份验证存储配置文件健康状态；仅使用环境变量的提供商不会出现在其中。 - - 将 `--check` 用于自动化（缺失/过期时退出 `1`，即将过期时退出 `2`）。 - - 将 `--probe` 用于实时身份验证检查；探测行可以来自身份验证配置文件、环境变量凭证或 `models.json`。 - - 如果显式 `auth.order.` 省略了已存储的配置文件，探测会报告 `excluded_by_auth_order`，而不是尝试使用它。如果身份验证存在，但无法为该提供商解析可探测模型，探测会报告 `status: no_model`。 + + - OAuth 状态始终显示（并包含在 `--json` 输出中）。如果已配置的提供商没有凭证，`models status` 会打印一个**缺少认证**部分。 + - JSON 包含 `auth.oauth`（警告窗口 + 配置文件）和 `auth.providers`（每个提供商的有效认证，包括环境变量支持的凭证）。`auth.oauth` 仅表示认证存储配置文件健康状况；仅环境变量的提供商不会出现在这里。 + - 使用 `--check` 进行自动化（缺失/过期时退出 `1`，即将过期时退出 `2`）。 + - 使用 `--probe` 进行实时认证检查；探测行可以来自认证配置文件、环境变量凭证或 `models.json`。 + - 如果显式 `auth.order.` 省略了已存储的配置文件，探测会报告 `excluded_by_auth_order`，而不是尝试它。如果认证存在但无法为该提供商解析出可探测模型，探测会报告 `status: no_model`。 -身份验证选择取决于提供商/账户。对于常开 Gateway 网关主机，API key 通常最可预测；也支持复用 Claude CLI 以及现有的 Anthropic OAuth/token 配置文件。 +认证选择取决于提供商/账户。对于常驻运行的 Gateway 网关主机，API key 通常最可预测；也支持复用 Claude CLI 以及现有的 Anthropic OAuth/token 配置文件。 示例（Claude CLI）： @@ -272,7 +275,7 @@ openclaw models status ## 扫描（OpenRouter 免费模型） -`openclaw models scan` 会检查 OpenRouter 的**免费模型目录**，并可选择探测模型是否支持工具和图像。 +`openclaw models scan` 会检查 OpenRouter 的**免费模型目录**，并可选择探测模型的工具和图像支持。 跳过实时探测（仅元数据）。 @@ -281,7 +284,7 @@ openclaw models status 最小参数规模（十亿）。 - 跳过较旧模型。 + 跳过较旧的模型。 提供商前缀过滤器。 @@ -290,14 +293,14 @@ openclaw models status 回退列表大小。 - 将 `agents.defaults.model.primary` 设置为第一个选择。 + 将 `agents.defaults.model.primary` 设置为第一个选择项。 - 将 `agents.defaults.imageModel.primary` 设置为第一个图像选择。 + 将 `agents.defaults.imageModel.primary` 设置为第一个图像选择项。 -OpenRouter `/models` 目录是公开的，因此仅元数据扫描可以在没有 key 的情况下列出免费候选项。探测和推理仍需要 OpenRouter API key（来自身份验证配置文件或 `OPENROUTER_API_KEY`）。如果没有可用 key，`openclaw models scan` 会回退到仅元数据输出，并保持配置不变。使用 `--no-probe` 可显式请求仅元数据模式。 +OpenRouter `/models` 目录是公开的，因此仅元数据扫描无需 key 即可列出免费候选项。探测和推理仍需要 OpenRouter API key（来自认证配置文件或 `OPENROUTER_API_KEY`）。如果没有可用的 key，`openclaw models scan` 会回退到仅元数据输出，并保持配置不变。使用 `--no-probe` 可显式请求仅元数据模式。 扫描结果按以下顺序排名： @@ -310,13 +313,13 @@ OpenRouter `/models` 目录是公开的，因此仅元数据扫描可以在没 输入： - OpenRouter `/models` 列表（过滤 `:free`） -- 实时探测需要来自身份验证配置文件或 `OPENROUTER_API_KEY` 的 OpenRouter API key（参见[环境变量](/zh-CN/help/environment)） +- 实时探测需要来自认证配置文件或 `OPENROUTER_API_KEY` 的 OpenRouter API key（参见[环境变量](/zh-CN/help/environment)） - 可选过滤器：`--max-age-days`、`--min-params`、`--provider`、`--max-candidates` - 请求/探测控制：`--timeout`、`--concurrency` -当实时探测在 TTY 中运行时，你可以交互式选择回退项。在非交互模式下，传入 `--yes` 以接受默认值。仅元数据结果只用于提供信息；`--set-default` 和 `--set-image` 需要实时探测，这样 OpenClaw 就不会配置一个无法使用的无 key OpenRouter 模型。 +当实时探测在 TTY 中运行时，你可以交互式选择回退模型。在非交互模式下，传入 `--yes` 以接受默认值。仅元数据结果只提供信息；`--set-default` 和 `--set-image` 需要实时探测，这样 OpenClaw 才不会配置无法使用的无 key OpenRouter 模型。 -## Models 注册表（`models.json`） +## 模型注册表（`models.json`） `models.providers` 中的自定义提供商会写入智能体目录下的 `models.json`（默认 `~/.openclaw/agents//agent/models.json`）。除非 `models.mode` 设置为 `replace`，否则默认会合并此文件。 @@ -325,25 +328,25 @@ OpenRouter `/models` 目录是公开的，因此仅元数据扫描可以在没 匹配提供商 ID 的合并模式优先级： - 智能体 `models.json` 中已存在的非空 `baseUrl` 优先。 - - 智能体 `models.json` 中的非空 `apiKey` 仅在当前配置/身份验证配置文件上下文中该提供商不由 SecretRef 管理时优先。 - - SecretRef 管理的提供商 `apiKey` 值会从源标记刷新（环境变量引用为 `ENV_VAR_NAME`，file/exec 引用为 `secretref-managed`），而不是持久化已解析的密钥。 - - SecretRef 管理的提供商标头值会从源标记刷新（环境变量引用为 `secretref-env:ENV_VAR_NAME`，file/exec 引用为 `secretref-managed`）。 - - 空或缺失的智能体 `apiKey`/`baseUrl` 会回退到配置 `models.providers`。 - - 其他提供商字段会从配置和规范化的目录数据刷新。 + - 智能体 `models.json` 中的非空 `apiKey` 仅在该提供商未由当前配置/认证配置文件上下文中的 SecretRef 管理时优先。 + - 由 SecretRef 管理的提供商 `apiKey` 值会从源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，file/exec 引用使用 `secretref-managed`），而不是持久化解析后的密钥。 + - 由 SecretRef 管理的提供商 header 值会从源标记刷新（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，file/exec 引用使用 `secretref-managed`）。 + - 空的或缺失的智能体 `apiKey`/`baseUrl` 会回退到配置 `models.providers`。 + - 其他提供商字段会从配置和规范化目录数据刷新。 -标记持久化以源为权威：OpenClaw 写入来自活动源配置快照（解析前）的标记，而不是来自已解析的运行时密钥值。每当 OpenClaw 重新生成 `models.json` 时都会如此，包括 `openclaw agent` 等命令驱动路径。 +标记持久化以源为准：OpenClaw 会从活动源配置快照（解析前）写入标记，而不是从解析后的运行时密钥值写入。只要 OpenClaw 重新生成 `models.json`，都会应用这一点，包括像 `openclaw agent` 这样的命令驱动路径。 ## 相关 -- [Agent Runtimes](/zh-CN/concepts/agent-runtimes) — PI、Codex 和其他 Agent loop 运行时 +- [Agent Runtimes](/zh-CN/concepts/agent-runtimes) — Pi、Codex 和其他 Agent loop 运行时 - [配置参考](/zh-CN/gateway/config-agents#agent-defaults) — 模型配置键 - [图像生成](/zh-CN/tools/image-generation) — 图像模型配置 - [模型故障转移](/zh-CN/concepts/model-failover) — 回退链 -- [模型提供商](/zh-CN/concepts/model-providers) — 提供商路由和身份验证 +- [模型提供商](/zh-CN/concepts/model-providers) — 提供商路由和认证 - [音乐生成](/zh-CN/tools/music-generation) — 音乐模型配置 - [视频生成](/zh-CN/tools/video-generation) — 视频模型配置 diff --git a/docs/zh-CN/help/faq-models.md b/docs/zh-CN/help/faq-models.md index 744a47df7..3b7299f27 100644 --- a/docs/zh-CN/help/faq-models.md +++ b/docs/zh-CN/help/faq-models.md @@ -2,20 +2,20 @@ read_when: - 选择或切换模型，配置别名 - 调试模型故障转移 / “所有模型均失败” - - 了解凭证配置文件以及如何管理它们 + - 了解身份验证配置文件及其管理方式 sidebarTitle: Models FAQ -summary: 常见问题：模型默认设置、选择、别名、切换、故障转移和认证配置文件 +summary: 常见问题：模型默认值、选择、别名、切换、故障转移和认证配置文件 title: 常见问题：模型和凭证 x-i18n: - generated_at: "2026-05-02T02:37:17Z" + generated_at: "2026-05-04T22:20:01Z" model: gpt-5.5 provider: openai - source_hash: 1bf7a6bb4a0e2bf791c73dbb4005ba4628afc2c20e06417f8147f4c65583e884 + source_hash: bf06266926cecc06d8799cb17f42d96cdaa09ad83c20e8d4dcc3bcccbd840abc source_path: help/faq-models.md workflow: 16 --- - 模型和认证配置文件问答。关于设置、会话、Gateway 网关、渠道和 + Models 和身份验证配置文件问答。关于设置、会话、Gateway 网关、渠道和 故障排除，请参阅主 [常见问题](/zh-CN/help/faq)。 ## Models：默认值、选择、别名、切换 @@ -28,27 +28,26 @@ x-i18n: agents.defaults.model.primary ``` - 模型以 `provider/model` 形式引用（示例：`openai/gpt-5.5` 或 `openai-codex/gpt-5.5`）。如果省略提供商，OpenClaw 会先尝试别名，然后尝试精确模型 ID 的唯一已配置提供商匹配，最后才会回退到已配置的默认提供商，这是一条已弃用的兼容路径。如果该提供商不再公开已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是暴露已过时的已移除提供商默认值。你仍应**显式**设置 `provider/model`。 + 模型以 `provider/model` 引用（例如：`openai/gpt-5.5` 或 `openai-codex/gpt-5.5`）。如果你省略提供商，OpenClaw 会先尝试别名，然后尝试该精确模型 ID 的唯一已配置提供商匹配，之后才会回退到已配置的默认提供商，这是已弃用的兼容路径。如果该提供商不再暴露已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是显示一个已移除提供商的过期默认值。你仍然应该**显式**设置 `provider/model`。 **推荐默认值：** 使用你的提供商栈中可用的最强最新一代模型。 - **对于启用工具或处理不受信任输入的智能体：** 优先考虑模型能力而不是成本。 - **对于常规/低风险聊天：** 使用更便宜的回退模型，并按智能体角色路由。 + **对于启用工具或不受信任输入的智能体：** 优先考虑模型能力，而不是成本。 + **对于日常/低风险聊天：** 使用更便宜的回退模型，并按智能体角色路由。 MiniMax 有自己的文档：[MiniMax](/zh-CN/providers/minimax) 和 [本地模型](/zh-CN/gateway/local-models)。 - 经验法则：对于高风险工作，使用你**负担得起的最佳模型**；对于常规聊天或摘要，使用更便宜的 - 模型。你可以为每个智能体路由模型，并使用子智能体来 - 并行处理长任务（每个子智能体都会消耗 token）。请参阅 [Models](/zh-CN/concepts/models) 和 + 经验法则：对于高风险工作，使用你**负担得起的最佳模型**；对于日常聊天或摘要，使用更便宜的 + 模型。你可以按智能体路由模型，并使用子智能体来 + 并行处理长任务（每个子智能体都会消耗 token）。参见 [Models](/zh-CN/concepts/models) 和 [子智能体](/zh-CN/tools/subagents)。 - 强烈警告：较弱或过度量化的模型更容易受到提示 - 注入和不安全行为的影响。请参阅[安全](/zh-CN/gateway/security)。 + 强烈警告：较弱/过度量化的模型更容易受到提示注入和不安全行为的影响。参见 [安全](/zh-CN/gateway/security)。 - 更多背景：[Models](/zh-CN/concepts/models)。 + 更多上下文：[Models](/zh-CN/concepts/models)。 @@ -62,10 +61,10 @@ x-i18n: - `openclaw configure --section model`（交互式） - 编辑 `~/.openclaw/openclaw.json` 中的 `agents.defaults.model` - 避免对部分对象使用 `config.apply`，除非你有意替换整个配置。 - 对于 RPC 编辑，请先用 `config.schema.lookup` 检查，并优先使用 `config.patch`。lookup 载荷会给出规范化路径、浅层 schema 文档/约束，以及直接子项摘要。 + 避免用部分对象调用 `config.apply`，除非你打算替换整个配置。 + 对于 RPC 编辑，先用 `config.schema.lookup` 检查，并优先使用 `config.patch`。查找载荷会给出规范化路径、浅层 schema 文档/约束，以及直接子项摘要。 用于部分更新。 - 如果你确实覆盖了配置，请从备份恢复，或重新运行 `openclaw doctor` 修复。 + 如果你确实覆盖了配置，请从备份恢复，或重新运行 `openclaw doctor` 进行修复。 文档：[Models](/zh-CN/concepts/models)、[配置](/zh-CN/cli/configure)、[配置](/zh-CN/cli/config)、[Doctor](/zh-CN/gateway/doctor)。 @@ -82,14 +81,13 @@ x-i18n: 4. 运行 `openclaw onboard` 并选择 `Ollama` 5. 选择 `Local` 或 `Cloud + Local` - 注意： + 说明： - - `Cloud + Local` 会为你提供云模型以及你的本地 Ollama 模型 + - `Cloud + Local` 会提供云模型以及你的本地 Ollama 模型 - `kimi-k2.5:cloud` 等云模型不需要本地拉取 - 如需手动切换，请使用 `openclaw models list` 和 `openclaw models set ollama/` - 安全注意事项：较小或重度量化的模型更容易受到提示 - 注入影响。对于任何可以使用工具的机器人，我们强烈建议使用**大模型**。 + 安全说明：较小或重度量化的模型更容易受到提示注入影响。对于任何可以使用工具的 bot，我们强烈建议使用**大模型**。 如果你仍想使用小模型，请启用沙箱隔离和严格的工具允许列表。 文档：[Ollama](/zh-CN/providers/ollama)、[本地模型](/zh-CN/gateway/local-models)、 @@ -100,12 +98,12 @@ x-i18n: - 这些部署可能不同，并且可能随时间变化；没有固定的提供商推荐。 - - 使用 `openclaw models status` 检查每个 Gateway 网关上的当前运行时设置。 + - 使用 `openclaw models status` 在每个 Gateway 网关上检查当前运行时设置。 - 对于安全敏感/启用工具的智能体，请使用可用的最强最新一代模型。 - + 将 `/model` 命令作为独立消息使用： ``` @@ -118,48 +116,48 @@ x-i18n: /model gemini-flash-lite ``` - 这些是内置别名。可通过 `agents.defaults.models` 添加自定义别名。 + 这些是内置别名。可以通过 `agents.defaults.models` 添加自定义别名。 - 你可以用 `/model`、`/model list` 或 `/model status` 列出可用模型。 + 你可以使用 `/model`、`/model list` 或 `/model status` 列出可用模型。 - `/model`（以及 `/model list`）会显示紧凑的编号选择器。按编号选择： + `/model`（以及 `/model list`）会显示一个紧凑的编号选择器。按编号选择： ``` /model 3 ``` - 你也可以为该提供商强制指定特定认证配置文件（按会话）： + 你也可以为提供商强制指定特定身份验证配置文件（按会话）： ``` /model opus@anthropic:default /model opus@anthropic:work ``` - 提示：`/model status` 会显示哪个智能体处于活动状态、正在使用哪个 `auth-profiles.json` 文件，以及接下来会尝试哪个认证配置文件。 - 可用时，它还会显示已配置的提供商端点（`baseUrl`）和 API 模式（`api`）。 + 提示：`/model status` 会显示哪个智能体处于活动状态、正在使用哪个 `auth-profiles.json` 文件，以及接下来会尝试哪个身份验证配置文件。 + 它还会在可用时显示已配置的提供商端点（`baseUrl`）和 API 模式（`api`）。 **如何取消固定我用 @profile 设置的配置文件？** - 重新运行 `/model`，但**不带** `@profile` 后缀： + 重新运行 `/model`，但**不要**带 `@profile` 后缀： ``` /model anthropic/claude-opus-4-6 ``` - 如果你想返回默认值，请从 `/model` 中选择它（或发送 `/model `）。 - 使用 `/model status` 确认哪个认证配置文件处于活动状态。 + 如果你想回到默认值，请从 `/model` 中选择它（或发送 `/model `）。 + 使用 `/model status` 确认当前活动的身份验证配置文件。 可以。将模型选择和运行时选择分开处理： - - **原生 Codex 编码智能体：** 将 `agents.defaults.model.primary` 设置为 `openai/gpt-5.5`，并将 `agents.defaults.agentRuntime.id` 设置为 `"codex"`。当你想使用 ChatGPT/Codex 订阅认证时，使用 `openclaw models auth login --provider openai-codex` 登录。 - - **通过 PI 直接执行 OpenAI API 任务：** 使用 `/model openai/gpt-5.5`，不要设置 Codex 运行时覆盖，并配置 `OPENAI_API_KEY`。 - - **通过 PI 使用 Codex OAuth：** 仅当你有意使用带 Codex OAuth 的普通 PI runner 时，才使用 `/model openai-codex/gpt-5.5`。 + - **原生 Codex 编码智能体：** 将 `agents.defaults.model.primary` 设置为 `openai/gpt-5.5`，并将 `agents.defaults.agentRuntime.id` 设置为 `"codex"`。当你想使用 ChatGPT/Codex 订阅身份验证时，请用 `openclaw models auth login --provider openai-codex` 登录。 + - **通过 PI 直接执行 OpenAI API 任务：** 使用 `/model openai/gpt-5.5`，不使用 Codex 运行时覆盖，并配置 `OPENAI_API_KEY`。 + - **通过 PI 使用 Codex OAuth：** 仅当你有意使用带 Codex OAuth 的普通 PI 运行器时，才使用 `/model openai-codex/gpt-5.5`。 - **子智能体：** 将编码任务路由到一个仅 Codex 的智能体，该智能体有自己的模型和 `agentRuntime` 默认值。 - 请参阅 [Models](/zh-CN/concepts/models) 和 [斜杠命令](/zh-CN/tools/slash-commands)。 + 参见 [Models](/zh-CN/concepts/models) 和 [斜杠命令](/zh-CN/tools/slash-commands)。 @@ -187,40 +185,43 @@ x-i18n: } ``` - 对于 OpenAI，快速模式会在受支持的原生 Responses 请求上映射到 `service_tier = "priority"`。会话 `/fast` 覆盖优先级高于配置默认值。 + 对于 OpenAI，快速模式会在受支持的原生 Responses 请求上映射到 `service_tier = "priority"`。会话 `/fast` 覆盖优先于配置默认值。 - 请参阅[思考和快速模式](/zh-CN/tools/thinking)以及 [OpenAI 快速模式](/zh-CN/providers/openai#fast-mode)。 + 参见 [思考和快速模式](/zh-CN/tools/thinking) 以及 [OpenAI 快速模式](/zh-CN/providers/openai#fast-mode)。 - 如果设置了 `agents.defaults.models`，它会成为 `/model` 和任何 + 如果设置了 `agents.defaults.models`，它就会成为 `/model` 和任何 会话覆盖的**允许列表**。选择不在该列表中的模型会返回： ``` - Model "provider/model" is not allowed. Use /model to list available models. + Model "provider/model" is not allowed. Use /models to list providers, or /models to list models. + Add it with: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge ``` - 这个错误会**代替**正常回复返回。修复方法：将该模型添加到 + 该错误会**代替**正常回复返回。修复方法：将模型添加到 `agents.defaults.models`，移除允许列表，或从 `/model list` 中选择一个模型。 + 如果命令还包含 `--runtime codex`，请先添加模型，然后重试同一个 + `/model provider/model --runtime codex` 命令。 - 这意味着**提供商尚未配置**（未找到 MiniMax 提供商配置或认证 + 这意味着**提供商未配置**（没有找到 MiniMax 提供商配置或身份验证 配置文件），因此无法解析该模型。 - 修复检查清单： + 修复清单： - 1. 升级到当前的 OpenClaw 版本（或从源代码 `main` 运行），然后重启 Gateway 网关。 - 2. 确保 MiniMax 已配置（向导或 JSON），或者 MiniMax 认证 - 存在于环境变量/认证配置文件中，以便注入匹配的提供商 + 1. 升级到当前 OpenClaw 版本（或从源代码 `main` 运行），然后重启 Gateway 网关。 + 2. 确保 MiniMax 已配置（向导或 JSON），或者 MiniMax 身份验证 + 存在于环境/身份验证配置文件中，以便可以注入匹配的提供商 （`MINIMAX_API_KEY` 用于 `minimax`，`MINIMAX_OAUTH_TOKEN` 或已存储的 MiniMax OAuth 用于 `minimax-portal`）。 - 3. 为你的认证路径使用精确模型 ID（区分大小写）： - API key 设置使用 `minimax/MiniMax-M2.7` 或 `minimax/MiniMax-M2.7-highspeed`， - OAuth 设置使用 `minimax-portal/MiniMax-M2.7` / - `minimax-portal/MiniMax-M2.7-highspeed`。 + 3. 对你的身份验证路径使用精确模型 ID（区分大小写）： + `minimax/MiniMax-M2.7` 或 `minimax/MiniMax-M2.7-highspeed` 用于 API key + 设置，或者 `minimax-portal/MiniMax-M2.7` / + `minimax-portal/MiniMax-M2.7-highspeed` 用于 OAuth 设置。 4. 运行： ```bash @@ -229,12 +230,12 @@ x-i18n: 并从列表中选择（或在聊天中使用 `/model list`）。 - 请参阅 [MiniMax](/zh-CN/providers/minimax) 和 [Models](/zh-CN/concepts/models)。 + 参见 [MiniMax](/zh-CN/providers/minimax) 和 [Models](/zh-CN/concepts/models)。 - - 可以。将 **MiniMax 作为默认模型**，并在需要时**按会话**切换模型。 + + 可以。将 **MiniMax 作为默认值**，并在需要时**按会话**切换模型。 回退用于**错误**，而不是“困难任务”，因此请使用 `/model` 或单独的智能体。 **选项 A：按会话切换** @@ -271,18 +272,18 @@ x-i18n: - 是。OpenClaw 随附一些默认简写（仅当模型存在于 `agents.defaults.models` 中时应用）： + 是的。OpenClaw 附带一些默认简写（仅在模型存在于 `agents.defaults.models` 中时应用）： - `opus` → `anthropic/claude-opus-4-6` - `sonnet` → `anthropic/claude-sonnet-4-6` - - `gpt` → API key 设置中的 `openai/gpt-5.5`，或配置为 Codex OAuth 时的 `openai-codex/gpt-5.5` + - `gpt` → `openai/gpt-5.5` 用于 API key 设置，或在配置为 Codex OAuth 时使用 `openai-codex/gpt-5.5` - `gpt-mini` → `openai/gpt-5.4-mini` - `gpt-nano` → `openai/gpt-5.4-nano` - `gemini` → `google/gemini-3.1-pro-preview` - `gemini-flash` → `google/gemini-3-flash-preview` - `gemini-flash-lite` → `google/gemini-3.1-flash-lite-preview` - 如果你设置了同名别名，则你的值优先。 + 如果你用相同名称设置自己的别名，你的值会优先。 @@ -304,7 +305,7 @@ x-i18n: } ``` - 然后 `/model sonnet`（或在支持时使用 `/`）会解析到该模型 ID。 + 然后 `/model sonnet`（或在受支持时使用 `/`）会解析为该模型 ID。 @@ -337,11 +338,11 @@ x-i18n: } ``` - 如果你引用了某个提供商/模型，但缺少所需的提供商密钥，你会收到运行时认证错误（例如 `No API key found for provider "zai"`）。 + 如果你引用了某个提供商/模型，但缺少所需的提供商密钥，你会遇到运行时认证错误（例如 `No API key found for provider "zai"`）。 - **添加新智能体后找不到提供商的 API key** + **添加新智能体后找不到提供商的 API 密钥** - 这通常表示**新智能体**的认证存储为空。认证按智能体区分，并存储在： + 这通常表示**新智能体**的认证存储为空。认证按智能体隔离，并存储在： ``` ~/.openclaw/agents//agent/auth-profiles.json @@ -350,120 +351,119 @@ x-i18n: 修复选项： - 运行 `openclaw agents add `，并在向导中配置认证。 - - 或者只把可移植的静态 `api_key` / `token` 配置文件从主智能体的认证存储复制到新智能体的认证存储。 - - 对于 OAuth 配置文件，在新智能体需要自己的账号时从新智能体登录；否则 OpenClaw 可以读取默认/主智能体，而无需克隆 refresh token。 + - 或者只将可移植的静态 `api_key` / `token` 配置档案从主智能体的认证存储复制到新智能体的认证存储中。 + - 对于 OAuth 配置档案，当新智能体需要自己的账号时，从新智能体登录；否则 OpenClaw 可以透传读取默认/主智能体，而无需克隆刷新令牌。 不要在多个智能体之间复用 `agentDir`；这会导致认证/会话冲突。 -## 模型故障转移和“所有模型均失败” +## 模型故障转移和“All models failed” - 故障转移分两个阶段进行： + 故障转移分两个阶段发生： - 1. 同一提供商内的**认证配置文件轮换**。 + 1. 同一提供商内的**认证配置档案轮换**。 2. **模型回退**到 `agents.defaults.model.fallbacks` 中的下一个模型。 - 冷却时间会应用到失败的配置文件（指数退避），因此即使某个提供商受到速率限制或暂时失败，OpenClaw 也可以继续响应。 + 冷却时间会应用到失败的配置档案（指数退避），因此即使提供商受到速率限制或暂时失败，OpenClaw 也能继续响应。 - 速率限制分组包含的不只是普通的 `429` 响应。OpenClaw - 也会把 `Too many concurrent requests`、 + 速率限制桶包含的不只是普通的 `429` 响应。OpenClaw + 也会将 `Too many concurrent requests`、 `ThrottlingException`、`concurrency limit reached`、 - `workers_ai ... quota limit exceeded`、`resource exhausted` 以及周期性 - 用量窗口限制（`weekly/monthly limit reached`）等消息视为值得故障转移的 + `workers_ai ... quota limit exceeded`、`resource exhausted` 以及周期性的 + 使用窗口限制（`weekly/monthly limit reached`）等消息视为值得触发故障转移的 速率限制。 - 有些看起来像计费问题的响应不是 `402`，而有些 HTTP `402` - 响应也会留在这个瞬态分组中。如果提供商在 `401` 或 `403` 上返回 - 明确的计费文本，OpenClaw 仍可以将其保留在计费通道中， - 但提供商特定的文本匹配器会限定在拥有它们的 - 提供商范围内（例如 OpenRouter `Key limit exceeded`）。如果 `402` - 消息看起来更像可重试的用量窗口或 + 某些看起来像计费问题的响应不是 `402`，而某些 HTTP `402` + 响应也仍会留在这个瞬时桶中。如果提供商在 `401` 或 `403` 上返回 + 明确的计费文本，OpenClaw 仍然可以将其保留在 + 计费通道中，但提供商特定的文本匹配器会保持在其所属提供商的作用域内（例如 OpenRouter `Key limit exceeded`）。如果 `402` + 消息反而看起来像可重试的使用窗口或 组织/工作区支出限制（`daily limit reached, resets tomorrow`、 `organization spending limit exceeded`），OpenClaw 会将其视为 - `rate_limit`，而不是长期的计费停用。 + `rate_limit`，而不是长期计费停用。 上下文溢出错误不同：诸如 `request_too_large`、`input exceeds the maximum number of tokens`、 `input token count exceeds the maximum number of input tokens`、 `input is too long for the model` 或 `ollama error: context length - exceeded` 这样的特征会留在压缩/重试路径上，而不是推进模型 + exceeded` 这样的签名会留在压缩/重试路径上，而不是推进模型 回退。 - 通用服务器错误文本被刻意限定得比“任何包含 - unknown/error 的内容”更窄。OpenClaw 确实会把提供商范围内的瞬态形态 - 视为值得故障转移的超时/过载信号，例如 Anthropic 裸 - `An unknown error occurred`、OpenRouter 裸 + 通用服务器错误文本有意比“任何包含 + unknown/error 的内容”更窄。当提供商上下文 + 匹配时，OpenClaw 确实会将提供商作用域内的瞬时形态， + 例如 Anthropic 裸 `An unknown error occurred`、OpenRouter 裸 `Provider returned error`、像 `Unhandled stop reason: - error` 这样的停止原因错误、带瞬态服务器文本 + error` 这样的停止原因错误、带有瞬时服务器文本的 JSON `api_error` 载荷 （`internal server error`、`unknown error, 520`、`upstream error`、`backend - error`）的 JSON `api_error` 负载，以及像 `ModelNotReadyException` 这样的 - 提供商繁忙错误，前提是提供商上下文匹配。 + error`），以及像 `ModelNotReadyException` 这样的提供商繁忙错误 + 视为值得触发故障转移的超时/过载信号。 像 `LLM request failed with an unknown - error.` 这样的通用内部回退文本会保持保守，单独不会触发模型回退。 + error.` 这样的通用内部回退文本会保持保守，本身不会触发模型回退。 - 这表示系统尝试使用认证配置文件 ID `anthropic:default`，但无法在预期的认证存储中找到它的凭据。 + 这表示系统尝试使用认证配置档案 ID `anthropic:default`，但无法在预期的认证存储中找到它的凭据。 - **修复清单：** + **修复检查清单：** - - **确认认证配置文件存放在哪里**（新路径与旧路径） + - **确认认证配置档案的存放位置**（新路径与旧路径） - 当前：`~/.openclaw/agents//agent/auth-profiles.json` - 旧版：`~/.openclaw/agent/*`（由 `openclaw doctor` 迁移） - - **确认你的环境变量已被 Gateway 网关加载** - - 如果你在 shell 中设置了 `ANTHROPIC_API_KEY`，但通过 systemd/launchd 运行 Gateway 网关，它可能不会继承该变量。将它放入 `~/.openclaw/.env`，或启用 `env.shellEnv`。 + - **确认你的环境变量已由 Gateway 网关加载** + - 如果你在 shell 中设置了 `ANTHROPIC_API_KEY`，但通过 systemd/launchd 运行 Gateway 网关，它可能不会继承该变量。把它放到 `~/.openclaw/.env`，或启用 `env.shellEnv`。 - **确保你正在编辑正确的智能体** - 多智能体设置意味着可能存在多个 `auth-profiles.json` 文件。 - **对模型/认证状态做完整性检查** - - 使用 `openclaw models status` 查看已配置的模型以及提供商是否已认证。 + - 使用 `openclaw models status` 查看已配置的模型，以及提供商是否已通过认证。 - **“No credentials found for profile anthropic”的修复清单** + **“No credentials found for profile anthropic”的修复检查清单** - 这表示本次运行固定到了某个 Anthropic 认证配置文件，但 Gateway 网关 + 这表示运行被固定到某个 Anthropic 认证配置档案，但 Gateway 网关 无法在其认证存储中找到它。 - **使用 Claude CLI** - - 在 Gateway 网关主机上运行 `openclaw models auth login --provider anthropic --method cli --set-default`。 - - **如果你想改用 API key** - - 在 **Gateway 网关主机**上的 `~/.openclaw/.env` 中放入 `ANTHROPIC_API_KEY`。 - - 清除任何强制使用缺失配置文件的固定顺序： + - 在网关主机上运行 `openclaw models auth login --provider anthropic --method cli --set-default`。 + - **如果你想改用 API 密钥** + - 将 `ANTHROPIC_API_KEY` 放到**网关主机**上的 `~/.openclaw/.env` 中。 + - 清除任何强制使用缺失配置档案的固定顺序： ```bash openclaw models auth order clear --provider anthropic ``` - - **确认你是在 Gateway 网关主机上运行命令** - - 在远程模式下，认证配置文件位于 Gateway 网关机器上，而不是你的笔记本电脑上。 + - **确认你是在网关主机上运行命令** + - 在远程模式下，认证配置档案位于网关机器上，而不是你的笔记本电脑上。 - - 如果你的模型配置包含 Google Gemini 作为回退（或者你切换到了 Gemini 简写），OpenClaw 会在模型回退期间尝试它。如果你还没有配置 Google 凭据，你会看到 `No API key found for provider "google"`。 + + 如果你的模型配置包含 Google Gemini 作为回退项（或者你切换到了 Gemini 简写），OpenClaw 会在模型回退期间尝试它。如果你没有配置 Google 凭据，你会看到 `No API key found for provider "google"`。 - 修复：提供 Google 认证，或者从 `agents.defaults.model.fallbacks` / aliases 中移除/避免 Google 模型，这样回退就不会路由到那里。 + 修复：提供 Google 认证，或者从 `agents.defaults.model.fallbacks` / 别名中移除/避免使用 Google 模型，这样回退就不会路由到那里。 - **LLM 请求被拒绝：需要 thinking signature（Google Antigravity）** + **LLM 请求被拒绝：需要 thinking 签名（Google Antigravity）** - 原因：会话历史包含**没有签名的 thinking block**（通常来自 - 已中止/不完整的流）。Google Antigravity 要求 thinking block 带有签名。 + 原因：会话历史包含**没有签名的 thinking 块**（通常来自 + 被中止/不完整的流）。Google Antigravity 要求 thinking 块具有签名。 - 修复：OpenClaw 现在会为 Google Antigravity Claude 去除未签名的 thinking block。如果仍然出现，请启动一个**新会话**，或为该智能体设置 `/thinking off`。 + 修复：OpenClaw 现在会为 Google Antigravity Claude 去除未签名的 thinking 块。如果仍然出现，请启动一个**新会话**，或为该智能体设置 `/thinking off`。 -## 认证配置文件：它们是什么以及如何管理 +## 认证配置档案：它们是什么以及如何管理 -相关：[/concepts/oauth](/zh-CN/concepts/oauth)（OAuth 流程、token 存储、多账号模式） +相关：[/concepts/oauth](/zh-CN/concepts/oauth)（OAuth 流程、令牌存储、多账号模式） - - 认证配置文件是绑定到提供商的命名凭据记录（OAuth 或 API key）。配置文件位于： + + 认证配置档案是一个命名的凭据记录（OAuth 或 API 密钥），绑定到某个提供商。配置档案位于： ``` ~/.openclaw/agents//agent/auth-profiles.json @@ -471,23 +471,23 @@ x-i18n: - + OpenClaw 使用带提供商前缀的 ID，例如： - - `anthropic:default`（没有电子邮件身份时常见） + - `anthropic:default`（没有邮箱身份时常见） - OAuth 身份使用 `anthropic:` - 你选择的自定义 ID（例如 `anthropic:work`） - - 可以。配置支持为配置文件添加可选元数据，并按提供商设置顺序（`auth.order.`）。这不会存储密钥；它会将 ID 映射到提供商/模式，并设置轮换顺序。 + + 可以。配置支持配置档案的可选元数据，以及每个提供商的排序（`auth.order.`）。这**不会**存储密钥；它将 ID 映射到提供商/模式，并设置轮换顺序。 - 如果某个配置文件处于短暂**冷却**状态（速率限制/超时/认证失败）或较长的**停用**状态（计费/余额不足），OpenClaw 可能会暂时跳过它。要检查这一点，请运行 `openclaw models status --json` 并查看 `auth.unusableProfiles`。调优项：`auth.cooldowns.billingBackoffHours*`。 + 如果某个配置档案处于短暂**冷却**状态（速率限制/超时/认证失败）或较长的**停用**状态（计费/余额不足），OpenClaw 可能会暂时跳过它。要检查这一点，请运行 `openclaw models status --json` 并查看 `auth.unusableProfiles`。调优项：`auth.cooldowns.billingBackoffHours*`。 - 速率限制冷却可以按模型限定。某个配置文件针对一个模型处于冷却中时， - 仍可能可用于同一提供商上的相邻模型， - 而计费/停用窗口仍会阻止整个配置文件。 + 速率限制冷却可以按模型划分。某个配置档案如果正在为 + 一个模型冷却，仍然可用于同一提供商上的同级模型， + 而计费/停用窗口仍会阻止整个配置档案。 你也可以通过 CLI 设置**按智能体**的顺序覆盖（存储在该智能体的 `auth-state.json` 中）： @@ -505,7 +505,7 @@ x-i18n: openclaw models auth order clear --provider anthropic ``` - 要指定某个智能体： + 要指定特定智能体： ```bash openclaw models auth order set --provider anthropic --agent main anthropic:default @@ -517,25 +517,25 @@ x-i18n: openclaw models status --probe ``` - 如果某个已存储的配置文件被显式顺序省略，探测会为该配置文件报告 + 如果某个已存储的配置档案被显式顺序省略，探测会为该配置档案报告 `excluded_by_auth_order`，而不是静默尝试它。 - - OpenClaw 同时支持两者： + + OpenClaw 两者都支持： - - **OAuth** 通常会利用订阅访问权限（适用时）。 - - **API keys** 使用按 token 计费。 + - **OAuth** 通常会利用订阅访问权限（在适用时）。 + - **API 密钥**使用按令牌计费。 - 向导明确支持 Anthropic Claude CLI、OpenAI Codex OAuth 和 API keys。 + 向导明确支持 Anthropic Claude CLI、OpenAI Codex OAuth 和 API 密钥。 ## 相关 -- [常见问题](/zh-CN/help/faq) — 主要常见问题 +- [常见问题](/zh-CN/help/faq) — 主常见问题 - [常见问题 — 快速开始和首次运行设置](/zh-CN/help/faq-first-run) - [模型选择](/zh-CN/concepts/model-providers) - [模型故障转移](/zh-CN/concepts/model-failover)