Wiki AI

模型配置

2分钟阅读

概述

OpenClaw 通过 provider/model 格式的模型引用选择模型，支持主模型 + 回退链配置，以及 Session 内动态切换。模型引用不直接决定运行时（Agent Runtime），OpenAI 模型是例外（默认走 Codex harness）。

核心要点

模型选择优先级：

  1. agents.defaults.model.primary（主模型）
  2. agents.defaults.model.fallbacks（回退链，按顺序）
  3. Provider 内 auth profile 轮换（在进入下一个模型前）

选择来源与回退策略：

  • 配置默认：使用 agents.defaults.model.fallbacks
  • 用户 Session 覆盖（/model、picker）：严格模式，失败直接报错，不走回退链
  • Cron 任务 --model：使用配置回退链，除非显式提供 fallbacks: []
  • 自动回退覆盖：标记 modelOverrideSource: "auto"，可继续走回退链

模型白名单：设置 agents.defaults.models 后，它成为 /model 和 Session 覆盖的白名单。支持 provider/* 通配符条目。

特殊模型类型：

  • imageModel：主模型不支持图片时使用
  • pdfModel：pdf 工具使用
  • imageGenerationModel、musicGenerationModel、videoGenerationModel：各自的生成能力

模型引用解析：按第一个 / 分割，OpenRouter 风格需带 provider 前缀（如 openrouter/moonshotai/kimi-k2）

配置/使用

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["openai/gpt-5.4-mini"]
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "anthropic/claude-opus-4-6": { alias: "Opus" }
      }
    }
  }
}

添加模型到白名单（安全写法，不覆盖现有条目）：

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

Session 内切换：

/model                    # 显示选择器
/model openai/gpt-5.4     # 直接切换
/model status             # 查看当前状态

CLI 命令：

openclaw models list
openclaw models set <provider/model>
openclaw models fallbacks add <provider/model>

相关页面

关系图谱

反向链接