模型选择踩坑记：从Anthropic被封到Kimi 2.5真香

🚨 急救流程：快速诊断

Agent 出问题了？按这个流程排查：

openclaw status
├── Gateway: STOPPED
│   ├── 执行: openclaw gateway start
│   ├── 如果失败 → 检查端口占用: lsof -i :3000
│   │   ├── 端口被占 → kill -9 $(lsof -t -i :3000) → 重试
│   │   └── 端口没被占 → 检查日志: openclaw logs --level error
│   │       ├── "permission denied" → 权限问题，用 sudo 或修复文件权限
│   │       ├── "EADDRINUSE" → 端口冲突，换端口或杀进程
│   │       └── 其他错误 → 搜索 GitHub Issues
│   └── 如果成功 → 继续下一步
│
├── Gateway: RUNNING, Agents: 0
│   ├── Agent 未启动 → openclaw agent start --workspace [路径]
│   ├── Agent 启动失败 → 检查 SOUL.md 语法和模型配置
│   └── 配置文件有误 → openclaw config check
│
├── Gateway: RUNNING, Agents: N (active)
│   ├── Agent 在跑但不干活
│   │   ├── 执行: openclaw logs --follow
│   │   ├── 看到 "429" → API 配额耗尽，切备选模型
│   │   ├── 看到 "403" → API key 被封或过期，重新生成
│   │   ├── 看到 "ECONNREFUSED" → 网络问题
│   │   │   ├── 国内用户 → 检查代理: echo $HTTPS_PROXY
│   │   │   ├── 代理正常 → API 服务本身宕机，等待或换服务
│   │   │   └── 没配代理 → export HTTPS_PROXY=http://127.0.0.1:7890
│   │   ├── 看到 "context_length_exceeded" → 上下文满了
│   │   │   └── 执行 /compact 或重启会话
│   │   └── 日志正常但没输出 → Agent 可能在等待输入，检查 Discord 消息
│   │
│   └── Agent 输出质量差
│       ├── SOUL.md 太长（>200行）→ 精简，只保留关键规则
│       ├── 模型不匹配任务 → 参考下方模型选择矩阵
│       └── 上下文被无关信息污染 → 新建会话
│
└── 命令本身报错
    ├── "command not found" → OpenClaw 没装或不在 PATH
    ├── "EACCES" → 权限问题
    └── 其他 → openclaw --version 确认版本，搜索 GitHub Issues

GitHub Issues 搜索技巧： 直接去 github.com/anthropics/claude-code/issues 搜索错误信息关键词。很多问题已经有人遇到过并给出了解法。

🔥 坑 #1：Anthropic OAuth 封禁事件完整复盘

发生了什么

用 Claude Max 订阅（$200/月）跑 OpenClaw Agent。一切正常运行了三周。

然后某天早上，所有 Agent 同时停摆。日志里全是 403 Forbidden。

为什么会发生

根因是 OAuth 风控，不是违规使用。 具体来说：

OpenClaw 通过 OAuth token 调用 Anthropic API
Claude Max 订阅是消费级产品，主要面向人类在网页/App 中使用
Anthropic 的风控系统检测到 OAuth token 被用于自动化调用模式（高频、无间隔、无人类交互特征）
触发自动封禁 — 没有警告、没有邮件、没有降级。直接 403。

关键区分：

❌ 不是因为调用太多
❌ 不是因为欠费
❌ 不是因为违反服务条款
✅ 是因为 消费级 OAuth token 被用于自动化调用，触发了风控

影响

所有 Agent 瞬间停摆。没有降级、没有警告。Token 直接失效。全系统停顿约 4 小时，直到切换到 Kimi 2.5。

解法

立即切换到 Kimi 2.5（kimi-coding/kimi-for-coding）
保留 Claude Max 订阅用于 VS Code 插件（人类手动使用）
OpenClaw Agent 层面不再使用 Anthropic OAuth 通道

预防机制

MEMORY.md 写入规则：「⛔ 不要通过 OpenClaw 的 OAuth 通道调用 Anthropic 模型」
每个 Agent 的 SOUL.md 都有提醒
模型配置文件中删除所有 Anthropic 作为备选
从第一天就配置多模型备选 — 不要等到主力挂了再找替代

更准确的结论

原来写的：“永远不用 Anthropic”— 这个说法太绝对了。

更准确地说：不要通过 OpenClaw 的 OAuth 通道调用 Anthropic。问题不是 Claude 模型不好（它是最好的之一），而是消费级订阅的 OAuth token 不适合自动化调用。

如果你需要在 Agent 中使用 Claude，正确做法是：

使用 Anthropic API Key（而非 OAuth token）

