模型 CLI

有关认证配置轮换、冷却期以及与回退的交互方式，请参?/concepts/model-failover? 快速提供商概览 + 示例：/concepts/model-providers?

模型选择的工作原?

OpenClaw 按以下顺序选择模型?

  1. 主要模型（agents.defaults.model.primary ?agents.defaults.model）?
  2. agents.defaults.model.fallbacks 中的回退（按顺序）?
  3. 在移动到下一个模型之前，提供?*认证回退**在提供商内部发生?

相关?

  • agents.defaults.models ?OpenClaw 可以使用的模型白名单/目录（加别名）?
  • agents.defaults.imageModel 仅在主要模型无法接受图像时使用?
  • 每个代理的默认值可以通过 agents.list[].model 加上绑定覆盖 agents.defaults.model（请参阅 /concepts/multi-agent）?

快速模型选择（经验之谈）

  • GLM：在编程/工具调用方面略好?
  • MiniMax：在写作和氛围方面更好?

设置向导（推荐）

如果你不想手动编辑配置，请运行引导向导：

openclaw onboard

它可以为常见提供商设置模?+ 认证，包?OpenAI Code (Codex) 订阅（OAuth）和 Anthropic（推?API 密钥；也支持 claude setup-token）?

配置键（概览?

  • agents.defaults.model.primary ?agents.defaults.model.fallbacks
  • agents.defaults.imageModel.primary ?agents.defaults.imageModel.fallbacks
  • agents.defaults.models（白名单 + 别名 + 提供商参数）
  • models.providers（写?models.json 的自定义提供商）

模型引用规范化为小写。提供商别名?z.ai/* 规范化为 zai/*?

提供商配置示例（包括 OpenCode Zen）位?/gateway/configuration?

”模型不允?（以及回复为何停止）

如果设置?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）是一个紧凑的编号选择器（模型系列 + 可用提供商）?
  • ?Discord 上，/model ?/models 打开一个交互式选择器，包含提供商和模型下拉菜单以及提交步骤?
  • /model <#> 从该选择器中选择?
  • /model status 是详细视图（认证候选，以及已配置时的提供商端点 baseUrl + api 模式）?
  • 模型引用通过在第一?/ 处分割来解析。输?/model <ref> 时使?provider/model?
  • 如果模型 ID 本身包含 /（OpenRouter 样式），你必须包含提供商前缀（例如：/model openrouter/moonshotai/kimi-k2）?
  • 如果省略提供商，OpenClaw 将输入视为别名或**默认提供?*的模型（仅在模型 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 <name>：按提供商过?
  • --plain：每行一个模?
  • --json：机器可读输?

models status

显示已解析的主要模型、回退、图像模型，以及已配置提供商的认证概览。它还显示在认证存储中找到的 OAuth 过期状态（默认 24 小时内警告）。--plain 仅打印已解析的主要模型? OAuth 状态始终显示（并包含在 --json 输出中）。如果配置的提供商没有凭证，models status 打印一?*缺少认证**部分? JSON 包含 auth.oauth（警告窗?+ 配置）和 auth.providers（每个提供商的生效认证）? 使用 --check 进行自动化（缺少/过期时退?1，即将过期时退?2）?

首选的 Anthropic 认证?Claude Code CLI setup-token（在任何地方运行；如需要可在网关主机上粘贴）：

claude setup-token
openclaw models status

扫描（OpenRouter 免费模型?

openclaw models scan 检?OpenRouter ?免费模型目录*，并可选择探测模型以获取工具和图像支持?

关键标志?

  • --no-probe：跳过实时探测（仅元数据?
  • --min-params <b>：最小参数大小（十亿?
  • --max-age-days <days>：跳过较旧的模型
  • --provider <name>：提供商前缀过滤?
  • --max-candidates <n>：回退列表大小
  • --set-default：将 agents.defaults.model.primary 设置为第一个选择
  • --set-image：将 agents.defaults.imageModel.primary 设置为第一个图像选择

探测需?OpenRouter API 密钥（来自认证配置或 OPENROUTER_API_KEY）。没有密钥时，使?--no-probe 仅列出候选模型?

扫描结果排名?

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

输入

  • OpenRouter /models 列表（过?:free?
  • 需要来自认证配置或 OPENROUTER_API_KEY ?OpenRouter API 密钥（请参阅 /environment?
  • 可选过滤器：--max-age-days、--min-params、--provider、--max-candidates
  • 探测控制：--timeout、--concurrency

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

模型注册表（models.json?

models.providers 中的自定义提供商写入代理目录下的 models.json（默?~/.openclaw/agents/<agentId>/models.json）。默认情况下该文件会被合并，除非 models.mode 设置?replace?

匹配提供?ID 的合并模式优先级?

  • 代理 models.json 中已存在的非?apiKey/baseUrl 优先?
  • 空或缺失的代?apiKey/baseUrl 回退到配?models.providers?
  • 其他提供商字段从配置和规范化的目录数据刷新?