openclaw models
模型发现、扫描和配置（默认模型、回退、认证配置文件）。
相关：
常用命令
status 和 auth 子命令接受 --agent <id> 来指定一个已配置的 agent；list、scan、aliases 以及 fallbacks/image-fallbacks 始终使用已配置的默认 agent，而 set/set-image 会直接拒绝 --agent。在未指定时，支持 --agent 的命令会使用 OPENCLAW_AGENT_DIR（如果已设置），否则使用已配置的默认 agent。
状态
直接运行openclaw models 等同于运行 openclaw models status。openclaw models --json 返回与 openclaw models status --json 相同的对象。
openclaw models status 显示解析后的默认模型/回退模型以及认证概览。活跃的 profile 冷却状态会显示在 不可用的认证 profile 下，并包含已存储的原因和恢复操作；JSON 输出会在 auth.unusableProfiles 中公开相同数据。对于 Codex 等由插件拥有的 agent 运行时，status 还会检查所属插件是否已启用，以及是否通过启动载荷验证。具有有效凭据但运行时不可用的路由会报告 status: unavailable，而不是 usable；JSON 输出会分别包含 authStatus、runtimeStatus 和受限的运行时诊断信息。当提供方使用情况快照可用时，OAuth/API key 状态部分会包含提供方使用时间窗口和配额快照。目前支持使用情况窗口的提供方包括：Anthropic、GitHub Copilot、OpenAI、MiniMax、小米和 z.ai。使用情况认证在可用时来自提供方专用钩子；否则 OpenClaw 会从认证 profile、环境变量或配置中匹配的 OAuth/API key 凭据回退获取。
在 --json 输出中，auth.providers 是面向环境/配置/存储且感知的提供方概览，而 auth.oauth 仅表示 auth-store 中 profile 的健康状态。
选项：
探测结果行可能来自 auth profile、环境凭据或
models.json。探测状态桶：ok、auth、rate_limit、billing、timeout、format、unknown、no_model。
直接运行 models status --probe 会在所选 agent 的规范数据库中创建临时内部会话，因此该命令要求对已配置状态目录拥有独占控制权。在探测前，请使用 openclaw gateway stop 停止正在运行的 Gateway；命令结束或被中断时，会删除其内部会话并释放状态锁。
当探测从未到达模型调用时，可能出现以下探测详细信息/原因代码：
excluded_by_auth_order：存在已存储的 profile，但显式的auth.order.<provider>将其省略，因此探测会报告被排除，而不是尝试它。missing_credential、invalid_expires、expired、unresolved_ref：profile 已存在，但不符合条件或无法解析。ineligible_profile：该 profile 因其他原因与提供方配置不兼容。no_model：存在提供方认证，但 OpenClaw 无法为该提供方解析出可探测的模型候选。
openclaw models status、openclaw models auth list --provider openai 和 openclaw config get agents.defaults.model --json 是最快确认某个 agent 是否拥有可用于通过原生 Codex 运行时访问 openai/* 的有效 openai OAuth profile 的方法。参见 OpenAI 提供方设置。
列表
openclaw models list 是只读的：它读取配置、auth profile、现有 catalog 状态以及由 provider 提供的 catalog 行，但绝不会重写 models.json。
openclaw models refresh [--json] 会强制立即检查托管 catalog。更新后的行会在下一次重启后应用到正在运行的 Gateway。若
models.catalogRefresh.enabled 为 false，该命令会明确输出已禁用的结果。catalog 的公开变更历史位于
openclaw/catalog，其中每次内容更新都会由计划发布器提交。
选项：--all（完整 catalog）、--local（筛选本地模型）、--provider <id>、--json、--plain。
注意：
Auth列是只读的。对于由提供方拥有的模型路由（例如 OpenAI），它会将每一行的 API/base-URL 路由与有效auth.order、环境/配置凭据以及已解析的命令作用域 SecretRefs 中的可用 profile 进行匹配。某个具体的 OpenAI 行在其路由策略不可用时会保持未知，而不会借用提供方级别认证；仅提供方旧版检查和其他提供方仍保留提供方级别行为。插件的 synthetic-auth 元数据只是运行时能力提示，并不能证明原生账号认证可用，因此在没有 registry 正向证据时，依赖账号的路由仍会显示为未知。该命令不会加载提供方运行时、读取 keychain 密钥、调用提供方 API，也不会证明确切的执行就绪状态。models list --all --provider <id>即使你尚未在该提供方完成认证，也可以包含来自插件清单或内置提供方 catalog 元数据的提供方拥有的静态 catalog 行。这些行在未配置匹配认证之前仍会显示为不可用。- 当提供方 catalog 发现过程较慢时，
models list会保持控制平面响应迅速。默认视图和已配置视图会在短暂等待后回退到已配置或合成的模型行，并让发现过程在后台继续完成。若你需要精确的完整发现 catalog 且愿意等待提供方发现完成，请使用--all。 - 宽泛的
models list --all会在不加载提供方运行时补充 hook 的情况下，将 manifest catalog 行合并到 registry 行之上。按提供方筛选的 manifest 快速路径只使用标记为static的提供方；标记为refreshable的提供方仍保持 registry/cache-backed，并将 manifest 行作为补充追加；而标记为runtime的提供方则仍依赖 registry/runtime 发现。 models list会将原生模型元数据与运行时上限区分开来。在表格输出中，当有效运行时上限与原生上下文窗口不同时，Ctx会显示contextTokens/contextWindow；JSON 行在提供方暴露该上限时会包含contextTokens。- 对于由提供方拥有的路由，
models list会将一个逻辑 provider/model 行投影到所选路由上。Input和Ctx只来自完全匹配的物理路由 catalog 行，并在最后应用显式配置的逻辑覆盖；未解析的路由选择会显示未知能力字段，而不会借用同级路由的元数据。 models list --provider <id>通过提供方 id 进行筛选，例如moonshot或openai。它不接受交互式提供方选择器中的显示标签，例如Moonshot AI。- 模型引用通过拆分第一个
/来解析。如果模型 ID 本身包含/（OpenRouter 风格），请包含提供方前缀（例如openrouter/moonshotai/kimi-k2）。 - 如果你省略提供方，OpenClaw 会先将输入解析为别名，然后解析为与该确切模型 id 对应的唯一已配置提供方匹配，最后才带着弃用警告回退到已配置的默认提供方。如果该提供方不再暴露已配置的默认模型，OpenClaw 会回退到第一个已配置的提供方/模型，而不是显示一个已失效、已移除提供方的默认值。
models status在认证输出中可能会显示marker(<value>)，用于非密钥占位符（例如OPENAI_API_KEY、secretref-managed、minimax-oauth、oauth:chutes、ollama-local），而不是将它们掩码为密钥。
设置默认/图像模型
set 会写入 agents.defaults.model.primary；set-image 会写入 agents.defaults.imageModel.primary。两者都接受 provider/model 或已配置的别名。set 还会在新选择的模型需要时修复 Codex/Copilot 运行时插件安装；set-image 不会。两个命令都不接受 --agent；它们始终写入 agent 默认值。
扫描
models scan 会读取 OpenRouter 的公开 :free catalog，并对候选项进行排序以供回退使用。catalog 本身是公开的，因此仅元数据扫描不需要 OpenRouter key。
默认情况下，OpenClaw 会尝试通过实时模型调用来探测工具和图像支持。如果未配置 OpenRouter key，该命令会回退到仅元数据输出，并说明 :free 模型在探测和推理时仍需要 OPENROUTER_API_KEY。
选项：
--no-probe（仅元数据；不查询配置/密钥）--min-params <b>--max-age-days <days>--provider <name>--max-candidates <n>--timeout <ms>（目录请求和每次探测超时）--concurrency <n>--yes--no-input--set-default--set-image--json
--set-default 和 --set-image 需要实时探测；仅元数据的扫描结果仅供参考，不会应用到配置中。
别名
agents.defaults.models.<key>.alias。add 会先将 <model-or-alias> 解析为规范的提供方/模型键，因此对别名再添加别名时会重新指向它，而不是形成链式引用。添加别名不会更改
agents.defaults.modelPolicy.allow，也不会限制模型覆盖。
回退
agents.defaults.model.fallbacks。openclaw models image-fallbacks list|add|remove|clear 以相同的子命令形式管理并行的 agents.defaults.imageModel.fallbacks 列表。
认证配置文件
models auth add 是交互式认证助手。根据你选择的 provider，它可以启动 provider 的认证流程（OAuth/API key），也可以引导你手动粘贴 token。
models auth list 会列出所选 agent 的已保存认证配置文件，但不会打印 token、API key 或 OAuth 密钥材料。活动中的冷却和禁用条目会包含其原因及恢复操作。对于旧版 Gemini CLI OAuth 冷却，该命令会引导你使用受支持的 Google AI Studio API key 设置，而不是提供不可用的 Gemini CLI 登录流程。使用 --provider <id> 可筛选单个 provider，例如 openai；使用 --json 可用于脚本处理。
models auth login 会运行 provider 插件的认证流程（OAuth/API key）。使用 openclaw plugins list 查看已安装哪些 provider。login 支持 --profile-id <id>，适用于在登录期间支持命名配置文件的 provider（可用来将同一 provider 的多个登录分开保存），--method <id> 用于选择特定认证方法，--device-code 作为 --method device-code 的快捷方式，--set-default 用于应用 provider 推荐的默认模型，--force 用于先移除该 provider 现有的配置文件（当缓存的 OAuth 配置文件卡住，或你想切换账号时使用）。
models auth logout <profileId> 会从所选 agent 的认证存储中移除一个已保存的认证配置文件。请使用 models auth list 显示的配置文件 id。它还会从你的配置中的 auth.profiles 以及所有 auth.order 列表中删除该配置文件，因此不会留下过期引用，并且会删除一个原本会被清空的 auth.order.<provider> 条目（已定义的空顺序表示“选择不使用任何配置文件”，这会禁用该 provider）。在 TTY 环境下会提示确认；脚本和 agent 请传入 --yes。如果该配置文件不在存储中，或者有 models.providers.<id>.apiKey 条目指向它，logout 会拒绝执行——请先更改该配置值。
models auth login-github-copilot 是 models auth login --provider github-copilot --method device（GitHub device flow）的快捷方式；它接受 --yes，可在不提示的情况下覆盖现有配置文件。
使用 openclaw models auth --agent <id> <subcommand> 可将认证结果写入某个特定的已配置 agent 存储。父级 --agent 标志适用于 add、list、login、logout、paste-api-key、setup-token、paste-token、login-github-copilot 以及 order get/set/clear。
对于 OpenAI 模型，--provider openai 默认使用 ChatGPT/Codex 账号登录。只有当你想添加 OpenAI API key 配置文件时才使用 --method api-key，通常这是 Codex 订阅额度的备用方案。运行 openclaw doctor --fix 可将旧版遗留的 OpenAI Codex 前缀认证/配置文件状态迁移到 openai。
示例：
paste-api-key接受在其他地方生成的 API key，会提示你输入 key 值，并将其写入默认配置文件 id<provider>:manual，除非你传入--profile-id。在自动化场景中，可以通过 stdin 管道传入 key，例如printf "%s\n" "$OPENAI_API_KEY" | openclaw models auth paste-api-key --provider openai。setup-token和paste-token仍然是适用于暴露 token 认证方法的 provider 的通用 token 命令。setup-token需要交互式 TTY，并运行 provider 的 token-auth 方法（默认使用该 provider 暴露的setup-token方法）。paste-token需要--provider，默认会提示输入 token 值，并将其写入默认配置文件 id<provider>:manual，除非你传入--profile-id。在自动化场景中，请通过 stdin 管道传入 token，而不要将其作为参数传递，这样 provider 凭据就不会出现在 shell 历史或进程列表中。paste-token --expires-in <duration>会将相对时长（例如365d或12h）保存为绝对 token 过期时间。- 对于
openai，OpenAI API key 和 ChatGPT/OAuth token 材料属于不同的认证形态。sk-...OpenAI API key 请使用paste-api-key，而paste-token仅用于 token 认证材料。 - Anthropic：
setup-token/paste-token是适用于anthropic的 OpenClaw 认证路径，但在主机上如果可用，OpenClaw 更倾向于复用 Claude CLI（claude -p）。 auth order get/set/clear管理某个 provider 的按 agent 认证配置文件顺序覆盖，该信息存储在auth-state.json中（与auth.order.<provider>配置键分开）。set按优先级顺序接收一个或多个 profile id；clear则回退到配置/轮询排序