Skip to main content

​
openclaw models

模型发现、扫描和配置（默认模型、回退、认证配置文件）。 相关：

​
常用命令

openclaw models status
openclaw models list
openclaw models set <model-or-alias>
openclaw models scan
openclaw models status 会显示解析后的默认值/回退项以及认证概览。 当可用提供方使用情况快照时，OAuth/API 密钥状态部分会包含 提供方使用窗口和配额快照。 当前使用窗口提供方：Anthropic、GitHub Copilot、Gemini CLI、OpenAI、 MiniMax、小米和 z.ai。使用认证来自各提供方特定的钩子， 如果可用；否则 OpenClaw 会回退到匹配 auth 配置文件、环境变量或配置中的 OAuth/API 密钥凭据。 在 --json 输出中，auth.providers 是感知环境/配置/存储的提供方 概览，而 auth.oauth 仅是 auth 存储配置文件健康状态。 添加 --probe 可针对每个已配置的提供方配置文件运行实时认证探测。 探测是真实请求（可能消耗 token 并触发速率限制）。 使用 --agent <id> 可检查某个已配置代理的模型/认证状态。省略时， 命令会使用 OPENCLAW_AGENT_DIR（如果已设置），否则使用 已配置的默认代理。 探测行可能来自 auth 配置文件、环境凭据或 models.json。 对于 OpenAI ChatGPT/Codex OAuth 排查，openclaw models status、 openclaw models auth list --provider openai 和 openclaw config get agents.defaults.model --json 是最快的方式，可确认某个代理是否 具有可用于 openai/* 的可用 openai OAuth 配置文件， 并通过原生 Codex 运行时使用。参见 OpenAI 提供方设置。 注意：
  • models set <model-or-alias> 接受 provider/model 或别名。
  • models list 是只读的：它会读取配置、auth 配置文件、现有目录 状态以及由提供方拥有的目录行，但不会重写 models.json。
  • Auth 列是提供方级别且只读。它由本地 auth 配置文件元数据、环境标记、已配置的提供方密钥、本地提供方 标记、AWS Bedrock 环境/配置文件标记以及插件合成认证元数据计算得出； 它不会加载提供方运行时、读取密钥环中的秘密、调用提供方 API，或证明逐模型的精确执行就绪状态。
  • models list --all --provider <id> 即使你尚未为该提供方认证， 也可以包含来自插件清单或内置提供方目录元数据的提供方拥有的静态目录 行。对于这些行，在匹配的认证配置好之前仍会显示为 不可用。
  • models list 会在提供方目录发现较慢时保持控制平面响应。默认和已配置视图 会在短暂等待后回退到已配置或合成模型行，并让发现在 后台继续完成。需要精确的完整发现目录且愿意等待提供方发现时， 使用 --all。
  • 广泛的 models list --all 会在不加载提供方运行时补充钩子的情况下，将清单目录行 与注册表行合并。按提供方过滤的清单快速路径仅使用标记为 static 的提供方；标记为 refreshable 的提供方仍保持注册表/缓存支持并附加清单行作为补充，而标记为 runtime 的提供方仍停留在注册表/运行时发现路径上。
  • models list 会保持原生模型元数据与运行时上限的区分。在表格 输出中，当有效运行时上限与原生上下文窗口不同时，Ctx 显示 contextTokens/contextWindow；JSON 行会在提供方暴露该上限时包含 contextTokens。
  • 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），而不是将其掩码为秘密。

​
Models scan

models scan 会读取 OpenRouter 的公开 :free 目录并为回退用途 对候选项进行排序。目录本身是公开的，因此仅元数据扫描不需要 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 需要实时探测；仅元数据的扫描结果 仅供参考，不会应用到配置中。

​
Models status

选项：
  • --json
  • --plain
  • --check（退出码 1=已过期/缺失，2=即将过期）
  • --probe（对已配置的认证配置文件进行实时探测）
  • --probe-provider <name>（探测一个提供方）
  • --probe-profile <id>（可重复或逗号分隔的配置文件 id）
  • --probe-timeout <ms>
  • --probe-concurrency <n>
  • --probe-max-tokens <n>
  • --agent <id>（已配置代理 id；覆盖 OPENCLAW_AGENT_DIR）
--json 会保留 stdout 仅用于 JSON 负载。认证配置文件、提供方和 启动诊断会路由到 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：提供方认证存在，但 OpenClaw 无法解析出该提供方可探测的 模型候选项。

​
别名 + 回退

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 login --provider openai --profile-id openai:work
openclaw models auth paste-api-key --provider <id>
openclaw models auth setup-token --provider <id>
openclaw models auth paste-token
models auth add 是交互式认证助手。它可以启动提供方认证 流程（OAuth/API 密钥），或根据你选择的提供方引导你手动粘贴令牌。 models auth list 会列出所选代理的已保存 auth 配置文件，而不会 打印 token、API 密钥或 OAuth 密钥材料。使用 --provider <id> 可过滤到 某个提供方，例如 openai，并使用 --json 供脚本处理。 models auth login 运行提供方插件的认证流程（OAuth/API 密钥）。使用 openclaw plugins list 可查看已安装哪些提供方。 使用 openclaw models auth --agent <id> <subcommand> 可将认证结果写入 特定的已配置代理存储。父级 --agent 标志会被 add、list、login、paste-api-key、setup-token、paste-token 和 login-github-copilot 继承。 对于 OpenAI 模型，--provider openai 默认使用 ChatGPT/Codex 账号登录。 仅在你想添加 OpenAI API 密钥配置文件时才使用 --method api-key， 通常作为 Codex 订阅限制的备用方案。运行 openclaw doctor --fix 可将旧版 OpenAI Codex 前缀认证/配置文件状态迁移到 openai。 示例： 
openclaw models auth login --provider openai --set-default
openclaw models auth login --provider openai --method api-key
openclaw models auth paste-api-key --provider openai
openclaw models auth list --provider openai
注意：
  • login 接受 --profile-id <id>，适用于在登录期间支持命名 配置文件的提供方。使用它可以将同一提供方的多个登录 分开保存。
  • paste-api-key 接受在别处生成的 API 密钥，提示输入密钥 值，并将其写入默认配置文件 id <provider>:manual，除非你 传入 --profile-id。在自动化中，可通过 stdin 传入密钥，例如 printf "%s\n" "$OPENAI_API_KEY" | openclaw models auth paste-api-key --provider openai。
  • setup-token 和 paste-token 仍然是针对暴露令牌认证方法的提供方的通用令牌命令。
  • setup-token 需要交互式 TTY，并运行提供方的令牌认证 方法（当该提供方暴露 setup-token 方法时，默认使用该方法）。
  • paste-token 接受在别处生成或来自自动化的令牌字符串。
  • paste-token 需要 --provider，默认提示输入令牌值， 并将其写入默认配置文件 id <provider>:manual，除非你传入 --profile-id。
  • 在自动化中，请通过 stdin 传入令牌，而不是将其作为参数传递，以便 提供方凭据不会出现在 shell 历史或进程列表中。
  • paste-token --expires-in <duration> 会将相对时长（如 365d 或 12h）存储为绝对令牌过期时间。
  • 对于 openai，OpenAI API 密钥和 ChatGPT/OAuth 令牌材料 是不同的认证形态。对于 sk-... OpenAI API 密钥请使用 paste-api-key，仅对令牌认证材料使用 paste-token。
  • Anthropic 说明：Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法现在再次被允许，因此除非 Anthropic 发布新政策，否则 OpenClaw 会将 Claude CLI 复用和 claude -p 用法视为该集成的获准方式。
  • Anthropic 的 setup-token / paste-token 仍作为受支持的 OpenClaw 令牌路径可用，但在可用时 OpenClaw 现在更倾向于使用 Claude CLI 复用和 claude -p。

​
相关