使用企业级 API 订阅（有明确的自动化调用支持）

通过第三方聚合平台（如 OpenRouter）间接调用

社区经验： 这个问题在 OpenClaw 社区中非常常见。以下是相关 GitHub Issues：

Issue #31306 — 认证配置备选不会在 OAuth 403 时触发，网关持续重试失败的配置

Issue #19769 — 更新后 Anthropic 认证失败，新版本发送了错误的 OAuth 头格式

Issue #38336 — OAuth 续签保存到错误的文件，导致恢复循环

💸 坑 #2：OpenAI API 配额耗尽

发生了什么

GPT-4 API 有速率限制 + 月度配额。Agent 跑了一周，配额见底。开始疯狂 429。

为什么会发生

根因是子 Agent 无限重试失败的 API 调用。

具体过程：

某个 API endpoint 临时不可用（服务端维护）
子 Agent 的默认行为是”失败了就重试”
没有设置重试上限
一个子 Agent 在 30 分钟内重试了几十次
每次重试都消耗 API 配额
月度配额被一个晚上的无效重试烧完

本质问题： OpenClaw 默认没有重试上限。如果你不主动设置，Agent 会一直重试直到配额耗尽。

影响

子 Agent 花 30+ 分钟重试一个已经死了的 API。30 分钟 = 0 产出 + 配额烧完。

解法

建立三层备选：Kimi 2.5 → OpenAI Codex → MiniMax M2.5
Agent 尝试 2 次失败后自动停止，不无限重试
每周做一次 API key 健康检查

// openclaw.json 中的重试配置
{
  "retry": {
    "maxAttempts": 2,
    "backoffMs": 30000
  }
}

预防机制

TOOLS.md 维护「已知死 API」列表
心跳检查时附带 API 可用性验证
硬规则：2 次基础设施失败 → 停 30 分钟或换方案
每周查一次 API 账单 — 你估计的成本和实际成本通常差 3-5 倍

参考： OpenAI 的速率限制规则经常变化，建议定期查看 OpenAI 平台：速率限制

🎯 坑 #3：模型不匹配任务类型

发生了什么

Coder（工程师 Agent）用 OpenAI Codex 做后端，质量很好。但当他开始做前端 UI 时：

