第 11 章：模型管理与故障切换 🤖

模型是 AI 的"大脑"。OpenClaw 让你可以同时拥有多个大脑，还能在一个坏了时自动换另一个。

---

11.1 为什么需要多个模型？

不同 AI 模型有不同的"性格"和特长：

模型	特长	适合场景
Claude Sonnet	全能均衡	日常对话、编码
Claude Opus	深度推理	复杂分析、长文档
GPT-5.x	编码 Agent	Codex 模式
Gemini 2.5 Pro	多模态理解	图片、视频分析
DeepSeek V3	性价比高	日常轻量任务
Qwen 系列	中文友好	中文场景
本地模型 (Ollama)	免费私密	测试、隐私敏感任务

想象一下：你有两个助手，一个（Sonnet）速度快、处理日常事务；另一个（Opus）深思熟虑、处理复杂问题。不同任务用不同的人，这就是多模型管理的价值。

---

11.2 配置多个模型

基础配置

在 ~/.openclaw/openclaw.json 中配置：

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["openai/gpt-5.4", "google/gemini-2.5-pro"],
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "anthropic/claude-opus-4-6": { alias: "Opus" },
        "openai/gpt-5.4": { alias: "GPT" },
        "google/gemini-2.5-pro": { alias: "Gemini" },
      },
    },
  },
}

模型引用格式

模型使用 provider/model 格式：

anthropic/claude-sonnet-4-6
openai/gpt-5.4
google/gemini-2.5-pro
ollama/qwen3:8b
openrouter/moonshotai/kimi-k2

通用规则： 模型 ID 以第一个 / 分割，前面是提供商，后面是模型名。

CLI 管理模型

openclaw models list                 # 列出所有可用模型
openclaw models status               # 查看当前使用的模型
openclaw models status --plain       # 只输出模型名
openclaw models set <provider/model> # 设置默认模型
openclaw models set-image <model>    # 设置图片分析模型

模型别名

给长模型名起个短名字：

openclaw models aliases add sonnet anthropic/claude-sonnet-4-6
openclaw models aliases add gpt openai/gpt-5.4

然后在聊天中就可以：

/model sonnet
/model gpt

---

11.3 在聊天中切换模型

无需重启，直接切换：

/model            # 打开模型选择器
/model list       # 列出可用模型
/model 3          # 选择列表中的第 3 个
/model sonnet     # 用别名切换
/model default    # 回到默认模型
/model status     # 查看当前模型

切换模型的效果

切换模型后：

• ✅ 当前会话上下文保留
• ✅ 下次回复就用新模型
• ❌ 当前正在进行的回复不受影响

模型的会话重载

如果你设置了 agents.defaults.models（允许列表），不在列表中的模型会被拒绝：

Model "xxx/yyy" is not allowed. Use /models to list providers.

解决方法：把模型加进允许列表，或者选列表里已有的模型。

---

11.4 模型故障切换

在线 AI 模型偶尔会出问题——API 限流、网络超时、服务暂不可用。OpenClaw 有自动故障切换机制。

故障切换流程

模型调用失败
     │
     ▼
  当前提供商有多个 API Key？
     ├── 是 → 换一个 Key 重试
     └── 否
          │
          ▼
    配置了备用模型？
     ├── 是 → 切换到下一个模型
     └── 否
          │
          ▼
    报告错误给用户

配置故障切换

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: [
          "openai/gpt-5.4",
          "google/gemini-2.5-pro",
          "ollama/qwen3:8b",     // 本地模型作为最后的保障
        ],
      },
    },
  },
}

用户看到的提示

切换时会自动通知你：

↪️ Model Fallback: openai/gpt-5.4 (selected anthropic/claude-sonnet-4-6; rate limit)

恢复时也会通知：

↪️ Model Fallback cleared: anthropic/claude-sonnet-4-6 (was openai/gpt-5.4)

手动选择不受故障切换影响

如果你用 /model 手动选择了一个模型，且它不可用，OpenClaw 会报错而不是自动切换：

选择：/model xxx/yyy
结果：不可用 → 报错

这是故意的——如果你明确选中了某个模型，说明你知道自己在做什么，不应该偷偷换别的。

---

11.5 模型开关机和冷却

冷却（Cooldown）机制

当一个 API Key 因限流或认证错误而失败，OpenClaw 会把它"冷静"一下：

失败次数	冷却时间
第 1 次	1 分钟
第 2 次	5 分钟
第 3 次	25 分钟
第 4+ 次	1 小时（上限）

