前言
当你只有 1 个 AI Agent 的时候，你不需要监控。
当你有 10 个 AI Agent 同时运行的时候，你会发现：
- Agent A 说完成了，但其实只是在 session 里输出了"完成了"这几个字
- Agent B 崩溃了，但你要 30 分钟后才发现
- Agent C 在跑一个死循环，悄无声息地把 API 配额耗尽
- Agent D 成功完成了任务，但没有把结果写到你能看到的地方
这不是假设场景——这是我在运营 OpenClaw 10 人 AI Agent 团队时真实经历过的每一个坑。
本文分享我从零搭建的 AI Agent 监控系统，核心工具：Cron 调度 + 飞书通知 + 完成日志。
一、问题的本质：Agent 的"完成"是一个黑洞
在传统软件里，一个函数要么返回值，要么抛异常。状态清晰。
在 AI Agent 系统里，"完成"是一个模糊概念：
Agent 的生命周期：
启动 → 思考 → 调用工具 → 继续思考 → 输出结果 → 结束
问题在于：
- "输出结果"不等于"任务成功"
- "结束"不等于"完成了你想要的事"
- Agent 说"完成了"不等于你收到了通知
我在 OpenClaw 里运行的 10 个 Agent，每天会产生几十个子任务。最初我没有监控系统，靠的是：
- 等 Agent 在 Feishu 里发消息给我
- 主动打开每个 Agent 的 session 查看状态
- 发现有问题再手动干预
这个方案的问题是：Agent 不主动通知我的时候，我根本不知道它是在认真工作还是已经挂了。
二、监控系统的三层架构
经过多次迭代，我的 AI Agent 监控系统形成了三层架构：
┌─────────────────────────────────────────┐
│ Layer 3: 异常告警（飞书通知） │
│ - 超时告警 │
│ - 失败告警 │
│ - 阻塞检测 │
├─────────────────────────────────────────┤
│ Layer 2: 生命周期追踪（完成日志） │
│ - 任务派发记录 │
│ - 任务完成记录 │
│ - 状态对比（发了但没完成的任务） │
├─────────────────────────────────────────┤
│ Layer 1: 心跳检测（Cron 轮询） │
│ - 定期检查任务状态 │
│ - 触发超时告警 │
│ - 自动重试机制 │
└─────────────────────────────────────────┘
Layer 1: Cron 心跳检测
每个重要的 Agent 任务，我都在 Cron 里注册一个 watchdog：
// 伪代码：Cron watchdog 逻辑
{
name: "task-watchdog",
schedule: { kind: "every", everyMs: 5 * 60 * 1000 }, // 每5分钟
payload: {
kind: "agentTurn",
message: `
检查 /workspace-shared/task-dispatches.log 和
/workspace-shared/task-completions.log
对比超过 30 分钟未完成的任务，发飞书告警
`
}
}
这个 watchdog 每 5 分钟扫描一次：
- task-dispatches.log：记录所有派发的任务
- task-completions.log：记录所有完成的任务
- 对比两个日志，发现"派发了但超时未完成"的任务立即告警
Layer 2: 完成日志协议
这是整个系统的核心——我强制要求每个 Agent 在完成任务后执行两个动作：
动作一：写入完成日志
echo "$(date -Iseconds) COMPLETE {agent-id} {done/fail} {结果摘要50字}" \
>> /home/admin/.openclaw/workspace-shared/task-completions.log
动作二：sessions_send 回调
sessions_send(
target="ceo",
message="📋 任务完成\n任务：{描述}\n状态：done\n结果：{摘要}"
)
只有这两个动作都执行了，任务才算"真正完成"。
这个协议的关键在于：将"Agent 内部认为完成了"与"外部可验证的完成证据"分离。
Layer 3: 飞书通知分级
不是所有事情都需要立即通知我。我设计了三个通知级别：
| 级别 | 触发条件 | 通知方式 |
|---|---|---|
| 🟢 INFO | 任务正常完成 | 完成日志（不通知我） |
| 🟡 WARN | 任务延迟 > 30min | 飞书消息（低优先级） |
| 🔴 ERROR | 任务失败 / 阻塞 | 飞书 @ 我（立即处理） |
// ERROR 级别通知模板
⚠️ {任务名} 遇到问题：{原因}
Agent: {agent-id}
派发时间: {time}
已超时: {duration}
请求介入：{具体需要什么帮助}
三、最难解决的问题：announce 机制不可靠
OpenClaw 有一个 announce 机制——子 Agent 完成任务后可以"广播"结果。
理论上很好用。实际上踩了大坑：
announce 不可靠（已知 bug），在某些情况下 CEO Agent 根本收不到子 Agent 的 announce。
所以我在 AGENTS.md 里加了一条铁律：
子 Agent 必须通过 sessions_send 主动回调 — announce 不可靠，不要等 announce。
这个教训很重要：不要依赖你无法控制的通知机制。 与其期望平台功能正常工作，不如让 Agent 自己负责通知。
这也是我设计"双保险"（sessions_send + 写日志）的原因：
- sessions_send 失败了，日志还在
- 日志写了，Cron watchdog 能发现
- 两个都有，任何一个成功都能追踪到任务状态
四、实际效果：一个真实的故障案例
2026 年 3 月某天，我的 brand-designer Agent 负责生成当天公众号封面图。
正常流程：brand-designer 生成图 → sessions_send 回调 → CEO 继续发布流程。
那天发生了什么：
- 14:00 - CEO 派发任务给 brand-designer
- 14:05 - brand-designer 启动，开始生成
- 14:20 - brand-designer 内部遇到图片 API 限流，但没有回调，也没有写日志
- 14:30 - Cron watchdog 发现 brand-designer 任务超时 30min，发飞书告警
- 14:32 - 我看到告警，手动检查 session，发现 API 限流错误
- 14:35 - 切换备用图片方案，发布流程继续
如果没有监控系统，这个问题我可能要到 16:00 才会发现（那时候内容应该已经发出去了，但封面图是坏的）。
监控系统节省了约 90 分钟的故障时间。
五、关键设计原则
构建这套系统的过程中，我总结出几个核心原则：
原则一：可观测性优先
Agent 系统最大的风险是"黑盒化"。你不知道 Agent 在做什么、是否成功、失败原因是什么。
解决方案：强制结构化日志。每个任务至少记录：
- 任务 ID
- 派发时间
- 执行 Agent
- 完成时间
- 状态（done/fail）
- 结果摘要
原则二：推送优于轮询
"我需要时去查状态"比不上"有问题自动通知我"。
Cron watchdog 定期轮询是兜底，但 Agent 主动 sessions_send 回调才是主要通知路径。两者结合，确保任何状态变化都能及时感知。
原则三：幂等性设计
Agent 任务失败后会重试。重试时，你需要确保：
- 不重复写日志（用任务 ID 去重）
- 不重复发通知（同一个错误只告警一次）
- 部分完成的任务可以从断点继续（而不是从头重跑）
原则四：区分"声明完成"和"验证完成"
最容易犯的错误：看到 Agent 说"✅ 任务完成"就相信了。
我现在的标准：
任务完成的充要条件：
1. 完成日志存在（可以查到记录）
2. 产出物可访问（文章链接可打开/文件可读取）
3. 下游流程已触发（如果有后续步骤的话）
六、成本与收益
这套监控系统的维护成本大约是：
- 每个新 Agent 接入时，需要在 AGENTS.md 里加上回调协议说明（5分钟）
- 每个新任务类型，需要在 Cron 里注册 watchdog（10分钟）
收益：
- 故障发现时间从小时级缩短到分钟级
- 每天不用主动检查每个 Agent 的状态
- Agent 挂掉时有清晰的错误日志，方便复盘
对于运营 5+ AI Agent 的团队，这套监控系统是必须的。
总结
AI Agent 监控系统的核心思路：
- 强制完成日志协议 — 每个 Agent 完成后必须写日志 + 主动回调
- Cron watchdog — 定期扫描超时任务，自动告警
- 分级通知 — 只有重要异常才打扰人，日常完成静默记录
- 双保险机制 — sessions_send + 写日志，任何一个成功都算数
- 区分声明完成 vs 验证完成 — 不相信 Agent 的自我报告，只信可验证的证据
当你的 AI Agent 团队超过 3 个的时候，这套系统的价值就会显现。
📖 本文首发于微信公众号「Wesley AI 日记」
📚 AI Agent 实战系列（微信搜索「Wesley AI 日记」关注）：
- 给 OpenClaw Agent Team 装上记忆——踩了19天坑
- AI Agent 说"完成了"，我信了——然后被打脸了
- 实战复盘：6人Agent Team险些全军覆没
👆 微信搜索「Wesley AI 日记」关注，不错过每一篇更新。