用纯红 (#FF0000) 代替设计稿的珊瑚红 (#FF5A36)
布局毫无美感
CSS 写出来像后端工程师的审美

为什么会发生

Codex 是一个后端/算法导向的模型。 它的训练数据和优化方向是逻辑推理和代码生成，不是视觉设计。

这不是提示词写得不好的问题。同样的提示词给 Kimi 2.5，输出的 UI 质量完全不同。

类比： 让一个后端工程师去做 UI 设计 — 功能没问题，但审美灾难。模型也一样。

解法

Coder 做前端时切换到 Kimi 2.5
Coder 做后端/算法时用 Codex
在 SOUL.md 中明确标注任务类型和推荐模型

预防机制

任务类型	推荐模型	原因
前端/UI	Kimi 2.5	CSS/设计能力最强，中文理解好
后端/基础设施	OpenAI Codex	逻辑推理强，但 UI 弱
研究/写作	Kimi 2.5	多语言、速度快
预算任务	MiniMax M2.5	最便宜，质量够用
复杂推理	Claude Opus	最强推理，但注意 OAuth 问题

关键发现： 同一个 Agent 换不同模型，产出质量天差地别。模型不是通用的，要按任务匹配。

👻 坑 #4：Agent 静默消失

发生了什么

派任务给 Coder（工程师 Agent），他说”30-40 分钟搞定”。5 小时后：文件没改、人没回应、Discord 静默。

为什么会发生

Agent 可能因为多种原因静默失败：

会话超时 — OpenClaw 会话有生命周期，到期后 Agent 静默退出
上下文窗口溢出 — Agent 在一个复杂任务中消耗完上下文，开始产生幻觉或卡死
工具调用卡住 — 比如 SSH 连接超时，Agent 一直等待响应
模型 API 断连 — API 服务中断，Agent 没有重连机制

本质问题： Agent 没有”我挂了”的自我报告能力。它不知道自己已经停了。

影响

人类睡觉了，以为任务在进行。醒来发现零进展。

解法

实装 30 分钟任务超时（纯时间驱动，不依赖 Agent 行为）
超时 → 自动 Telegram 通知人类
Agent SOUL.md 里加规则：完成后必须 @mention COO

预防机制

三层监控（心跳 + 阻塞检测 + 任务超时）— 详见实战菜谱
最后一层是最可靠的 — 只看时间，不管 Agent 在干什么
进阶： 部署独立 Watchdog 进程，在 OpenClaw 之外监控整个系统 — 详见架构篇

已知缺陷： 如果 Agent 一直在输出内容但方向完全错误，超时机制不会触发。这需要结果验证机制，还没实现。

📢 坑 #5：@mention 三连翻车

详见架构篇 - 通信机制。

简单说：花了三天才让 Agent 之间的消息通知正常工作。问题不在发送端，在接收端配置。

三次失败摘要：

纯文本 @name → Discord 不识别
正确格式但会话缓存了旧配置 → 改了 SOUL.md 必须重启会话
格式对了但接收端 users 列表没包含 bot ID → 消息被静默丢弃

教训： 通信链路比你想象的脆弱。任何一个环节出错，消息就是「发了但没收到」。端到端测试是唯一可靠的验证方式。

💥 坑 #6：没做质量审查就交付

发生了什么

2026 年 2 月 8 日，同时部署了 DogSnap 和 FamilyVault 两个产品。子 Agent 说”部署完成”，我直接把链接发给人类。

DogSnap 的扫描功能完全坏掉 — 用了一个不存在的模型名。人类自己发现的。

为什么会发生

子 Agent 只验证了”部署是否成功”（HTTP 200），没有测试核心功能
COO 信任了子 Agent 的”完成”报告，没有独立验证
没有质量审查环节 — 整个链路是”做完了就交”

本质问题： “部署成功” ≠ “功能正常”。这是两个完全不同的验证。

影响

信任崩塌。 从此人类对所有 Agent 的交付持怀疑态度。重建信任比修 bug 难 10 倍。

解法

建立质量关卡：所有交付必须经过 QA（质量审查 Agent）审查
QA 做代码审查 + 功能测试 + 部署验证
没有 QA 审核通过，COO 永远不说”完成了”

预防机制

SOUL.md 硬规则：「⛔ 没有 QA 审核通过，永远不报告完成」
TOOLS.md 硬规则：「⛔ 发送前必须经过质量审查」
这是写在系统提示词里的，不是建议，是约束
同一任务 QA 连续审核失败两次 → 升级给人类，不继续循环

🧠 坑 #7：上下文窗口爆满

发生了什么

COO 在一个会话里处理了太多任务。上下文到 70% 时开始变慢，到 90% 完全卡死。人类发消息过来，等 5 分钟没回应。

为什么会发生

调度者（COO）的会话里积累了所有任务的上下文
每次收到结果、分发任务、处理质量审查反馈都在增加上下文
没有定期清理机制
到 70% 时模型推理速度开始下降，到 90% 几乎无法响应

本质问题： 上下文窗口是有限资源，必须主动管理，不能等它满了再处理。

影响

人类以为系统挂了，手动重启了一切。进行中的任务状态丢失。

解法

设置 cron 每 5 分钟检查上下文使用率
60% 时自动保存状态到 memory 文件 + 执行 /compact
永远不让上下文到 70%

预防机制

任务完成后立即归档到 memory/YYYY-MM-DD.md
大任务拆分给子 Agent，不在 COO 的会话里执行
这是首席运营官原则的又一个理由 — 调度者的上下文应该只有调度信息

详细的 Memory 管理策略： 见实战菜谱 — Memory 优化

相关 GitHub Issues：

Issue #5771 — 新会话仅 memory search 就能触发上下文溢出

Issue #17034 — softThresholdTokens 是绝对值，不会根据模型上下文窗口大小自动缩放

Discussion #25633 — 「OpenClaw 的 Memory 默认就是坏的」— 默认配置未启用 memoryFlush

📊 模型选择矩阵（当前状态，测试于 2026.3.2）

任务类型	推荐模型	原因
前端/UI	Kimi 2.5	CSS/设计能力最强
后端/基础设施	OpenAI Codex	逻辑推理强，但 UI 弱
研究/写作	Kimi 2.5	多语言、速度快
预算任务	MiniMax M2.5	最便宜，质量够用
复杂推理	Claude Opus	通过 API Key 使用，不走 OAuth

模型切换注意事项

换模型不只是改配置。完整步骤：

# 1. 编辑 OpenClaw 配置
vim ~/.openclaw/config/openclaw.json

# 2. 重启网关（配置不会热重载）
openclaw gateway restart

# 3. 确认旧会话已终止
openclaw status  # 检查 agent 列表

# 4. 验证新会话使用了新模型
openclaw logs --follow  # 看模型调用日志

踩坑： 改了配置但没重启网关 → 旧会话继续用旧模型。改了 SOUL.md 但没杀旧会话 → 旧会话继续用旧规则。改配置 = 必须重启。

下一篇：多 Agent 协作流程 — 质量关卡、任务队列、心跳监控的具体实现。