计费禁止

如果 API Key 因为欠费等原因被禁用（通常返回 402 或类似错误），冷却会长得多：

• 首次 5 小时
• 翻倍，最多 24 小时
• 24 小时无失败后重置

查看认证状态

openclaw models status --check     # 检查认证状态
openclaw models status --probe     # 实际探测各模型可用性

---

11.6 本地模型配置（Ollama）

本地模型最大的好处：免费、私密、无限制。即使网络断了也能用。

第一步：安装 Ollama

# macOS
brew install ollama

# Linux
curl -fsSL https://ollama.com/install.sh | sh

第二步：下载模型

ollama pull qwen3:8b      # 中文友好的小模型
ollama pull llama3.1:8b   # 通用模型

第三步：配置 OpenClaw

{
  agents: {
    defaults: {
      model: {
        primary: "ollama/qwen3:8b",
        // 或者作为备用
        // primary: "anthropic/claude-sonnet-4-6",
        // fallbacks: ["ollama/qwen3:8b", "ollama/llama3.1:8b"]
      },
      models: {
        "ollama/qwen3:8b": { alias: "Qwen" },
        "ollama/llama3.1:8b": { alias: "Llama" },
      },
    },
  },
}

确认可用

openclaw models list --local
openclaw models status

使用场景

本地模型用作：

1. 主模型——完全离线使用（适合隐私敏感场景）
2. 备用模型——云端模型不可用时自动切到本地
3. 专用模型——轻量任务用本地，复杂任务用云端
4. 压缩模型——用本地小模型做会话压缩和记忆闪存，省 Token

---

11.7 模型用量跟踪与成本控制

限制可用模型

通过 agents.defaults.models 限制 Agent 能用的模型：

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "anthropic/claude-opus-4-6": { alias: "Opus" },
        // 不把最贵的模型加入列表，Agent 就用不了
      },
    },
  },
}

不同 Agent 不同预算

{
  agents: {
    list: [
      {
        id: "chat",
        model: "anthropic/claude-sonnet-4-6",  // 日常用，性价比高
      },
      {
        id: "deep-work",
        model: "anthropic/claude-opus-4-6",     // 深度工作用好模型
      },
      {
        id: "local-test",
        model: "ollama/qwen3:8b",               // 测试用免费的本地模型
      },
    ],
  },
}

分频道、分时段使用不同模型

通过多 Agent 绑定，可以在不同频道用不同模型：

• WhatsApp → 快模型（Sonnet，日常聊天）
• Telegram → 强模型（Opus，处理复杂请求）
• 深夜 → 本地模型（不费 API Key）

使用 OpenRouter 免费模型

如果你用 OpenRouter，可以扫描免费模型：

openclaw models scan                # 扫描 OpenRouter 免费模型
openclaw models scan --no-probe     # 仅看元数据
openclaw models scan --min-params 8 # 只看 8B 以上

---

11.8 实战：搭建"三层保险"模型架构

场景

你想确保 Agent 7×24 小时永远可用，同时控制成本。

配置

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",  // 首选：快而准
        fallbacks: [
          "openai/gpt-5.4",                        // 后备 1：另一个云端模型
          "ollama/qwen3:8b",                       // 后备 2：本地模型，永不宕机
        ],
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "openai/gpt-5.4": { alias: "GPT" },
        "ollama/qwen3:8b": { alias: "Qwen" },
        "ollama/llama3.1:8b": { alias: "Llama" },
      },
    },
  },
}

运行效果

场景	使用模型	原因
正常情况	Claude Sonnet	最佳性价比
Claude API 限流	GPT-5.4	自动切换
Claude + GPT 都不可用	Qwen 本地模型	永不宕机
网络断开	Qwen 本地模型	离线也能用
你说 /model opus	Opus	手动优先，不受故障切换

这样你的 Agent 就拥有了"三层保险"：

1. 首选 — 云端最优模型
2. 后备 — 另一个云端模型
3. 终极保障 — 本地模型，完全离线

---

当当老师 🐾 笔记： 模型是 Agent 的"大脑核心"。OpenClaw 的多模型策略就像一个精明的老板——日常杂事交给性价比高的员工，复杂项目交给资深专家，紧急情况再差也有 B 计划。配置好故障切换，你的 Agent 就像装了"永不宕机"的护身符。

---

上一章 ← 第 10 章：记忆系统 | 返回目录 →

---