openclaw models 子命令提供模型发现、扫描、默认模型/降级链切换和认证档案管理。使用 status 查看当前认证和模型配置（支持 --probe 实时探测）、list 列出所有可用模型（只读，不写 models.json）、set 切换主模型、scan 自动扫描并推荐模型（可 --set-default 自动应用）、auth 管理 OAuth/API Key 档案（add/login/paste-token/setup-token）。注意：list 的 Auth 列是 provider 级别只读状态，不含运行时验证；scan 的 --set-default 需要实时探测，仅 metadata 扫描不会修改配置。

OpenClaw models 命令：模型配置、认证与用量排查指南

模型发现、扫描、配置（默认模型、降级链、认证档案）的 CLI 参考。

相关文档：

• Provider + 模型配置：Models
• 模型选择概念 + /models 斜杠命令：Models concept
• Provider 认证设置：快速开始

常用命令

openclaw models status
openclaw models list
openclaw models set <model-or-alias>
openclaw models scan

openclaw models status 显示已解析的默认/降级链以及认证概览。当有 provider 用量快照时，OAuth/API Key 状态部分会包含用量窗口和配额快照。 当前支持用量快照的 provider：Anthropic、GitHub Copilot、Gemini CLI、OpenAI Codex、MiniMax、Xiaomi、z.ai。用量认证来自 provider 特定钩子（如果可用）；否则 OpenClaw 回退到匹配的 OAuth/API Key 凭据（从认证档案、环境变量或 config 获取）。 在 --json 输出中，auth.providers 是环境/配置/存储感知的 provider 概览，而 auth.oauth 仅反映认证存储（auth store）中的档案健康状态。 加上 --probe 会对每个配置的 provider 档案发起实时认证探测。探测是真实请求（可能消耗 token 并触发限速）。 使用 --agent <id> 检查指定 agent 的模型/认证状态。省略时使用 OPENCLAW_AGENT_DIR/PI_CODING_AGENT_DIR（如果设置）或默认 agent。 探测行可以来自认证档案、环境凭据或 models.json。

