模型 CLI

​

选择顺序

• 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），否则使用该代理的主模型；将其设置为空字符串可禁用 utility 路由。生成的标题在不同的 utility 模型失败后，会使用主模型重试一次。对于仪表板标题，自动 utility 推导和常规回退会遵循有效的会话提供方和认证配置文件；显式的 utility 模型会保留其配置的提供方/认证。空的 utility 模型仅会跳过备用小模型路径，不会跳过仪表板标题生成。utility 任务是独立的模型调用，可能会向所选模型提供方发送有限范围的任务内容。
• agents.defaults.imageModel 仅在主模型无法接受图像时使用。
• agents.defaults.pdfModel 由 pdf 工具使用。若未设置，该工具会回退到 imageModel，然后回退到解析后的会话/默认模型。
• agents.defaults.mediaModels.{image,music,video} 为共享的媒体生成工具提供支持。若未设置，每个工具都会推断一个基于认证的提供方默认值：先使用当前默认提供方，然后按提供方 ID 顺序使用该能力的其余已注册提供方。跨提供方回退是固定的默认行为。
• 按代理的 agents.entries.*.model（以及绑定）会覆盖 agents.defaults.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 会对其进行过滤，包括尾随前缀通配符条目；否则它会显示已配置的模型以及具有可用认证的提供方。默认和已配置的选择器视图会隐藏标记为 deprecated 或 disabled 的目录行，除非该精确模型被配置为 primary、fallback、utility/tool model、别名/设置键，或精确的策略条目。隐藏行仍可通过精确的 provider/model 引用进行选择。完整的内置目录（包括隐藏行）仅保留给显式浏览视图（models.list 且 view: "all"，或 openclaw models list --all）。
• Provider inventory 界面使用带有 view: "provider-config" 的 models.list 来显示源头编写的 models.providers.*.models 行，而不应用选择器允许列表。

​

快速模型策略

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

​

入门

openclaw onboard

​

“模型不被允许”（以及为什么回复会停止）

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

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

{
  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 openai/gpt-5.4 -s
/model default -s
/model default
/model status

• /model 和 /model list 会显示一个紧凑的编号选择器（模型系列 + 可用提供商）；/model <#> 可从中选择。Telegram 的回调选择器仅作用于当前会话。Discord 的选择器遵循直接命令流程，因此所有者/管理员提交后会请求更新已配置的默认值。/models add 已弃用，现在会返回一条消息，而不会从聊天中注册模型。
• 已配置的默认值： 直接由所有者/管理员执行 /model <model> 会更改当前会话，并请求尽力更新有效的已配置默认值。如果代理存在显式主模型，OpenClaw 会以其为目标；否则会以共享的 agents.defaults.model 回退值为目标。不可变配置保持不变，异步写入失败会被记录日志，但不会回滚会话中的模型选择。
• 仅当前会话： /model <model> -s（或 --session）会更改当前会话，而不会更改任何一个已配置的默认值。非所有者执行不带参数的 /model <model> 时，也仅作用于当前会话，因为该调用者无法写入已配置的默认值。只要提供商仍支持显式用户选择的模型和身份验证配置文件，它们就会在 /new、/reset、会话轮换、压缩和冷却窗口期间保持固定；自动配置文件固定可能会轮换或清除。
• 使用已配置的默认值： /model default（带或不带 -s）会清除当前会话的模型选择，使其继承当前有效的已配置默认值。兼容的身份验证配置文件固定会保留；不兼容的固定会被清除。它不会恢复之前某次所有者/管理员执行 /model <model> 所替换掉的旧已配置默认值。
• 如果代理处于空闲状态，模型更改会立即应用于下一次运行。如果已有运行正在进行，则切换会排队到下一个干净的重试点（如果工具活动或回复输出已经开始，也可能会延后到更晚的重试点）。
• 用户选择的 /model 引用对该会话是严格的：如果它变得不可访问，回复会明确失败，而不会通过 agents.defaults.model.fallbacks 静默回退。已配置的默认值和 cron 任务的主模型仍会使用回退链。
• /model status 是详细视图：显示每个提供商的身份验证候选项，以及（在已配置时）提供商端点的 baseUrl 和 api 模式。
• 模型引用通过在第一个 / 处分割来解析；格式为 provider/model。如果模型 ID 本身包含 /（OpenRouter 风格），请包含提供商前缀，例如 /model openrouter/moonshotai/kimi-k2。如果省略提供商，OpenClaw 会依次尝试：(1) 别名匹配；(2) 针对该完全匹配的未加前缀模型 ID，查找唯一的已配置提供商匹配项；(3) 使用已配置的默认提供商（已弃用的回退方式）——如果该提供商不再提供已配置的默认模型，则改用第一个已配置的提供商/模型，以避免显示已过时的、已移除提供商的默认值。
• 模型引用会被规范化为小写；除此之外，提供商 ID 区分大小写，因此请使用插件公布的 ID。

​

命令行界面

openclaw models status
openclaw models list
openclaw models set <provider/model>
openclaw models set-image <provider/model>
openclaw models scan
openclaw models aliases list|add|remove
openclaw models fallbacks list|add|remove|clear
openclaw models image-fallbacks list|add|remove|clear
openclaw models auth list|add|login|paste-api-key|paste-token|setup-token|order

​

模型注册表（models.json）

​

托管目录更新

​

相关内容

• Agent 运行时 — OpenClaw、Codex 以及其他 agent 循环运行时
• 配置参考 — 模型配置键
• 图像生成 — 图像模型配置
• 模型故障转移 — 回退链
• 模型提供商 — 提供商路由和认证
• Models CLI 参考 — 完整命令和标志参考
• 音乐生成 — 音乐模型配置
• 视频生成 — 视频模型配置。