模型选择与故障转移

模型选择顺序

OpenClaw 按以下顺序选择模型：

1. 主模型（agents.defaults.model.primary）
2. 备用模型（agents.defaults.model.fallbacks，按顺序尝试）
3. Provider 内部认证轮换（同一 Provider 多个 API 密钥之间的切换，发生在切换到下一个备用模型之前）

基本配置

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

模型目录（models）

agents.defaults.models 同时承担两个作用：

• 模型别名：在聊天中使用 /model <别名> 切换
• 允许列表：设置后，只有列表中的模型才能在聊天中选择

如果设置了 models 但用户尝试使用不在列表中的模型，会收到"Model is not allowed"错误，而不是正常回复。

// 正确：定义允许的模型目录
{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": { alias: "Opus" },
        "anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
      },
    },
  },
}

在聊天中切换模型

/model              # 显示当前模型
/model list         # 列出所有可用模型
/model Sonnet       # 切换到别名为 Sonnet 的模型
/model status       # 详细认证状态（含备用、Provider 端点信息）

图像模型（vision fallback）

当主模型无法处理图片时，使用专用图像模型：

{
  agents: {
    defaults: {
      imageModel: {
        primary: "openrouter/anthropic/claude-sonnet-4-5",
      },
    },
  },
}

认证轮换与冷却

当某个认证配置（API 密钥或 token）出现问题时，OpenClaw 在同一 Provider 内切换到下一个认证配置：

{
  auth: {
    profiles: {
      "anthropic:key1": { provider: "anthropic", mode: "api_key" },
      "anthropic:key2": { provider: "anthropic", mode: "api_key" },
    },
    order: {
      anthropic: ["anthropic:key1", "anthropic:key2"],
    },
  },
}

查看认证状态：

openclaw models status
openclaw models status --json  # 查看 auth.unusableProfiles（冷却中的配置）

按 Agent 覆盖模型配置

不同 Agent 可以使用不同的模型：

{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-opus-4-6" },  // 大多数 Agent 用这个
    },
    list: [
      { id: "fast", model: { primary: "anthropic/claude-sonnet-4-5" } },  // 快速 Agent
      { id: "local", model: { primary: "ollama/llama3.3" } },  // 本地模型 Agent
    ],
  },
}

模型策略建议

• 主模型：选用最新一代最强模型（当前推荐 anthropic/claude-opus-4-6）
• 备用模型：低成本/低延迟场景使用更小的模型
• 工具型 Agent 或不可信输入：避免使用较旧/较弱的模型层

API 密钥多 Key 轮换

部分 Provider 支持多个 API Key，触发速率限制时自动轮换：

# 环境变量方式
export ANTHROPIC_API_KEYS="sk-ant-key1,sk-ant-key2,sk-ant-key3"
# 或
export ANTHROPIC_API_KEY_1="sk-ant-key1"
export ANTHROPIC_API_KEY_2="sk-ant-key2"

优先级顺序：

1. OPENCLAW_LIVE_<PROVIDER>_KEY（临时覆盖）
2. <PROVIDER>_API_KEYS
3. <PROVIDER>_API_KEY
4. <PROVIDER>_API_KEY_*

仅速率限制错误（429 等）触发轮换，其他错误直接失败。