模型 CLI

模型引用（provider/model）用于选择提供商和模型，而不是底层 Agent 运行时。当未设置运行时策略或策略为 auto 时，仅当路由是完全匹配的官方 HTTPS Platform Responses 或 ChatGPT Responses 路由，且没有用户编写的请求覆盖时，OpenAI provider 自有的 路由策略才可能选择 Codex；仅有 openai/* 前缀绝不会选择 Codex。Completions 适配器、自定义 端点以及用户编写的请求行为仍使用 OpenClaw。官方明文 HTTP 端点会被拒绝。请参阅 OpenAI 隐式 Agent 运行时。

订阅版 Copilot 引用（github-copilot/*）可以选择使用外部 GitHub Copilot agent runtime 插件，但该路径始终需要显式选择（绝不会 由 auto 选择）。运行时覆盖应配置在提供商/模型策略上，而不是配置在 整个智能体或会话上。运行时选择并不决定计费方式： OpenAI API 密钥凭据与 ChatGPT/Codex 订阅凭据仍相互独立。请参阅 Agent Runtimes 和 GitHub Copilot agent runtime。

选择顺序

相关模型配置项：

• agents.defaults.models 存储别名和每个模型的设置。添加条目不会限制模型覆盖。
• agents.defaults.modelPolicy.allow 是可选的覆盖允许列表。使用精确引用或尾部前缀通配符，例如 provider/* 和 provider/namespace/*；省略该项或将 [] 设置为允许任意模型。每个智能体的 agents.entries.*.modelPolicy.allow 会替换该智能体的默认策略。
• agents.defaults.utilityModel 是用于简短内部任务的可选低成本模型，例如生成的仪表板会话标题、受支持渠道的线程/主题标题以及进度叙述。每个智能体的 agents.entries.*.utilityModel 会覆盖它。未设置时，如果主提供商声明了小模型默认值，OpenClaw 会使用该值（OpenAI → gpt-5.6-luna，Anthropic → claude-haiku-4-5）；否则使用智能体的主模型。将其设置为空字符串可禁用实用模型路由。使用不同的实用模型生成标题失败时，会使用主模型重试一次。对于仪表板标题，自动实用模型派生和常规回退会遵循有效会话提供商及身份验证配置文件；显式配置的实用模型则保留其已配置的提供商/身份验证。空实用模型只会跳过备用小模型路由，不会跳过仪表板标题生成。实用任务是独立的模型调用，可能会将有限的任务内容发送给所选模型提供商。
• agents.defaults.imageModel 仅在主模型无法接受图像时使用。
• agents.defaults.pdfModel 由 pdf 工具使用。如果未设置，该工具会回退到 imageModel，然后回退到解析后的会话/默认模型。
• agents.defaults.mediaModels.{image,music,video} 为共享媒体生成工具提供支持。如果未设置，每个工具会推断具有身份验证支持的提供商默认值：先使用当前默认提供商，然后按照提供商 ID 顺序尝试其余为该能力注册的提供商。跨提供商回退是固定的默认行为。
• 每个智能体的 agents.entries.*.model（以及绑定）会覆盖 agents.defaults.model —— 请参阅多智能体路由。

完整键参考、默认值和 JSON5 示例：配置参考。

选择来源和回退严格性

同一个 provider/model 会因其来源不同而表现不同：

其他选择规则：

• 更改 agents.defaults.model.primary 不会重写现有会话固定设置。如果状态报告 This session is pinned to X; config primary Y will apply to new/unpinned sessions.，请运行 /model default 清除固定设置。
• CLI 默认模型和允许列表选择器会遵循 models.mode: "replace"，仅列出 models.providers.*.models，而不是完整的内置目录。
• Control UI 模型选择器会向 Gateway 网关请求其已配置的模型视图。显式的 modelPolicy.allow 会对其进行筛选，包括尾部前缀通配符条目；否则，它会显示已配置的模型以及具有可用身份验证的提供商。完整内置目录仅用于显式浏览视图（带有 view: "all" 的 models.list，或 openclaw models list --all）。
• 提供商清单 UI 使用带有 view: "provider-config" 的 models.list，显示由来源编写的 models.providers.*.models 行，而不应用选择器允许列表。

完整机制：模型故障转移。

快速模型策略

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

新手引导

openclaw onboard

无需手动编辑配置，即可为常用提供商设置模型和身份验证，包括 OpenAI Codex 订阅 OAuth 和 Anthropic（API 密钥或复用 Claude CLI）。

如果未配置主模型，全新 OpenAI API 密钥设置会选择 openai/gpt-5.6；不带限定的直接 API ID 会解析到 Sol 层级。全新 ChatGPT/Codex OAuth 设置会选择精确的 openai/gpt-5.6-sol 目录引用。 重新进行身份验证时会保留现有的显式主模型，包括 openai/gpt-5.5。如果账户无法使用 GPT-5.6，请显式选择 openai/gpt-5.5；OpenClaw 不会在不提示的情况下将其降级。

“不允许使用该模型”（以及回复为何停止）

如果 agents.defaults.modelPolicy.allow 非空，它会成为 /model、会话覆盖和 --model 的允许列表。选择允许列表之外的模型时，系统会在生成任何正常回复之前返回。每个智能体的 agents.entries.*.modelPolicy.allow 会替换该智能体的默认策略。

agents.defaults.modelPolicy.allow 不允许模型覆盖“provider/model”。请将“provider/model”“provider/*”或更窄的“provider/namespace/*”前缀添加到 agents.defaults.modelPolicy.allow，或者删除/清空该列表以允许任意模型。

修复方法是将模型或提供商通配符添加到指定的 modelPolicy.allow 键、删除/清空该列表，或从 /model list 中选择模型。如果被拒绝的命令包含运行时覆盖（例如 /model openai/gpt-5.5 --runtime codex），请先修复允许列表，然后重试同一命令。

对于本地/GGUF 模型，允许列表需要完整的提供商前缀引用，例如 ollama/gemma4:26b 或 lmstudio/Gemma4-26b-a4-it-gguf —— 请查看 openclaw models list --provider <provider> 以获取精确字符串。允许列表启用后，仅使用文件名或显示名称是不够的。

要限制提供商而不逐一列出每个模型，请使用尾部前缀通配符条目。提供商范围的 provider/* 会匹配该提供商下的所有模型；更窄的前缀（例如 clawrouter/anthropic/*）仅匹配该命名空间：

{  agents: {    defaults: {      modelPolicy: {        allow: ["openai/*", "vllm/*"],      },    },  },}

随后，/model、/models 和模型选择器只会显示这些提供商的已发现目录，并且新模型无需编辑允许列表即可出现。将精确的 provider/model 条目与 provider/* 条目混合使用，可引入另一个提供商的某个特定模型。

包含别名和每个模型设置的允许列表示例：

{  agents: {    defaults: {      model: { primary: "anthropic/claude-sonnet-4-6" },      modelPolicy: {        allow: ["anthropic/claude-sonnet-4-6", "anthropic/claude-opus-4-6"],      },      models: {        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },        "anthropic/claude-opus-4-6": { alias: "Opus" },      },    },  },}

openclaw config set agents.defaults.modelPolicy.allow '["openai/gpt-5.4","anthropic/*"]' --strict-json

聊天中的 /model

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

• /model 和 /model list 会显示一个紧凑的编号选择器（模型系列 + 可用提供商）；/model <#> 从中进行选择。在 Discord 上，这会打开提供商/模型下拉菜单，并包含一个 Submit 步骤；在 Telegram 上，选择器中的选择仅作用于会话，绝不会改写 openclaw.json 中智能体的持久默认值。/models add 已弃用，它会返回一条消息，而不是从聊天中注册模型。
• /model 会立即持久化新的会话选择。如果智能体处于空闲状态，下一次运行会立即使用它；如果已有运行正在进行，切换会排队等到下一个可安全重试的节点（如果工具活动或回复输出已经开始，则等待之后的节点）。
• /model default 会清除会话选择，使其重新继承已配置的主模型。
• 用户选择的 /model 引用对该会话是严格的：如果它变得不可访问，回复会明确失败，而不是通过 agents.defaults.model.fallbacks 静默回退。已配置的默认值和定时任务的主模型仍会使用回退链。
• /model status 是详细视图：显示每个提供商的身份验证候选项，以及（配置后）提供商端点 baseUrl 和 api 模式。
• 模型引用通过在第一个 / 处拆分来解析；请输入 provider/model。如果模型 ID 本身包含 /（OpenRouter 风格），请包含提供商前缀，例如 /model openrouter/moonshotai/kimi-k2。如果省略提供商，OpenClaw 会依次尝试：(1) 匹配别名；(2) 对该未加前缀的确切模型 ID 进行唯一的已配置提供商匹配；(3) 使用已配置的默认提供商（已弃用的回退）——如果该提供商已不再提供已配置的默认模型，则改用第一个已配置的提供商/模型，以免暴露已被移除提供商的过时默认值。
• 模型引用会规范化为小写；提供商 ID 在其他方面则要求完全匹配，因此请使用插件公布的 ID。

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

CLI

openclaw models statusopenclaw models listopenclaw models set <provider/model>openclaw models set-image <provider/model>openclaw models scanopenclaw models aliases list|add|removeopenclaw models fallbacks list|add|remove|clearopenclaw models image-fallbacks list|add|remove|clearopenclaw models auth list|add|login|paste-api-key|paste-token|setup-token|order

不带子命令的 openclaw models 是 models status 的快捷方式，后者还会显示身份验证存储配置文件的 OAuth 到期状态（默认在 24h 内到期时发出警告）。完整的标志、JSON 结构和身份验证配置文件子命令：模型 CLI 参考。

模型注册表（models.json）

在 models.providers 下配置的自定义提供商会写入智能体目录下的 models.json（默认值为 ~/.openclaw/agents/<agentId>/agent/models.json）。提供商插件目录会单独存储为由插件拥有的已生成目录分片，并自动加载。默认情况下，此文件会与配置合并；将 models.mode: "replace" 设置为仅使用你配置的提供商。

标记持久化以来源为准：每当 OpenClaw 重新生成 models.json 时（包括 openclaw agent 等由命令驱动的路径），都会从活动来源配置快照（解析前）写入标记，而不是从运行时已解析的机密值写入。

相关内容

• Agent Runtimes — OpenClaw、Codex 和其他 Agent loop 运行时
• 配置参考 — 模型配置键
• 图像生成 — 图像模型配置
• 模型故障转移 — 回退链
• 模型提供商 — 提供商路由和身份验证
• 模型 CLI 参考 — 完整的命令和标志参考
• 音乐生成 — 音乐模型配置
• 视频生成 — 视频模型配置