diff --git a/docs/zh-CN/cli/models.md b/docs/zh-CN/cli/models.md index adb21b8c3..e54b51f23 100644 --- a/docs/zh-CN/cli/models.md +++ b/docs/zh-CN/cli/models.md @@ -5,10 +5,10 @@ read_when: summary: '`openclaw models` 的 CLI 参考（status/list/set/scan、别名、回退、认证）' title: 模型 x-i18n: - generated_at: "2026-04-23T20:44:17Z" + generated_at: "2026-04-24T01:05:12Z" model: gpt-5.4 provider: openai - source_hash: d0d244da9793efc520827d35e7dbf8fd643b11d1bf52d0e202cf5c93e693e2bc + source_hash: b3cda32db9aa36527c30d8820ce76a94a4ae3e1294fdc850dc1d7948bfa90799 source_path: cli/models.md workflow: 15 --- @@ -32,35 +32,42 @@ openclaw models set openclaw models scan ``` -`openclaw models status` 会显示解析后的默认值/回退值以及认证概览。 +`openclaw models status` 会显示已解析的默认值/回退配置以及认证概览。 当提供商使用情况快照可用时，OAuth/API 密钥状态部分会包含 提供商使用窗口和配额快照。 当前支持使用窗口的提供商有：Anthropic、GitHub Copilot、Gemini CLI、OpenAI -Codex、MiniMax、Xiaomi 和 z.ai。使用情况认证在可用时来自提供商特定 hooks； -否则，OpenClaw 会回退为从认证配置文件、环境变量或配置中匹配 OAuth/API 密钥 +Codex、MiniMax、Xiaomi 和 z.ai。使用情况认证在可用时来自提供商专属钩子； +否则 OpenClaw 会回退为匹配来自认证配置文件、环境变量或配置的 OAuth/API 密钥 凭证。 -在 `--json` 输出中，`auth.providers` 是感知 env/config/store 的提供商 -概览，而 `auth.oauth` 仅表示认证存储中的配置文件健康状态。 -添加 `--probe` 可针对每个已配置的提供商配置文件运行实时认证探测。 -探测是真实请求（可能会消耗令牌并触发速率限制）。 +在 `--json` 输出中，`auth.providers` 是感知环境变量/配置/存储的提供商 +概览，而 `auth.oauth` 仅是认证存储中的配置文件健康状态。 +添加 `--probe` 可对每个已配置的提供商配置文件运行实时认证探测。 +探测会发起真实请求（可能消耗令牌并触发速率限制）。 使用 `--agent ` 可检查某个已配置智能体的模型/认证状态。省略时， -该命令会在设置了 `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR` 时使用它， -否则使用已配置的默认智能体。 -探测行可来自认证配置文件、环境变量凭证或 `models.json`。 +命令会在已设置的情况下使用 `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`，否则使用 +已配置的默认智能体。 +探测结果行可能来自认证配置文件、环境变量凭证或 `models.json`。 说明： - `models set ` 接受 `provider/model` 或别名。 -- `models list --all` 即使在你尚未完成该提供商认证时，也会包含由内置提供商拥有的静态目录行。这些行在配置匹配认证之前仍会显示为不可用。 -- `models list --provider ` 按提供商 ID 过滤，例如 `moonshot` 或 `openai-codex`。它不接受交互式提供商选择器中的显示标签，例如 `Moonshot AI`。 -- 模型引用通过按**第一个** `/` 分割来解析。如果模型 ID 本身包含 `/`（OpenRouter 风格），请包含提供商前缀（示例：`openrouter/moonshotai/kimi-k2`）。 -- 如果你省略提供商，OpenClaw 会先将输入解析为别名，然后 - 解析为对该精确模型 ID 的唯一已配置提供商匹配，最后 - 才会回退到已配置的默认提供商，并显示弃用警告。 - 如果该提供商不再提供已配置的默认模型，OpenClaw - 会回退到第一个已配置的提供商/模型，而不是暴露 - 已被移除的过时默认提供商。 -- `models status` 可能会在认证输出中显示 `marker()`，用于表示非秘密占位符（例如 `OPENAI_API_KEY`、`secretref-managed`、`minimax-oauth`、`oauth:chutes`、`ollama-local`），而不是将其作为秘密进行掩码处理。 +- `models list` 是只读的：它会读取配置、认证配置文件、现有目录 + 状态以及提供商拥有的目录条目，但不会重写 + `models.json`。 +- `models list --all` 会包含内置的、由提供商拥有的静态目录条目，即使 + 你尚未通过该提供商完成认证。 + 在配置匹配的认证之前，这些条目仍会显示为不可用。 +- `models list --provider ` 会按提供商 id 过滤，例如 `moonshot` 或 + `openai-codex`。它不接受交互式提供商选择器中的显示标签，例如 + `Moonshot AI`。 +- 模型引用通过按**第一个** `/` 拆分来解析。如果模型 ID 包含 `/`（OpenRouter 风格），请包含提供商前缀（例如：`openrouter/moonshotai/kimi-k2`）。 +- 如果你省略了提供商，OpenClaw 会先将输入解析为别名，然后 + 解析为该精确模型 id 在已配置提供商中的唯一匹配，最后才 + 回退到已配置的默认提供商，并附带弃用警告。 + 如果该提供商不再公开已配置的默认模型，OpenClaw + 会回退到第一个已配置的提供商/模型，而不是暴露一个 + 过时、已移除提供商的默认值。 +- `models status` 可能会在认证输出中将非机密占位符显示为 `marker()`（例如 `OPENAI_API_KEY`、`secretref-managed`、`minimax-oauth`、`oauth:chutes`、`ollama-local`），而不是将它们作为机密进行掩码处理。 ### `models status` @@ -71,13 +78,13 @@ Codex、MiniMax、Xiaomi 和 z.ai。使用情况认证在可用时来自提供 - `--check`（退出码 1=已过期/缺失，2=即将过期） - `--probe`（对已配置的认证配置文件进行实时探测） - `--probe-provider `（探测单个提供商） -- `--probe-profile `（可重复或用逗号分隔的配置文件 ID） +- `--probe-profile `（可重复使用或传入逗号分隔的配置文件 id） - `--probe-timeout ` - `--probe-concurrency ` - `--probe-max-tokens ` -- `--agent `（已配置的智能体 ID；会覆盖 `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`） +- `--agent `（已配置的智能体 id；覆盖 `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`） -探测状态分桶： +探测状态分类： - `ok` - `auth` @@ -88,15 +95,15 @@ Codex、MiniMax、Xiaomi 和 z.ai。使用情况认证在可用时来自提供 - `unknown` - `no_model` -预期会看到的探测详情/原因代码情况： +可预期的探测详情/原因代码包括： - `excluded_by_auth_order`：存在已存储的配置文件，但显式的 - `auth.order.` 将其省略，因此探测会报告该排除，而不是 + `auth.order.` 将其省略，因此探测会报告该排除情况，而不是 尝试使用它。 - `missing_credential`、`invalid_expires`、`expired`、`unresolved_ref`： - 配置文件存在，但不具备资格/不可解析。 -- `no_model`：提供商认证存在，但 OpenClaw 无法为该提供商解析出 - 可用于探测的候选模型。 + 配置文件存在，但不符合条件/无法解析。 +- `no_model`：提供商认证存在，但 OpenClaw 无法为该提供商解析出可用于探测的 + 候选模型。 ## 别名 + 回退 @@ -115,10 +122,10 @@ openclaw models auth paste-token ``` `models auth add` 是交互式认证辅助工具。它可以启动提供商认证 -流程（OAuth/API 密钥），或根据你选择的提供商，引导你手动粘贴令牌。 +流程（OAuth/API 密钥），也可以根据你选择的提供商，引导你手动粘贴令牌。 -`models auth login` 运行提供商插件的认证流程（OAuth/API 密钥）。使用 -`openclaw plugins list` 可查看已安装的提供商。 +`models auth login` 会运行提供商插件的认证流程（OAuth/API 密钥）。使用 +`openclaw plugins list` 查看已安装了哪些提供商。 示例： @@ -128,13 +135,15 @@ openclaw models auth login --provider openai-codex --set-default 说明： -- `setup-token` 和 `paste-token` 仍然是通用令牌命令，适用于 - 暴露了令牌认证方法的提供商。 -- `setup-token` 需要交互式 TTY，并运行该提供商的令牌认证 - 方法（当该提供商暴露了 `setup-token` 方法时，默认使用它的 `setup-token` 方法）。 -- `paste-token` 接受从其他地方或自动化流程生成的令牌字符串。 -- `paste-token` 需要 `--provider`，会提示输入令牌值，并将其写入默认配置文件 ID `:manual`，除非你传入 +- `setup-token` 和 `paste-token` 仍然是通用令牌命令，适用于公开了 + 令牌认证方法的提供商。 +- `setup-token` 需要交互式 TTY，并会运行该提供商的令牌认证 + 方法（当该提供商公开了 `setup-token` 方法时，默认使用它）。 +- `paste-token` 接受在其他地方或通过自动化生成的令牌字符串。 +- `paste-token` 需要 `--provider`，会提示输入令牌值，并将其写入 + 默认配置文件 id `:manual`，除非你传入 `--profile-id`。 -- `paste-token --expires-in ` 会根据相对时长（如 `365d` 或 `12h`）存储一个绝对令牌过期时间。 -- Anthropic 说明：Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允许，因此 OpenClaw 将 Claude CLI 复用和 `claude -p` 用法视为此集成的认可路径，除非 Anthropic 发布新的政策。 -- Anthropic 的 `setup-token` / `paste-token` 仍然是受支持的 OpenClaw 令牌路径，但在可用时，OpenClaw 现在更优先使用 Claude CLI 复用和 `claude -p`。 +- `paste-token --expires-in ` 会根据相对时长存储绝对令牌过期时间， + 例如 `365d` 或 `12h`。 +- Anthropic 说明：Anthropic 员工告知我们，OpenClaw 风格的 Claude CLI 使用再次被允许，因此 OpenClaw 将 Claude CLI 复用和 `claude -p` 用法视为该集成的许可方式，除非 Anthropic 发布新的政策。 +- Anthropic `setup-token` / `paste-token` 仍然作为受支持的 OpenClaw 令牌路径可用，但 OpenClaw 现在在可用时更倾向于使用 Claude CLI 复用和 `claude -p`。