Codex OAuth 故障排查：openclaw models status、openclaw models auth list --provider openai-codex 和 openclaw config get agents.defaults.model --json 是最快确认 agent 是否具有可用的 openai-codex 认证档案（用于 openai/* 模型）的方式。详见 OpenAI provider 设置。

注意：

• models set <model-or-alias> 接受 provider/model 格式或别名。
• models list 是只读命令：它读取 config、认证档案、现有 catalog 状态以及 provider 拥有的 catalog 行，但不会改写 models.json。
• Auth 列是 provider 级别且只读。它根据本地认证档案元数据、环境变量标记、配置的 provider key、本地 provider 标记、AWS Bedrock 环境/档案标记以及插件合成认证元数据计算得出；它不会加载 provider 运行时、读取钥匙串机密、调用 provider API，也不会证明每个模型的精确执行就绪性。
• models list --all --provider <id> 可能包含 provider 拥有的静态 catalog 行（来自插件清单或捆绑的 provider catalog 元数据），即使你尚未对该 provider 进行认证。这些行会显示为不可用，直到配置了匹配的认证。
• models list 在 provider catalog 发现较慢时会保持控制平面响应。默认和配置的视图会在一段等待后回退到配置或合成模型行，并让发现过程在后台完成。当你需要精确的完整发现 catalog 且愿意等待 provider 发现时，使用 --all。
• 宽泛的 models list --all 会合并 manifest catalog 行覆盖 registry 行，但不会加载 provider 运行时补充钩子。provider 过滤的 manifest 快速路径仅使用标记为 static 的 provider；标记为 refreshable 的 provider 保持 registry/缓存备份并附加 manifest 行作为补充，而标记为 runtime 的 provider 保持 registry/运行时发现。
• models list 会区分原生模型元数据和运行时能力。在表格输出中，当有效运行时能力窗口与原生的 context window 不同时，Ctx 列会显示 contextTokens/contextWindow；JSON 行在 provider 暴露该能力时包含 contextTokens。
• models list --provider <id> 按 provider id 过滤，例如 moonshot 或 openai-codex。不接受来自交互式 provider 选择器的显示标签（如 Moonshot AI）。
• 模型引用通过第一个 / 分割。如果模型 ID 包含 /（OpenRouter 风格），需要带上 provider 前缀（例如 openrouter/moonshotai/kimi-k2）。
• 如果省略 provider，OpenClaw 先作为别名解析，然后作为已配置的 provider 中唯一匹配该模型 ID 的精确模型，最后才回退到配置的默认 provider 并发出弃用警告。如果该默认 provider 不再暴露配置的默认模型，OpenClaw 会回退到第一个配置的 provider/模型，而不是显示一个过时的已移除 provider 默认模型。
• models status 在认证输出中可能显示 marker(<value>) 来表示非机密的占位符（例如 OPENAI_API_KEY、secretref-managed、minimax-oauth、oauth:chutes、ollama-local），不会将其掩盖为机密。

Models scan

models scan 读取 OpenRouter 的公开 :free catalog 并对候选模型进行排序以用于降级链。catalog 本身是公开的，因此仅元数据的扫描不需要 OpenRouter 密钥。

默认情况下，OpenClaw 会尝试使用实时模型调用来探测工具支持和图像支持。如果未配置 OpenRouter 密钥，命令回退到仅元数据输出，并说明 :free 模型仍需要 OPENROUTER_API_KEY 才能进行探测和推理。

选项：

• --no-probe（仅元数据，不查找配置/密钥）
• --min-params <b>
• --max-age-days <days>
• --provider <name>
• --max-candidates <n>
• --timeout <ms>（catalog 请求和每次探测的超时）
• --concurrency <n>
• --yes
• --no-input
• --set-default
• --set-image
• --json

--set-default 和 --set-image 需要实时探测；仅元数据的扫描结果是信息性参考，不会应用到配置。

Models status

选项：

• --json
• --plain
• --check（退出码：1=已过期/缺失，2=即将过期）
• --probe（对配置的认证档案发起实时探测）
• --probe-provider <name>（仅探测一个 provider）
• --probe-profile <id>（可重复或逗号分隔的档案 id）
• --probe-timeout <ms>
• --probe-concurrency <n>
• --probe-max-tokens <n>
• --agent <id>（指定 agent id，覆盖 OPENCLAW_AGENT_DIR/PI_CODING_AGENT_DIR）

--json 保持 stdout 专用于 JSON 负载。认证档案、provider 和启动诊断信息路由到 stderr，以便脚本可以直接将 stdout 管道传输给 jq 等工具。

探测状态桶：

• ok
• auth
• rate_limit
• billing
• timeout
• format
• unknown
• no_model

探测详情/原因码情况：

• excluded_by_auth_order：存储的档案存在，但显式的 auth.order.<provider> 排除了它，因此探测报告排除而非尝试。
• missing_credential、invalid_expires、expired、unresolved_ref：档案存在但不可用/无法解析。
• no_model：provider 认证存在，但 OpenClaw 无法为该 provider 解析出可探测的模型候选。

别名和降级链

openclaw models aliases list
openclaw models fallbacks list

认证档案

openclaw models auth add
openclaw models auth list [--provider <id>] [--json]
openclaw models auth login --provider <id>
openclaw models auth setup-token --provider <id>
openclaw models auth paste-token

models auth add 是交互式认证助手。它会根据你选择的 provider 启动一个 provider 认证流程（OAuth/API Key），或引导你手动粘贴 token。

models auth list 列出所选 agent 保存的认证档案，不会打印 token、API Key 或 OAuth 机密信息。使用 --provider <id> 过滤到单个 provider（例如 openai-codex），使用 --json 便于脚本处理。

models auth login 运行 provider 插件的认证流程（OAuth/API Key）。使用 openclaw plugins list 查看已安装的 provider。使用 openclaw models auth --agent <id> <subcommand> 将认证结果写入特定 agent 的存储。父级 --agent 标志适用于 add、list、login、setup-token、paste-token 和 login-github-copilot。

对于 OpenAI 模型，--provider openai 默认使用 ChatGPT/Codex 账号登录。仅当你想要添加 OpenAI API Key 档案（通常作为 Codex 订阅限额的备份）时使用 --method api-key。旧的 --provider openai-codex 拼写仍适用于现有脚本。

示例：

openclaw models auth login --provider openai --set-default
openclaw models auth login --provider openai --method api-key
openclaw models auth list --provider openai

注意：

• setup-token 和 paste-token 仍然是适用于暴露 token 认证方法的 provider 的通用 token 命令。
• setup-token 需要交互式 TTY，运行该 provider 的 token 认证方法（如果该 provider 暴露了 setup-token 方法，则默认使用该方法）。
• paste-token 接受在其他地方生成或来自自动化的 token 字符串。
• paste-token 需要 --provider，提示输入 token 值，并写入默认档案 id <provider>:manual，除非你传递 --profile-id。
• paste-token --expires-in <duration> 从相对时长（如 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（如果可用）。

相关文档

• CLI 参考
• 模型选择
• 模型故障转移

常见问题

excluded_by_auth_order 是什么意思？

A：models status 显示该状态时，表示认证档案存在，但 auth.order.<provider> 配置明确排除了该档案，因此不会被探测。检查 openclaw config get auth.order 确认优先级配置。

models list 为什么看不到某些模型？

A：模型需要在 provider 中完成认证才会在默认视图中显示。未认证的 provider 的模型只有在你使用 --all 时才列出（并标记为不可用）。另外，models list 是只读命令，不会修改 models.json，也不会主动发现新 provider；可以尝试 models scan 手动扫描。

如何通过 paste-token 添加一个 token？

A：运行 openclaw models auth paste-token --provider <provider-id>，程序会提示输入 token 值。默认写入档案 id <provider>:manual，可通过 --profile-id 指定。支持 --expires-in <duration> 设置过期时间，例如 365d。