OpenClaw 的模型 CLI 用于在聊天中实时切换模型、管理回退链和扫描 OpenRouter 免费模型。配置模型允许列表可防止「Model is not allowed」错误；使用 openclaw config set --merge 安全更新模型列表。模型选择优先走主模型，然后按顺序试 fallback，最后走 provider 内部 auth 故障转移。用户手动切换的模型是严格选定的，如果不可达会直接失败而不是静默 fallback。openclaw models scan 支持带实时探测（需 OpenRouter API key）或无 key 的元数据模式。

OpenClaw 模型 CLI：列表、切换、别名、回退和扫描配置

模型选择逻辑

OpenClaw 按以下顺序选择模型：

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

模型选择来源与回退行为

相同的 provider/model 在不同来源下含义不同：

配置的默认值（agents.defaults.model.primary 和 agent 级别的 primary）是正常入口，使用 agents.defaults.model.fallbacks。
自动回退选择是临时恢复状态。存储时带 modelOverrideSource: "auto"，后续轮次会继续使用回退链，而不会每次探测已知有问题的 primary；OpenClaw 会定期重新探测原始 primary，恢复后清除自动选择，每个状态变化只通知一次回退/恢复转换。
用户 session 选择是精确的。/model、模型选择器、session_status(model=...) 和 sessions.patch 存储 modelOverrideSource: "user"；若选择的 provider/model 不可达，OpenClaw 会可见地失败，而不回退到其他配置模型。
修改 agents.defaults.model.primary 不会重写现有 session 的选择。如果状态显示 This session is pinned to X; config primary Y will apply to new/unpinned sessions.，请用 /model Y 切换当前 session，或用 /reset 清除过期 session 状态。
Cron --model / payload model 是每个任务的 primary。如果任务没有提供显式 payload fallbacks，它仍然会使用配置的 fallback（用 fallbacks: [] 可严格限制 cron 运行不 fallback）。
CLI 默认模型和允许列表选择器尊重 models.mode: "replace"，通过列出显式 models.providers.*.models 而不是加载完整内置目录。
Control UI 模型选择器请求 Gateway 的配置模型视图：当存在 agents.defaults.models 时使用（包括 provider 范围的 provider/* 条目），否则使用显式 models.providers.*.models 加上可用认证的 provider。完整内置目录保留给显式浏览视图，如 models.list 搭配 view: "all" 或 openclaw models list --all。

快速模型策略

主模型设为你能用到的最强最新一代模型。
对成本/延迟敏感的任务和轻量聊天，使用 fallback 模型。
对于启用了工具的 agent 或不可信输入，避免使用较旧/较弱的模型。

上线引导（推荐）

如果不想手动编辑配置，运行上线引导：

bash

openclaw onboard

它能为常见 provider 配置模型+认证，包括 OpenAI Code（Codex）订阅（OAuth）和 Anthropic（API key 或 Claude CLI）。

配置键（概览）

agents.defaults.model.primary 和 agents.defaults.model.fallbacks
agents.defaults.imageModel.primary 和 agents.defaults.imageModel.fallbacks
agents.defaults.pdfModel.primary 和 agents.defaults.pdfModel.fallbacks
agents.defaults.imageGenerationModel.primary 和 agents.defaults.imageGenerationModel.fallbacks
agents.defaults.videoGenerationModel.primary 和 agents.defaults.videoGenerationModel.fallbacks
agents.defaults.models（允许列表 + 别名 + provider 参数 + provider/* 动态 provider 条目）
models.providers（写入 models.json 的自定义 provider）

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

安全编辑允许列表

手动更新 agents.defaults.models 时使用增量写入：

bash

openclaw config set agents.defaults.models '{"openai/gpt-5.4":{&#125;&#125;' --strict-json --merge

覆盖保护规则：

openclaw config set 保护模型/provider 映射不被意外覆盖。对 agents.defaults.models、models.providers 或 models.providers.<id>.models 的普通对象赋值，如果会移除已有条目则会被拒绝。使用 --merge 做增量修改；仅在提供的值应成为目标值时使用 --replace。

交互式 provider 设置和 openclaw configure --section model 也会将 provider 范围的选择合并到现有允许列表中，添加 Codex、Ollama 或其他 provider 不会丢弃无关的模型条目。当重新应用 provider auth 时，configure 会保留已有的 agents.defaults.model.primary。显式的默认值设置命令如 openclaw models auth login --provider <id> --set-default 和 openclaw models set <model> 仍然会替换 agents.defaults.model.primary。

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

若设置了 agents.defaults.models，它将成为 /model 和 session 覆盖的允许列表。当用户选择了不在允许列表中的模型时，OpenClaw 返回：

Model "provider/model" is not allowed. Use /models to list providers, or /models <provider> to list models.
Add it with: openclaw config set agents.defaults.models '{"provider/model":{&#125;&#125;' --strict-json --merge

⚠️ 这个检查发生在正常回复生成之前，因此消息会看起来像「没有响应」。解决方法：
将模型添加到 agents.defaults.models，或
清除允许列表（删除 agents.defaults.models），或
从 /model list 中选择一个模型。

如果被拒绝的命令包含运行时覆盖（如 /model openai/gpt-5.5 --runtime codex），先修复允许列表，再重试相同的 /model ... --runtime ... 命令。对于原生 Codex 执行，选中的模型仍是 openai/gpt-5.5；codex 运行时选择 harness 并单独使用 Codex auth。

对于本地/GGUF 模型，将完整的 provider 前缀 ref 存储在允许列表中，例如 ollama/gemma4:26b、lmstudio/Gemma4-26b-a4-it-gguf，或 openclaw models list --provider <provider> 显示的准确 provider/model。当允许列表激活时，仅裸本地文件名或显示名是不够的。

如果想限制 provider 而不手动列出每个模型，添加 provider/* 条目到 agents.defaults.models：

json5

{
  agents: {
    defaults: {
      models: {
        "openai-codex/*": {},
        "vllm/*": {},
      },
    },
  },
}

这样 /model、/models 和模型选择器只显示这些 provider 的可发现目录。所选 provider 的新模型出现时无需编辑允许列表。需要某个特定模型时，可以将精确的 provider/model 条目与 provider/* 条目混合使用。

允许列表配置示例：

json5

{
  agents: {
    defaults: {
      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.4
/model status

选择器行为

/model（和 /model list）是紧凑的编号选择器（模型家族 + 可用 provider）。
在 Discord 上，/model 和 /models 会打开包含 provider 和模型下拉框及提交步骤的交互选择器。
在 Telegram 上，/models 选择器的选择是 session 范围的；不会改变 agent 在 openclaw.json 中的持久默认值。
/models add 已弃用，现在返回弃用消息而非从聊天注册模型。
/model <#> 从该选择器中选择。

持久化与实时切换

/model 立即持久化新的 session 选择。
如果 agent 空闲，下一次运行立即使用新模型。
如果运行已激活，OpenClaw 标记实时切换为 pending，只在干净的 retry 点重启到新模型。
如果工具活动或回复输出已开始，pending 切换可能排队到稍后的 retry 机会或下一次用户轮次。
用户选择的 /model ref 对该 session 是严格的：如果选中的 provider/model 不可达，回复会可见地失败，而不是静默地使用 agents.defaults.model.fallbacks。这与配置默认值和 cron 任务 primary 不同，它们仍可使用回退链。
/model status 是详细视图（auth 候选，以及配置时的 provider 端点 baseUrl + api 模式）。

Ref 解析规则

Model ref 以第一个 / 分割解析。输入 /model <ref> 时请使用 provider/model。
若 model ID 本身包含 /（OpenRouter 风格），必须包含 provider 前缀（例如 /model openrouter/moonshotai/kimi-k2）。
若省略 provider，OpenClaw 按以下顺序解析：
1. 别名匹配
2. 唯一配置 provider 对该精确无前缀 model id 的匹配
3. 已弃用的回退到配置的默认 provider——如果该 provider 不再暴露配置的默认模型，OpenClaw 会回退到第一个配置的 provider/model，以避免暴露一个已移除 provider 的陈旧默认值。

CLI 命令

bash

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：完整目录。包括打包的 provider 自有静态目录行（在配置 auth 之前），因此发现视图可以显示在添加匹配 provider 凭据之前不可用的模型。
--local：仅本地 provider。
--provider <id>：按 provider id 过滤，例如 moonshot。不接受交互选择器中的显示标签。
--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 的有效认证，包括环境变量凭据）。auth.oauth 仅针对 auth-store profile 健康状态；仅环境变量的 provider 不会出现在那里。
使用 --check 可用于自动化（缺失/过期时退出码 1，即将过期时退出码 2）。
使用 --probe 进行实时认证检查；探测行可来自 auth profile、环境凭据或 models.json。
如果显式 auth.order.<provider> 跳过了某个存储的 profile，探测报告 excluded_by_auth_order 而不尝试它。如果 auth 存在但无法为该 provider 解析出可探测的模型，探测报告 status: no_model。

认证选择取决于 provider/账号。对于常驻 gateway 主机，API key 通常最可预测；Claude CLI 复用和已有的 Anthropic OAuth/token profile 也受支持。

示例（Claude CLI）：

bash

claude auth login
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 /models 目录是公开的，因此仅元数据扫描可以列出免费候选而无需 key。探测和推理仍然需要 OpenRouter API key（来自 auth profile 或 OPENROUTER_API_KEY）。如果没有 key，openclaw models scan 会回退到仅元数据输出并保持配置不变。使用 --no-probe 显式请求仅元数据模式。

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

图像支持
工具延迟
上下文大小
参数量

输入：

OpenRouter /models 列表（过滤 :free）
实时探测需要来自 auth profile 或 OPENROUTER_API_KEY 的 OpenRouter API key（参见环境变量）
可选过滤器：--max-age-days、--min-params、--provider、--max-candidates
请求/探测控制：--timeout、--concurrency

在 TTY 中运行时可交互式选择 fallback。非交互模式下，传 --yes 接受默认值。仅元数据结果仅供信息参考；--set-default 和 --set-image 需要实时探测，以避免配置一个没有 key 的不可用 OpenRouter 模型。

模型注册表（`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 值同样从源标记刷新（env ref 用 secretref-env:ENV_VAR_NAME，file/exec ref 用 secretref-managed）。
空或缺失的 agent apiKey/baseUrl 回退到 config models.providers。
其他 provider 字段从 config 和规范化目录数据刷新。

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

常见问题

为什么聊天回复显示「Model is not allowed」而且没有响应？

因为设置了 agents.defaults.models 允许列表，你选择的模型不在列表中。回复生成前就会中断，所以看起来像没回复。解决方法：将目标模型添加到允许列表（运行 openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge），或者删除整个 agents.defaults.models 配置，或者从 /model list 中选择一个已允许的模型。

如何在不重启 gateway 的情况下切换当前聊天的模型？

使用 /model 命令。例如 /model openai/gpt-5.4 可立即切换当前 session 的模型。如果想查看可选模型，运行 /model list。模型选择会持久化到该 session，下一次对话直接使用新模型。如果选中的模型不可达，你会收到明确的失败消息，而不是静默 fallback。

`openclaw models scan` 需要 OpenRouter API key 吗？

仅元数据扫描（--no-probe）不需要 key，可以直接列出免费的模型候选。但如果你想进行实时探测（检查工具、图像支持）或使用 --set-default/--set-image 自动配置，则必须提供 OpenRouter API key（通过 auth profile 或 OPENROUTER_API_KEY 环境变量）。没有 key 时，扫描会自动退回到仅元数据模式，不会修改配置。

OpenClaw 模型 CLI：列表、切换、别名、回退和扫描配置

模型选择逻辑

相关模型配置键

模型选择来源与回退行为

快速模型策略

上线引导（推荐）

配置键（概览）

安全编辑允许列表

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

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

选择器行为

持久化与实时切换

Ref 解析规则

CLI 命令

`models list`

`models status`

扫描（OpenRouter 免费模型）

模型注册表（`models.json`）

相关文档

常见问题

为什么聊天回复显示「Model is not allowed」而且没有响应？

如何在不重启 gateway 的情况下切换当前聊天的模型？

`openclaw models scan` 需要 OpenRouter API key 吗？

OpenClaw 模型 CLI：列表、切换、别名、回退和扫描配置 ​

模型选择逻辑 ​

相关模型配置键 ​

模型选择来源与回退行为 ​

快速模型策略 ​

上线引导（推荐） ​

配置键（概览） ​

安全编辑允许列表 ​

「Model is not allowed」（以及回复中断的原因） ​

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

选择器行为 ​

持久化与实时切换 ​

Ref 解析规则 ​

CLI 命令 ​

models list ​

models status ​

扫描（OpenRouter 免费模型） ​

模型注册表（models.json） ​

相关文档 ​

常见问题 ​

为什么聊天回复显示「Model is not allowed」而且没有响应？ ​

如何在不重启 gateway 的情况下切换当前聊天的模型？ ​

openclaw models scan 需要 OpenRouter API key 吗？ ​

OpenClaw 模型 CLI：列表、切换、别名、回退和扫描配置

模型选择逻辑

相关模型配置键

模型选择来源与回退行为

快速模型策略

上线引导（推荐）

配置键（概览）

安全编辑允许列表

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

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

选择器行为

持久化与实时切换

Ref 解析规则

CLI 命令

`models list`

`models status`

扫描（OpenRouter 免费模型）

模型注册表（`models.json`）

相关文档

常见问题

为什么聊天回复显示「Model is not allowed」而且没有响应？

如何在不重启 gateway 的情况下切换当前聊天的模型？

`openclaw models scan` 需要 OpenRouter API key 吗？