模型 CLI

认证配置轮换、冷却以及与回退的交互，详见 /concepts/model-failover。Provider 概览和示例：/concepts/model-providers。

模型选择机制

OpenClaw 按以下顺序选择模型：

  1. 主模型（agents.defaults.model.primary 或 agents.defaults.model）。
  2. 回退列表中的模型（agents.defaults.model.fallbacks，按顺序）。
  3. 在转向下一个模型之前，先在当前 provider 内进行认证配置轮换。

相关：

  • agents.defaults.models 是 OpenClaw 可使用的模型白名单/目录（以及别名）。
  • agents.defaults.imageModel 仅在主模型不支持图片时使用。
  • 每个 agent 可以通过 agents.list[].model 加上 bindings 覆盖 agents.defaults.model（详见 /concepts/multi-agent）。

模型选择策略

  • 主模型设置为你能用的最强的最新一代模型。
  • 回退列表用于成本/延迟敏感的任务和低风险聊天。
  • 对于启用了工具的 agent 或不可信的输入，避免使用旧的/较弱的模型。

配置向导（推荐）

不想手动编辑配置的话，运行引导向导：

openclaw onboard

它可以帮你设置常见 provider 的模型和认证，包括 OpenAI Code（Codex）订阅（OAuth）和 Anthropic（API key 或 claude setup-token）。

配置项（概览）

  • agents.defaults.model.primary 和 agents.defaults.model.fallbacks
  • agents.defaults.imageModel.primary 和 agents.defaults.imageModel.fallbacks
  • agents.defaults.models（白名单 + 别名 + provider 参数）
  • models.providers（自定义 provider，写入 models.json）

