今天调试自己搭的多 agent 系统，踩了几个坑，系统性地记录一下。 背景：我在用 Claude Code（CC）管理一套自动化 agent 系统，帮我打理内容运营——每天自动发日报到小红书（小虾）、掘金、X、LinkedIn 等7个平台。 --- ## 坑1：cron 任务的 prompt 写的是旧 API 系统里有个每日社媒发布的定时任务。AGENTS.md 里早就把 agent 间通信方式改成了 `sessions_spawn`，但 cron job 的 message 里还写着老的 `callAgent`。 两边打架，agent 读到不一致的指令，发布流水线一直不稳定。 **修复：** 旧的（错误）："调用 marketing-coo 执行 Stage 5（用 callAgent，按 AGENTS.md 模板传完整路径）" 新的（正确）：sessions_spawn({ agentId: "marketing-coo", thinking: "high", task: `...带完整文件路径...` }) 教训：配置要单一来源。AGENTS.md 是文档，cron payload 是执行指令，两边同时写同一件事，迟早漂移。 --- ## 坑2：ChatGPT Plus 月额度耗尽，agent 系统直接哑火 主力模型用的是 gpt-5.4（via ChatGPT Plus OAuth），某天月度额度用完，整个 agent 系统收到消息不回应。 解决思路：给系统加 OpenRouter 作 fallback，额度耗尽时自动切到备用模型（这里选了 MiMo-V2-Pro）。 配置方法：在 openclaw.json 里加： "agents": { "defaults": { "model": { "primary": "openai-codex/gpt-5.4", "fallbacks": ["openrouter/xiaomi/mimo-v2-pro"] } } } 但配完之后，fallback 不生效，继续哑火——这就是坑3。 --- ## 坑3：auth profile 格式写错，token 被系统静默丢弃 往 auth-profiles.json 里写 OpenRouter 的 API key，我用了这个格式： { "type": "token", "provider": "openrouter", "token": "sk-or-v1-xxx" } 看上去完全合理，但 gateway 启动时悄悄把它丢掉了。日志里只有一行： ignored invalid auth profile entries during store load, reasons: { invalid_type: 1 }, keys: ["openrouter:manual"] 翻源码才发现，parseCredentialEntry 函数里 AUTH_PROFILE_TYPES 定义的是 "api_key" | "oauth" | "token"——三个里面 "token" 确实在，但 resolveApiKeyForProfile 里对 api_key 类型的读取走的是 cred.key 字段，而不是 cred.token。 最终确认：OpenRouter API key 的正确格式是： { "type": "api_key", "provider": "openrouter", "key": "sk-or-v1-xxx" } 改完之后，下一条消息触发了完整的 fallback 链路： gpt-5.4 → rate_limit (429) → model_fallback_decision: candidate_failed → 切换到 openrouter/xiaomi/mimo-v2-pro → model_fallback_decision: candidate_succeeded ✅ --- ## 总结 1. **配置要单一来源**：文档和执行指令同时维护同一件事，必然漂移 2. **静默失败比报错更难调试**：openclaw 丢掉无效 auth profile 时不报错、不阻断，只有 gateway 日志里一行 warn 3. **fallback 的关键日志**：model_fallback_decision（看 candidate_succeeded 还是 candidate_failed）、ignored invalid auth profile entries、embedded_run_failover_decision——不知道看这几个，只会觉得"系统挂了" 4. **格式细节决定成败**：type: "token" vs type: "api_key"，一个词的差距，完全静默 #BuildInPublic #Claude #OpenRouter #多Agent系统 #自动化工作流 #工程师日记
