跳转到主要内容

​
模型 CLI

参见 /concepts/model-failover 了解认证配置文件轮换、冷却时间及其与回退的交互。 快速提供商概述 + 示例：/concepts/model-providers。 Quick provider overview + examples: /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。

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

如果设置了 agents.defaults.models，它将成为 /model 和会话覆盖的白名单。当用户选择不在该白名单中的模型时，OpenClaw 返回： 当用户选择了不在该允许列表中的模型时， OpenClaw 会返回： 
Model "provider/model" is not allowed. Use /model to list available models.
这发生在正常回复生成之前，所以消息可能感觉像”没有响应”。修复方法是： 4. 修复方法是以下之一：
  • 将模型添加到 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-5": { alias: "Opus" },
    },
  },
}

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

你可以在不重启的情况下切换当前会话的模型： 
/model
/model list
/model 3
/model openai/gpt-5.2
/model status
注意事项：
  • /model（和 /model list）是紧凑的编号选择器（模型系列 + 可用提供商）。
  • /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

Shows the resolved primary model, fallbacks, image model, and an auth overview of configured providers. It also surfaces OAuth expiry status for profiles found in the auth store (warns within 24h by default). --plain prints only the resolved primary model. OAuth status is always shown (and included in --json output). If a configured provider has no credentials, models status prints a Missing auth section. JSON includes auth.oauth (warn window + profiles) and auth.providers (effective auth per provider). Use --check for automation (exit 1 when missing/expired, 2 when expiring). 首选的 Anthropic 认证是 Claude Code CLI setup-token（在任何地方运行；如需要在 Gateway 网关主机上粘贴）： 
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 仅列出候选项。 Without a key, use --no-probe to list candidates only. 扫描结果按以下顺序排名：
  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 接受默认值。 In non‑interactive mode, pass --yes to accept defaults.

​
模型注册表（models.json）

models.providers 中的自定义提供商会写入智能体目录下的 models.json（默认 ~/.openclaw/agents/<agentId>/models.json）。除非 models.mode 设置为 replace，否则此文件默认会被合并。 This file is merged by default unless models.mode is set to replace.