Models CLI

模型引用会选择提供商和模型。它们通常不会选择底层 Agent Runtimes。例如，openai/gpt-5.5 可以通过常规 OpenAI provider 路径运行，也可以通过 Codex app-server 运行时运行，具体取决于 agents.defaults.agentRuntime.id。在 Codex 运行时模式下，openai/gpt-* 引用并不意味着 API key 计费；凭证可以来自 Codex 账号或 openai-codex 凭证配置。请参阅 Agent Runtimes。

# 模型选择的工作方式

OpenClaw 按以下顺序选择模型：

# 选择来源和 fallback 行为

同一个 provider/model 可能有不同含义，具体取决于它的来源：

• 已配置默认值（agents.defaults.model.primary 和 agent 专属 primary）是常规起点，并使用 agents.defaults.model.fallbacks。
• 自动 fallback 选择是临时恢复状态。它们会与 modelOverrideSource: "auto" 一起存储，因此后续轮次可以继续使用 fallback 链，而无需先探测已知不可用的 primary。
• 用户会话选择是精确的。/model、模型选择器、session_status(model=...) 和 sessions.patch 会存储 modelOverrideSource: "user"；如果所选提供商/模型不可达，OpenClaw 会显式失败，而不是落到另一个已配置模型。
• Cron --model / payload model 是每个 job 的 primary。它仍会使用已配置的 fallback，除非该 job 提供显式 payload fallbacks（严格 cron 运行可使用 fallbacks: []）。
• CLI 默认模型和 allowlist 选择器会遵循 models.mode: "replace"，列出显式的 models.providers.*.models，而不是加载完整内置目录。
• Control UI 模型选择器会向 Gateway 网关请求其已配置的模型视图：存在 agents.defaults.models 时使用它，否则使用显式 models.providers.*.models 加上有可用凭证的提供商。完整内置目录仅保留给显式浏览视图，例如带 view: "all" 的 models.list 或 openclaw models list --all。

# 快速模型策略

• 将 primary 设置为你可用的最强最新一代模型。
• 对成本/延迟敏感任务和低风险聊天使用 fallback。
• 对启用了工具的 agent 或不受信任的输入，避免使用较旧/较弱的模型层级。

# 新手引导（推荐）

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

openclaw onboard

它可以为常见提供商设置模型 + 凭证，包括 OpenAI Code (Codex) subscription（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（allowlist + 别名 + 提供商参数）
• models.providers（写入 models.json 的自定义提供商）

# 安全编辑 allowlist

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

openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge

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

如果设置了 agents.defaults.models，它会成为 /model 和会话覆盖的 allowlist。当用户选择的模型不在该 allowlist 中时，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":{}}' --strict-json --merge

当被拒绝的命令包含运行时覆盖（例如 /model openai/gpt-5.5 --runtime codex）时，请先修复 allowlist，然后重试相同的 /model ... --runtime ... 命令。对于原生 Codex 执行，所选模型仍是 openai/gpt-5.5；codex 运行时会选择 harness，并单独使用 Codex 凭证。

对于本地/GGUF 模型，请在 allowlist 中存储完整的带提供商前缀引用， 例如 ollama/gemma4:26b、lmstudio/Gemma4-26b-a4-it-gguf，或 openclaw models list --provider <provider> 显示的精确 provider/model。 当 allowlist 处于启用状态时，仅使用本地文件名或显示名称是不够的。

allowlist 配置示例：

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

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

你可以在不重启的情况下为当前会话切换模型：

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

完整命令行为/配置：Slash commands。

# 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

默认显示已配置/认证可用的模型。常用标志：

--allboolean

完整目录。在配置认证之前包含内置的、由提供商拥有的静态目录行，因此仅发现视图可以显示那些在你添加匹配的提供商凭证之前不可用的模型。

--localboolean

仅本地提供商。

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcHJvdmlkZXIgPGlk " type="string"> 按提供商 id 过滤，例如 moonshot。不接受交互式选择器中的显示标签。

--plainboolean

每行一个模型。

--jsonboolean

机器可读输出。

# models status

显示解析后的主模型、回退模型、图像模型，以及已配置提供商的认证概览。它还会显示在认证存储中找到的配置文件的 OAuth 过期状态（默认在 24 小时内警告）。--plain 仅打印解析后的主模型。

示例（Claude CLI）：

claude auth login
openclaw models status

# 扫描（OpenRouter 免费模型）

openclaw models scan 会检查 OpenRouter 的免费模型目录，并可选择探测模型的工具和图像支持。

--no-probeboolean

跳过实时探测（仅元数据）。

"--min-params

"--max-age-days

"--provider

"--max-candidates

--set-defaultboolean

将 agents.defaults.model.primary 设置为第一个选择项。

--set-imageboolean

将 agents.defaults.imageModel.primary 设置为第一个图像选择项。

扫描结果按以下顺序排名：

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

输入：

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

当实时探测在 TTY 中运行时，你可以交互式选择回退模型。在非交互模式下，传入 --yes 以接受默认值。仅元数据结果只提供信息；--set-default 和 --set-image 需要实时探测，这样 OpenClaw 才不会配置无法使用的无 key OpenRouter 模型。

# 模型注册表（models.json）

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

# 相关

• Agent Runtimes — Pi、Codex 和其他 Agent loop 运行时
• 配置参考 — 模型配置键
• 图像生成 — 图像模型配置
• 模型故障转移 — 回退链
• 模型提供商 — 提供商路由和认证
• 音乐生成 — 音乐模型配置
• 视频生成 — 视频模型配置