模型引用统一规范化为小写。z.ai/* 这样的 provider 别名会规范化为 zai/*。

Provider 配置示例（包括 OpenCode）在 /gateway/configuration 中。

“Model is not allowed”（以及为什么回复停了）

如果设置了 agents.defaults.models，它就成了 /model 和会话覆盖的白名单。当用户选择的模型不在白名单中时，OpenClaw 返回：

Model "provider/model" is not allowed. Use /model to list available models.

这发生在正常回复生成之前，所以消息看起来像是”没有回应”。解决方法：

  • 把模型加入 agents.defaults.models，或
  • 清除白名单（删除 agents.defaults.models），或
  • 从 /model list 中选择一个模型。

白名单配置示例：

{
  agent: {
    model: { primary: "anthropic/claude-sonnet-4-5" },
    models: {
      "anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
      "anthropic/claude-opus-4-6": { alias: "Opus" },
    },
  },
}

在聊天中切换模型（/model）

可以在当前会话中切换模型，无需重启：

/model
/model list
/model 3
/model openai/gpt-5.2
/model status

注意：

  • /model（和 /model list）是紧凑的编号选择器（模型系列 + 可用 provider）。
  • 在 Discord 上，/model 和 /models 会打开交互式选择器，有 provider 和模型下拉菜单以及提交步骤。
  • /model <#> 从选择器中选择。
  • /model status 是详细视图（认证候选和已配置 provider 端点的 baseUrl + api 模式）。
  • 模型引用按第一个 / 分割解析。使用 /model <ref> 时用 provider/model 格式。
  • 如果模型 ID 本身包含 /（OpenRouter 风格），必须带上 provider 前缀（例如：/model openrouter/moonshotai/kimi-k2）。
  • 如果省略 provider，OpenClaw 把输入当作别名或默认 provider 的模型处理（仅在模型 ID 中没有 / 时有效）。

完整命令行为/配置：斜杠命令。

CLI 命令

openclaw models list
openclaw models status
openclaw models set <provider/model>
openclaw models set-image <provider/model>

openclaw models aliases list
openclaw models aliases add <alias> <provider/model>
openclaw models aliases remove <alias>

openclaw models fallbacks list
openclaw models fallbacks add <provider/model>
openclaw models fallbacks remove <provider/model>
openclaw models fallbacks clear

openclaw models image-fallbacks list
openclaw models image-fallbacks add <provider/model>
openclaw models image-fallbacks remove <provider/model>
openclaw models image-fallbacks clear

openclaw models（不带子命令）等同于 models status。

models list

默认显示已配置的模型。常用参数：

  • --all：完整目录
  • --local：仅本地 provider
  • --provider <name>：按 provider 过滤
  • --plain：每行一个模型
  • --json：机器可读输出

models status

显示解析后的主模型、回退列表、图片模型，以及已配置 provider 的认证概览。也会显示认证存储中 OAuth profile 的过期状态（默认在 24 小时内预警）。--plain 只输出解析后的主模型。OAuth 状态始终显示（也包含在 --json 输出中）。如果已配置的 provider 没有凭证，models status 会打印 Missing auth 部分。JSON 包含 auth.oauth（预警窗口 + profile）和 auth.providers（每个 provider 的生效认证）。用 --check 做自动化检查（缺失/过期退出码 1，即将过期退出码 2）。

认证选择取决于 provider/账户。对于 always-on 的 Gateway 主机，API key 通常最可预测；订阅 token 流程也支持。

示例（Anthropic setup-token）：

claude setup-token
openclaw models status

扫描（OpenRouter 免费模型）

openclaw models scan 检查 OpenRouter 的免费模型目录，可以选择性地探测模型的工具和图片支持。

关键参数：

  • --no-probe：跳过实时探测（仅元数据）
  • --min-params <b>：最小参数量（十亿）
  • --max-age-days <days>：跳过较老的模型
  • --provider <name>：provider 前缀过滤
  • --max-candidates <n>：回退列表大小
  • --set-default：把首选设为 agents.defaults.model.primary
  • --set-image：把首选图片模型设为 agents.defaults.imageModel.primary

探测需要 OpenRouter API key（从认证配置或 OPENROUTER_API_KEY）。没有 key 时用 --no-probe 仅列出候选。

扫描结果排名依据：

  1. 图片支持
  2. 工具延迟
  3. 上下文大小
  4. 参数量

输入

  • OpenRouter /models 列表（过滤 :free）
  • 需要 OpenRouter API key（从认证配置或 OPENROUTER_API_KEY，详见 /environment）
  • 可选过滤器：--max-age-days、--min-params、--provider、--max-candidates
  • 探测控制：--timeout、--concurrency

在 TTY 中运行时可以交互式选择回退列表。非交互模式下用 --yes 接受默认值。

模型注册表（models.json）

models.providers 中的自定义 provider 写入 agent 目录下的 models.json（默认 ~/.openclaw/agents/<agentId>/agent/models.json）。这个文件默认使用合并模式，除非 models.mode 设为 replace。

合并模式下匹配 provider ID 的优先级：

  • agent models.json 中已有的非空 baseUrl 优先。
  • agent models.json 中的非空 apiKey 仅在该 provider 不是当前配置/认证上下文中 SecretRef 管理的时才优先。
  • SecretRef 管理的 provider apiKey 值从源标记刷新（环境变量引用用 ENV_VAR_NAME，文件/exec 引用用 secretref-managed），而不是持久化解析后的密钥。
  • SecretRef 管理的 provider header 值从源标记刷新（环境变量引用用 secretref-env:ENV_VAR_NAME，文件/exec 引用用 secretref-managed）。
  • 空的或缺失的 agent apiKey/baseUrl 回退到配置中的 models.providers。
  • 其他 provider 字段从配置和规范化的目录数据中刷新。

标记持久化以源配置为准：OpenClaw 从活跃的源配置快照（解析前）写入标记，而不是从运行时解析后的密钥值。这适用于 OpenClaw 重新生成 models.json 的任何场景，包括 openclaw agent 等命令驱动的路径。

arrow_back
上一页
Models
下一页
Model Providers
arrow_forward