CLI模型 CLI

身份配置文件轮换、冷却期，以及它们如何与故障转移交互。

提供商快速概览和示例。

OpenClaw、Codex 和其他代理循环运行时。

模型配置键。

模型引用选择提供商和模型。它们通常不选择底层的代理运行时。OpenAI 代理引用是主要的例外：openai/gpt-5.5 在官方 OpenAI 提供商上默认通过 Codex 应用服务器运行时运行。订阅版 Copilot 引用（github-copilot/*）还可以选择加入外部 GitHub Copilot 代理运行时插件 —— 该路径保持显式（没有 auto 回退）。显式的运行时覆盖属于提供商/模型策略，而不属于整个代理或会话。在 Codex 运行时模式下，openai/gpt-* 引用并不意味着 API 密钥计费；身份验证可以来自 Codex 账户或 openai OAuth 配置文件。请参阅代理运行时和GitHub Copilot 代理运行时。

模型选择如何工作

OpenClaw 按以下顺序选择模型：

Primary 模型
agents.defaults.model.primary（或 agents.defaults.model）。
Fallbacks
agents.defaults.model.fallbacks（按顺序）。
提供商身份验证故障转移
身份验证故障转移在移至下一个模型之前在提供商内部发生。

Related 模型 surfaces

agents.defaults.modelsOpenClaw 是 OpenClaw 可以使用的模型允许列表/目录（以及别名）。使用 provider/* 条目来限制可见的提供商，同时保持提供商发现为动态。
agents.defaults.imageModel 仅当主模型无法接受图像时才使用。
agents.defaults.pdfModel 由 pdf 工具使用。如果省略，该工具将回退到 agents.defaults.imageModel，然后是已解析的会话/默认模型。
agents.defaults.imageGenerationModel 由共享图像生成功能使用。如果省略，image_generateAPI 仍然可以推断一个支持身份验证的提供商默认值。它首先尝试当前的默认提供商，然后按提供商 ID 顺序尝试剩余的已注册图像生成提供商。如果您设置了特定的提供商/模型，还请配置该提供商的 auth/API 密钥。
agents.defaults.musicGenerationModel 由共享音乐生成功能使用。如果省略，music_generateAPI 仍然可以推断一个支持身份验证的提供商默认值。它首先尝试当前的默认提供商，然后按提供商 ID 顺序尝试剩余的已注册音乐生成提供商。如果您设置了特定的提供商/模型，还请配置该提供商的 auth/API 密钥。
agents.defaults.videoGenerationModel 由共享视频生成功能使用。如果省略，video_generateAPI 仍然可以推断一个支持身份验证的提供商默认值。它首先尝试当前的默认提供商，然后按提供商 ID 顺序尝试剩余的已注册视频生成提供商。如果您设置了特定的提供商/模型，还请配置该提供商的 auth/API 密钥。
每个代理的默认值可以通过 agents.list[].model 加上绑定来覆盖 agents.defaults.model（请参阅多代理路由）。

选择来源和回退行为

相同的 provider/model 可能因其来源不同而含义不同：

配置的默认值（agents.defaults.model.primary 和特定于代理的主要模型）是常规的起点，并使用 agents.defaults.model.fallbacks。
自动故障转移选择是临时的恢复状态。它们通过 modelOverrideSource: "auto" 存储，以便后续轮次可以继续使用故障转移链，而无需每次都探测已知损坏的主要模型；OpenClaw 会定期再次探测原始的主要模型，并在其恢复时清除自动选择，且每次状态变更仅宣布一次故障转移/恢复转换。
用户会话选择是精确的。/model、模型选择器 session_status(model=...) 和 sessions.patch 存储 modelOverrideSource: "user"；如果所选的提供商/模型不可达，OpenClaw 将明显失败，而不是回退到另一个配置的模型。
更改 agents.defaults.model.primary 不会重写现有的会话选择。如果状态显示 This session is pinned to X; config primary Y will apply to new/unpinned sessions.，请使用 /model Y 切换当前会话，或使用 /reset 清除过时的会话状态。
Cron --model / 负载 model 是每个作业的主要模型。除非作业提供了明确的负载 fallbacks（使用 fallbacks: [] 进行严格的 Cron 运行），否则它仍使用配置的故障转移。
CLI default-模型和 allowlist 选择器通过列出明确的 models.providers.*.models 而不是加载完整的内置目录来遵循 models.mode: "replace"。
控制 UI 模型选择器向 Gateway(网关) 请求其配置的模型视图：如果存在，则为 agents.defaults.models，包括提供商范围的 provider/* 条目；否则为明确的 models.providers.*.models 加上具有可用身份验证的提供商。完整的内置目录保留用于明确的浏览视图，例如带有 view: "all" 或 openclaw models list --all 的 models.list。

快速模型策略

将您的主模型设置为可用的最强最新一代模型。
对于成本/延迟敏感的任务和低风险聊天，使用回退模型。
对于启用工具的代理或不受信任的输入，请避免使用较旧/较弱的模型层级。

新手引导（推荐）

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

openclaw onboard

它可以为常见提供商设置模型 + 身份验证，包括 OpenAI Code (Codex) 订阅（OAuth）和 Anthropic（API 密钥或 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 + aliases + 提供商 params + provider/* 动态提供商条目）
models.providers（写入 models.json 的自定义提供商）

安全 allowlist 编辑

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

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

覆盖保护规则

openclaw config set 可保护模型/提供商映射免遭意外覆盖。当对 agents.defaults.models、models.providers 或 `models.providers.

.models进行普通对象赋值会移除现有条目时，该操作将被拒绝。使用—merge进行增量更改；仅当提供的值应成为完整目标值时才使用—replace`。

交互式提供商设置和 `openclaw configure --section model` 也会将提供商范围内的选择合并到现有的 allowlist 中，因此添加 Codex、Ollama 或其他提供商不会丢弃不相关的模型条目。当重新应用提供商身份验证时，Configure 会保留现有的 `agents.defaults.model.primary`。显式设置默认值的命令（例如 `openclaw models auth login --provider

—set-default和openclaw models set

）仍会替换 agents.defaults.model.primary`。

“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）时，请先修复允许列表，然后重试相同的 /model ... --runtime ... 命令。对于原生 Codex 执行，所选的模型仍然是 openai/gpt-5.5；codex 运行时会选择线束并单独使用 Codex 身份验证。

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

如果您想在不手动列出每个模型的情况下限制提供商，请向 agents.defaults.models 添加 provider/* 条目：

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

使用该策略时，/model、/models 和模型选择器将仅显示这些提供商的已发现目录。来自所选提供商的新模型可以在不编辑允许列表的情况下出现。当您需要来自另一个提供商的某个特定模型时，可以将确切的 provider/model 条目与 provider/* 条目混合使用。

允许列表配置示例：

{
  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`)

您可以无需重新启动即可为当前会话切换模型：

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

Picker behavior

/model（以及 /model listDiscord）是一个紧凑的、带编号的选择器（模型系列 + 可用提供商）。
在 Discord 上，/model 和 /modelsTelegram 会打开一个交互式选择器，其中包含提供商和模型下拉菜单以及提交步骤。
在 Telegram 上，/models 选择器选择的范围限定为会话；它们不会更改 openclaw.json 中代理的持久默认值。
/models add 已弃用，现在返回弃用消息而不是从聊天中注册模型。
/model <#> 从该选择器中进行选择。

持久化和实时切换

/model 会立即保存新的会话选择。
如果代理处于空闲状态，下一次运行将立即使用新模型。
如果运行已在进行中，OpenClaw 会将实时切换标记为待处理，并仅在干净的重试点重启到新模型。
如果工具活动或回复输出已经开始，待处理的切换可能会保持排队，直到出现稍后的重试机会或下一次用户轮次。
用户选择的 /model 引用对该会话是严格的：如果所选提供商/模型无法访问，回复将明显失败，而不是悄悄地 agents.defaults.model.fallbacks 进行回答。这与配置的默认值和定时作业主设置不同，后者仍可使用回退链。
/model status 是详细视图（认证候选者，以及在配置时，提供商端点 baseUrl + api 模式）。

引用解析

模型引用通过在 第一个 / 处拆分来解析。输入 `/model

时请使用provider/model。 - 如果模型 ID 本身包含 /（OpenRouter 风格），则必须包含提供商前缀（示例：/model openrouter/moonshotai/kimi-k2`）。 - 如果省略提供商，OpenClaw 将按以下顺序解析输入： 1. 别名匹配 2. 该确切无前缀模型 ID 的唯一已配置提供商匹配 3. 已弃用，回退到配置的默认提供商 — 如果该提供商不再暴露配置的默认模型，OpenClaw 将改为回退到第一个配置的提供商/模型，以避免显示过时的已移除提供商默认值。

完整命令行为/配置：斜杠命令。

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`

默认显示已配置/可进行身份验证的模型。有用的标志：

完整目录。包括在配置身份验证之前捆绑的提供商拥有的静态目录行，以便仅发现的视图可以显示在您添加匹配的提供商凭据之前不可用的模型。仅本地提供商。按提供商 ID 过滤，例如 `moonshot`。不接受来自交互式选择器的显示标签。每行一个模型。机器可读输出。

`models status`

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

Auth and probe behavior

OAuth 状态始终显示（并包含在 --json 输出中）。如果配置的提供商没有凭据，models status 会打印一个 Missing auth 部分。
JSON 包含 auth.oauth（警告窗口 + 配置文件）和 auth.providers（每个提供商的有效身份验证，包括支持 env 的凭据）。auth.oauth 仅显示 auth-store 配置文件运行状况；仅限 env 的提供商不会出现在那里。
使用 --check 进行自动化（当缺失/过期时退出 1，即将过期时退出 2）。
使用 --probe 进行实时身份验证检查；探测行可以来自身份验证配置文件、env 凭据或 models.json。
如果显式的 `auth.order.

省略了存储的配置文件，探测将报告excluded_by_auth_order而不是尝试它。如果身份验证存在但无法为该提供商解析可探测的模型，探测将报告status: no_model`。

示例 (Claude CLI)：

claude auth login
openclaw models status

扫描 (OpenRouter 免费模型)

openclaw models scan 检查 OpenRouter 的 free 模型 catalog，并可选择探测模型以获取工具和图像支持。

跳过实时探测（仅限元数据）。最小参数规模（十亿）。跳过旧模型。提供商前缀过滤器。回退列表大小。将 `agents.defaults.model.primary` 设置为首个选择。将 `agents.defaults.imageModel.primary` 设置为首张图片选择。

扫描结果按以下标准排序：

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

输入：

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

当实时探针在 TTY 中运行时，您可以交互式地选择回退选项。在非交互模式下，传递 --yes 以接受默认值。仅元数据的结果仅供参考；--set-default 和 --set-imageOpenClawOpenRouter 需要实时探针，因此 OpenClaw 不会配置不可用的无密钥 OpenRouter 模型。

模型注册表 (`models.json`)

models.providers 中的自定义提供商被写入 agent 目录下的 models.json（默认为 ~/.openclaw/agents/<agentId>/agent/models.json）。提供商插件目录作为生成的插件拥有的目录片段存储在 agent 的插件状态下并自动加载。除非将 models.mode 设置为 replace，否则默认合并此文件。

合并模式优先级

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

Agent models.json 中已存在的非空 baseUrl 优先。
Agent models.json 中的非空 apiKey 仅在该提供商在当前配置/身份配置文件上下文中不由 SecretRef 管理时才优先。
SecretRef 管理的提供商 apiKey 值从源标记（环境引用为 ENV_VAR_NAME，文件/exec 引用为 secretref-managed）刷新，而不是持久化已解析的密钥。
SecretRef 管理的提供商标头值从源标记（环境引用为 secretref-env:ENV_VAR_NAME，文件/exec 引用为 secretref-managed）刷新。
空或缺失的 agent apiKey/baseUrl 回退到配置 models.providers。
其他提供商字段从配置和规范化目录数据刷新。