模型 CLI

auth profile 轮换、cooldown 与回退的交互方式参见 /openclaw/concepts/model-failover。 Provider 快速概述与示例参见 /openclaw/concepts/model-providers。

模型选择逻辑

OpenClaw 按以下顺序选择模型：

1. 主模型（agents.defaults.model.primary 或 agents.defaults.model）。
2. agents.defaults.model.fallbacks 中的备用模型（按顺序）。
3. Provider auth 故障转移在切换到下一个模型之前，在 provider 内部发生。

相关说明：

• agents.defaults.models 是 OpenClaw 可用模型的允许列表/目录（含别名）。
• agents.defaults.imageModel 仅在主模型无法接受图片时使用。
• agents.defaults.imageGenerationModel 由共享图像生成能力使用。若省略，image_generate 仍可从兼容的带认证图像生成插件中推断 provider 默认值。若指定了特定 provider/model，还需配置该 provider 的认证/API key。
• Per-agent 默认值可通过 agents.list[].model 加绑定覆盖 agents.defaults.model（参见 /openclaw/concepts/multi-agent）。

模型策略快速建议

• 将主模型设为你能用到的最强最新一代模型。
• 对成本/延迟敏感的任务和轻量聊天，使用 fallback 模型。
• 对于启用了工具的 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.imageGenerationModel.primary 和 agents.defaults.imageGenerationModel.fallbacks
• agents.defaults.models（允许列表 + 别名 + provider 参数）
• models.providers（写入 models.json 的自定义 provider）

Model ref 会被规范化为小写。Provider 别名如 z.ai/* 会规范化为 zai/*。

包含 OpenCode 的 provider 配置示例参见 /openclaw/providers/opencode（如有）。

"Model is not allowed"（以及回复中断的原因）

若设置了 agents.defaults.models，它将成为 /model 和 session 覆盖的允许列表。当用户选择了不在允许列表中的模型时，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-6" },
    models: {
      "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
      "anthropic/claude-opus-4-6": { alias: "Opus" },
    },
  },
}

聊天中切换模型（/model）

无需重启即可为当前 session 切换模型：

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

说明：

• /model（和 /model list）是紧凑的编号选择器（模型家族 + 可用 provider）。
• 在 Discord 上，/model 和 /models 会打开包含 provider 和模型下拉框及提交步骤的交互选择器。
• /model <#> 从该选择器中选择。
• /model status 是详细视图（auth 候选，以及已配置时的 provider 端点 baseUrl + api 模式）。
• Model ref 以第一个 / 分割解析。输入 /model <ref> 时请使用 provider/model。
• 若 model ID 本身包含 /（OpenRouter 风格），必须包含 provider 前缀（例如 /model openrouter/moonshotai/kimi-k2）。
• 若省略 provider，OpenClaw 将输入视为别名或默认 provider 的模型（仅当 model 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

显示解析后的主模型、fallback、图像模型，以及已配置 provider 的认证概览。还会显示 auth store 中找到的 profile 的 OAuth 过期状态（默认在 24 小时内发出警告）。--plain 仅打印解析后的主模型。OAuth 状态始终显示（也包含在 --json 输出中）。若已配置的 provider 无凭据，models status 会打印 Missing auth 部分。JSON 包含 auth.oauth（警告窗口 + profile）和 auth.providers（每个 provider 的有效认证）。使用 --check 可用于自动化（缺失/过期时退出码 1，即将过期时退出码 2）。

认证选择取决于 provider/账号。对于常驻 gateway 主机，API key 通常最可预测；订阅令牌流程也受支持。

示例（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>：fallback 列表大小
• --set-default：将第一个选择设为 agents.defaults.model.primary
• --set-image：将第一个图像选择设为 agents.defaults.imageModel.primary

探测需要 OpenRouter API key（来自 auth profile 或 OPENROUTER_API_KEY）。无 key 时使用 --no-probe 仅列出候选。

扫描结果按以下优先级排名：

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

输入：

• OpenRouter /models 列表（过滤 :free）
• 需要来自 auth profile 或 OPENROUTER_API_KEY 的 OpenRouter API key
• 可选过滤器：--max-age-days、--min-params、--provider、--max-candidates
• 探测控制：--timeout、--concurrency

在 TTY 中运行时可交互式选择 fallback。非交互模式下，传 --yes 接受默认值。

模型注册表（models.json）

models.providers 中的自定义 provider 会写入 agent 目录下的 models.json（默认为 ~/.openclaw/agents/<agentId>/agent/models.json）。除非 models.mode 设为 replace，否则默认以合并模式处理。

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

• agent models.json 中已有非空 baseUrl 的优先。
• 仅当该 provider 在当前 config/auth-profile 上下文中不受 SecretRef 管理时，agent models.json 中的非空 apiKey 才优先。
• SecretRef 管理的 provider apiKey 值会从源标记刷新（env ref 用 ENV_VAR_NAME，file/exec ref 用 secretref-managed），而非持久化已解析的密钥。
• SecretRef 管理的 provider header 值同样从源标记刷新。
• 空或缺失的 agent apiKey/baseUrl 回退到 config models.providers。
• 其他 provider 字段从 config 和规范化目录数据刷新。

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