diff --git a/docs/zh-CN/cli/models.md b/docs/zh-CN/cli/models.md index b1a756872..3628e803e 100644 --- a/docs/zh-CN/cli/models.md +++ b/docs/zh-CN/cli/models.md @@ -2,20 +2,20 @@ read_when: - 你想更改默认模型或查看提供商凭证状态 - 你想扫描可用的模型/提供商并调试凭证配置文件 -summary: '`openclaw models` 的 CLI 参考（status/list/set/scan、别名、回退、身份验证）' +summary: CLI 参考：`openclaw models`（status/list/set/scan、别名、回退、身份验证） title: Models x-i18n: - generated_at: "2026-04-29T17:28:24Z" + generated_at: "2026-05-01T02:36:03Z" model: gpt-5.5 provider: openai - source_hash: 95e2361989b583f7f52947dad1faaaba44dc6a5f58719cc2e83c13fce7c33adc + source_hash: 538d3e4808329737fdc044dc6e14e5c7c78052e75d8a8b3b257b1ebd821c84d1 source_path: cli/models.md workflow: 16 --- # `openclaw models` -模型发现、扫描和配置（默认模型、回退项、认证配置文件）。 +模型发现、扫描和配置（默认模型、回退、认证配置档案）。 相关： @@ -32,64 +32,69 @@ openclaw models set openclaw models scan ``` -`openclaw models status` 会显示解析后的默认/回退项以及认证概览。 -当提供商用量快照可用时，OAuth/API key Status 部分会包含 -提供商用量窗口和配额快照。 -当前用量窗口提供商：Anthropic、GitHub Copilot、Gemini CLI、OpenAI -Codex、MiniMax、Xiaomi 和 z.ai。可用时，用量认证来自提供商专属钩子； -否则 OpenClaw 会回退到从认证配置文件、环境变量或配置中匹配 -OAuth/API key 凭据。 +`openclaw models status` 会显示解析后的默认值/回退以及认证概览。 +当提供商使用量快照可用时，OAuth/API key 状态部分会包含 +提供商使用窗口和配额快照。 +当前的使用窗口提供商：Anthropic、GitHub Copilot、Gemini CLI、OpenAI +Codex、MiniMax、Xiaomi 和 z.ai。使用量认证会尽可能来自提供商专属钩子； +否则 OpenClaw 会回退到从认证配置档案、环境变量或配置中匹配 OAuth/API key +凭据。 在 `--json` 输出中，`auth.providers` 是感知环境变量/配置/存储的提供商 -概览，而 `auth.oauth` 仅表示认证存储配置文件健康状态。 -添加 `--probe` 可对每个已配置的提供商配置文件运行实时认证探测。 +概览，而 `auth.oauth` 仅表示认证存储中的配置档案健康状况。 +添加 `--probe` 可对每个已配置的提供商配置档案运行实时认证探测。 探测是真实请求（可能消耗 token 并触发速率限制）。 -使用 `--agent ` 检查已配置智能体的模型/认证状态。省略时， -该命令会在已设置时使用 `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`，否则使用 +使用 `--agent ` 可检查已配置智能体的模型/认证状态。省略时， +该命令会使用 `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`（如果已设置），否则使用 已配置的默认智能体。 -探测行可以来自认证配置文件、环境凭据或 `models.json`。 +探测行可以来自认证配置档案、环境变量凭据或 `models.json`。 注意： - `models set ` 接受 `provider/model` 或别名。 -- `models list` 是只读的：它会读取配置、认证配置文件、现有目录 +- `models list` 是只读的：它会读取配置、认证配置档案、现有目录 状态和提供商拥有的目录行，但不会重写 `models.json`。 -- `Auth` 列是提供商级别且只读。它根据本地 - 认证配置文件元数据、环境变量标记、已配置的提供商键、本地提供商 - 标记、AWS Bedrock 环境变量/配置文件标记以及插件合成认证元数据计算； +- `Auth` 列是提供商级别且只读的。它根据本地 + 认证配置档案元数据、环境变量标记、已配置的提供商 key、本地提供商 + 标记、AWS Bedrock 环境变量/配置档案标记，以及插件合成认证元数据计算； 它不会加载提供商运行时、读取 keychain 密钥、调用提供商 - API，也不会证明精确的逐模型执行就绪状态。 -- `models list --all --provider ` 可以包含来自插件清单或内置提供商目录元数据的提供商拥有静态目录 + API，也不会证明精确的单模型执行就绪状态。 +- `models list --all --provider ` 可以包含来自插件清单或内置提供商目录元数据的提供商自有静态目录 行，即使你尚未对该提供商完成认证。这些行仍会显示为 不可用，直到配置了匹配的认证。 -- 宽泛的 `models list --all` 会将清单目录行合并覆盖注册表行， - 而不会加载提供商运行时补充钩子。按提供商过滤的清单 - 快速路径只使用标记为 `static` 的提供商；标记为 `refreshable` 的 - 提供商保持由注册表/缓存支持，并追加清单行作为补充，而 - 标记为 `runtime` 的提供商保持使用注册表/运行时发现。 -- `models list` 会将原生模型元数据和运行时上限分开保留。在表格 - 输出中，当有效运行时上限不同于原生上下文窗口时，`Ctx` 会显示 `contextTokens/contextWindow`；当提供商暴露该上限时，JSON 行会包含 `contextTokens`。 -- `models list --provider ` 按提供商 id 过滤，例如 `moonshot` 或 +- 当提供商目录发现较慢时，`models list` 会保持控制平面响应。默认视图和已配置视图会在短暂等待后回退到已配置或 + 合成模型行，并让发现过程在 + 后台完成。当你需要精确完整的已发现目录并且 + 愿意等待提供商发现时，使用 `--all`。 +- 宽泛的 `models list --all` 会将清单目录行合并到注册表行之上， + 而不加载提供商运行时补充钩子。提供商过滤的清单 + 快速路径只使用标记为 `static` 的提供商；标记为 `refreshable` 的提供商 + 保持由注册表/缓存支持，并将清单行作为补充追加，而 + 标记为 `runtime` 的提供商保持在注册表/运行时发现路径上。 +- `models list` 会区分原生模型元数据和运行时上限。在表格 + 输出中，当有效运行时 + 上限不同于原生上下文窗口时，`Ctx` 会显示 `contextTokens/contextWindow`；当提供商暴露该上限时，JSON 行会包含 `contextTokens`。 +- `models list --provider ` 按提供商 ID 过滤，例如 `moonshot` 或 `openai-codex`。它不接受交互式提供商 选择器中的显示标签，例如 `Moonshot AI`。 -- 模型引用通过按**第一个** `/` 拆分来解析。如果模型 ID 包含 `/`（OpenRouter 风格），请包含提供商前缀（示例：`openrouter/moonshotai/kimi-k2`）。 +- 模型引用会按**第一个** `/` 拆分。如果模型 ID 包含 `/`（OpenRouter 风格），请包含提供商前缀（示例：`openrouter/moonshotai/kimi-k2`）。 - 如果省略提供商，OpenClaw 会先将输入解析为别名，然后 - 将其解析为该精确模型 id 的唯一已配置提供商匹配，最后才 + 解析为该精确模型 ID 的唯一已配置提供商匹配项，最后才 回退到已配置的默认提供商，并显示弃用警告。 如果该提供商不再暴露已配置的默认模型，OpenClaw - 会回退到第一个已配置的提供商/模型，而不是暴露一个 + 会回退到第一个已配置的提供商/模型，而不是暴露 过时的已移除提供商默认值。 -- `models status` 可能会在认证输出中对非密钥占位符显示 `marker()`（例如 `OPENAI_API_KEY`、`secretref-managed`、`minimax-oauth`、`oauth:chutes`、`ollama-local`），而不是把它们当作密钥进行遮蔽。 +- `models status` 可能会在认证输出中为非密钥占位符显示 `marker()`（例如 `OPENAI_API_KEY`、`secretref-managed`、`minimax-oauth`、`oauth:chutes`、`ollama-local`），而不是将它们当作密钥遮蔽。 ### Models 扫描 -`models scan` 会读取 OpenRouter 的公开 `:free` 目录，并为 -回退用途对候选项排序。目录本身是公开的，因此仅元数据扫描不需要 +`models scan` 会读取 OpenRouter 的公开 `:free` 目录，并对用于 +回退的候选项进行排名。目录本身是公开的，因此仅元数据扫描不需要 OpenRouter key。 默认情况下，OpenClaw 会尝试通过实时模型调用探测工具和图像支持。 如果未配置 OpenRouter key，该命令会回退到仅元数据 -输出，并说明 `:free` 模型仍然需要 `OPENROUTER_API_KEY` 才能进行 +输出，并说明 `:free` 模型仍需要 `OPENROUTER_API_KEY` 才能进行 探测和推理。 选项： @@ -99,7 +104,7 @@ OpenRouter key。 - `--max-age-days ` - `--provider ` - `--max-candidates ` -- `--timeout `（目录请求和每次探测超时） +- `--timeout `（目录请求和单次探测超时） - `--concurrency ` - `--yes` - `--no-input` @@ -110,26 +115,26 @@ OpenRouter key。 `--set-default` 和 `--set-image` 需要实时探测；仅元数据扫描 结果仅供参考，不会应用到配置。 -### Models Status +### Models 状态 选项： - `--json` - `--plain` -- `--check`（退出 1=已过期/缺失，2=即将过期） -- `--probe`（对已配置认证配置文件进行实时探测） +- `--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`） -`--json` 会保留 stdout 专用于 JSON 负载。认证配置文件、提供商 -和启动诊断会路由到 stderr，因此脚本可以将 stdout 直接管道传入 +`--json` 会将 stdout 保留给 JSON payload。认证配置档案、提供商 +和启动诊断会路由到 stderr，因此脚本可以将 stdout 直接通过管道传给 `jq` 等工具。 -探测状态分类： +探测状态桶： - `ok` - `auth` @@ -142,22 +147,22 @@ OpenRouter key。 可预期的探测详情/原因代码情况： -- `excluded_by_auth_order`：已存在存储的配置文件，但显式 - `auth.order.` 省略了它，因此探测报告该排除原因，而不是 - 尝试使用它。 +- `excluded_by_auth_order`：存在已存储的配置档案，但显式 + `auth.order.` 省略了它，因此探测会报告该排除，而不是 + 尝试它。 - `missing_credential`、`invalid_expires`、`expired`、`unresolved_ref`： - 配置文件存在，但不符合条件/无法解析。 -- `no_model`：提供商认证存在，但 OpenClaw 无法为该提供商解析可探测的 + 配置档案存在，但不符合条件/无法解析。 +- `no_model`：提供商认证存在，但 OpenClaw 无法为该提供商解析出可探测的 模型候选项。 -## 别名 + 回退项 +## 别名 + 回退 ```bash openclaw models aliases list openclaw models fallbacks list ``` -## 认证配置文件 +## 认证配置档案 ```bash openclaw models auth add @@ -166,9 +171,9 @@ openclaw models auth setup-token --provider openclaw models auth paste-token ``` -`models auth add` 是交互式认证助手。它可以启动提供商认证 -流程（OAuth/API key），也可以根据你选择的 -提供商引导你手动粘贴 token。 +`models auth add` 是交互式认证辅助工具。它可以启动提供商认证 +流程（OAuth/API key），也可以指导你手动粘贴 token，具体取决于你选择的 +提供商。 `models auth login` 会运行提供商插件的认证流程（OAuth/API key）。使用 `openclaw plugins list` 查看已安装的提供商。 @@ -184,18 +189,17 @@ openclaw models auth login --provider openai-codex --set-default 注意： -- `setup-token` 和 `paste-token` 仍是面向暴露 token 认证方法的提供商的 - 通用 token 命令。 +- `setup-token` 和 `paste-token` 仍是面向暴露 token 认证方法的提供商的通用 token 命令。 - `setup-token` 需要交互式 TTY，并运行提供商的 token 认证 方法（当该提供商暴露 `setup-token` 方法时，默认使用该方法）。 -- `paste-token` 接受在别处生成或来自自动化的 token 字符串。 -- `paste-token` 需要 `--provider`，会提示输入 token 值，并将其写入 - 默认配置文件 id `:manual`，除非你传入 +- `paste-token` 接受在其他地方生成或来自自动化的 token 字符串。 +- `paste-token` 需要 `--provider`，会提示输入 token 值，并将 + 它写入默认配置档案 ID `:manual`，除非你传入 `--profile-id`。 -- `paste-token --expires-in ` 会根据相对时长存储绝对 token 过期时间，例如 `365d` 或 `12h`。 -- Anthropic 注意事项：Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 使用已重新允许，因此 OpenClaw 会将 Claude CLI 复用和 `claude -p` 用法视为此集成已获批准，除非 Anthropic 发布新策略。 -- Anthropic `setup-token` / `paste-token` 仍可作为受支持的 OpenClaw token 路径使用，但 OpenClaw 现在优先在可用时复用 Claude CLI 和 `claude -p`。 +- `paste-token --expires-in ` 会根据相对时长（如 `365d` 或 `12h`）存储绝对 token 到期时间。 +- Anthropic 注意：Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 使用已再次被允许，因此 OpenClaw 会将 Claude CLI 复用和 `claude -p` 使用视为此集成的受认可方式，除非 Anthropic 发布新策略。 +- Anthropic `setup-token` / `paste-token` 仍作为受支持的 OpenClaw token 路径可用，但 OpenClaw 现在会在可用时优先使用 Claude CLI 复用和 `claude -p`。 ## 相关