OpenClaw 第十七篇：AI Agent observability 可观测性建设

—— 日志、监控、追踪、告警：让企业级 Agent 可看、可管、可排查

---

0. 本篇定位（写给谁看）

• 运维 / SRE / 平台管理员
• 想把 OpenClaw 做成稳定、可上线、可追责的企业平台的人
• 遇到过：任务莫名卡住、执行失败、权限异常、性能变慢却查不到原因的人

本篇目标：给 OpenClaw 装上 “天眼系统”，实现：

• 每条指令：谁发的、什么时候、跑了什么、结果如何
• 每个技能：耗时、成功率、报错率、资源占用
• 每个节点：在线状态、负载、并发、健康度
• 异常自动告警：邮件 / 企业微信 / 钉钉

---

1. 什么是 AI Agent 可观测性（Observability）

简单讲三件事：

1. Logs（日志）：发生了什么
2. Metrics（指标）：运行得好不好
3. Traces（追踪）：从指令到执行全链路怎么走的

OpenClaw 作为本地执行 + 模型决策 + 技能调度的 Agent，比普通后端服务更难排查，必须做可观测。

---

2. 整体可观测架构（极简版）

plaintext

用户指令 → API网关 → 日志采集 → 指标采集 → 分布式追踪 → 告警 → 大盘

对应组件：

• 审计日志（谁、做了什么、结果）
• 技能运行指标（成功率、耗时、失败率）
• 集群状态（Master/Worker 在线、负载）
• 全链路追踪（指令 → 意图解析 → 技能调度 → 执行 → 返回）
• 告警规则（失败、超时、节点离线）
• 可视化大盘（Grafana 或内置控制台）

---

3. 日志体系建设（企业最刚需）

3.1 四类必记日志

1. 访问日志
   • 用户、IP、指令、Token、时间
2. 审计日志（合规必备）
   • 操作人、操作内容、权限校验结果、是否拦截
3. 技能执行日志
   • 技能名、参数、开始 / 结束时间、成功 / 失败、错误信息
4. 系统日志
   • 集群、网关、模型调用、存储、异常崩溃

3.2 统一日志格式（JSON 结构化）

json

{
  "traceId": "oc-trace-xxxx",
  "timestamp": "2026-03-21T14:30:00Z",
  "level": "INFO",
  "type": "skill_exec",
  "userId": "zhangsan",
  "skill": "desk-file-archive",
  "success": true,
  "costMs": 1240,
  "message": "执行完成"
}

3.3 日志存储与切分

• 本地滚动：按天 / 按大小切分
• 企业版：输出到 ELK / Loki / 内网日志系统
• 保留策略：普通 90 天，审计日志 180 天

---

4. 监控指标（Metrics）建设

4.1 网关层指标

• QPS、请求总量、响应时间
• 鉴权成功 / 失败次数
• 4xx/5xx 错误率

4.2 技能层核心指标（最关键）

• 技能调用次数
• 成功率 / 失败率
• 平均执行耗时 P50/P95
• 文件操作次数、读写大小
• 模型调用次数、耗时、失败率

4.3 集群层指标

• Master 在线状态
• Worker 在线 / 离线数
• 任务排队数、并发数
• CPU / 内存 / 磁盘占用

4.4 企业常用监控面板（可直接做 Grafana）

• 今日指令总数
• 技能成功率 TOP10 / 失败率 TOP10
• 最活跃用户 TOP10
• 集群健康状态
• 异常告警实时显示

---

5. 全链路追踪 Tracing（Agent 灵魂）

OpenClaw 一条指令会经过：

plaintext

指令 → 意图解析 → 权限校验 → 技能调度 → 执行 → 结果返回

我们给每一步加 traceId，实现：

• 一次指令，全流程串起来
• 哪一步卡、哪一步报错、耗时多少一目了然

示例追踪结构：

plaintext

traceId: oc-123456
├── 0ms   接收指令
├── 120ms 意图解析完成
├── 180ms 权限校验通过
├── 220ms 调度技能：file-manager
├── 240~1300ms 执行文件操作
└── 1340ms 返回结果

作用：

• 快速定位：是模型慢、权限拦了、还是技能卡了
• 性能优化依据

---

6. 告警体系（自动发现问题）

6.1 必开告警规则

1. 技能执行失败率 > 5%
2. 指令超时 > 10s
3. Worker 节点离线
4. 鉴权失败次数突增（疑似攻击）
5. 磁盘使用率 > 85%
6. 越权操作被拦截（重点审计）

6.2 告警渠道

• 企业微信 / 钉钉机器人
• 邮件
• 短信（可选）

6.3 告警示例文案

plaintext

【OpenClaw 告警】
类型：技能执行失败
技能：desk-file-archive
用户：zhangsan
时间：2026-03-21 14:31
错误：目标路径无写入权限
traceId：oc-xxx

---

7. 企业级落地：3 套最简方案

方案 A：轻量版（单机 / 小团队）

• 内置文件日志
• 内置命令查看：

  plaintext

  openclaw log list
  openclaw log skill <name>
  openclaw monitor
  

• 告警：邮件

方案 B：标准企业版（推荐）

• 日志 → Loki / ELK
• 指标 → Prometheus
• 大盘 → Grafana
• 告警 → Alertmanager + 企业微信

方案 C：高级平台版（多集群 / 多租户）

• 分布式追踪：Jaeger
• 统一日志平台
• 审计日志单独存储
• 安全分析：异常行为检测

---

8. 可观测性带来的真实价值（给管理层看）

1. 可追责：谁在什么时间执行了什么，一目了然
2. 可合规：满足内控、审计、等保需求
3. 可稳定：故障提前发现，平均恢复时间 MTTR 大幅下降
4. 可优化：知道哪些技能慢、哪些没人用、哪些风险高
5. 可扩展：从单机 → 集群 → 多租户都能撑住

---

9. 本篇核心总结（3 句话）

1. 没有可观测性的 AI Agent = 黑盒，不能上企业生产
2. OpenClaw 可观测 = 日志 + 指标 + 追踪 + 告警
3. 目标：指令可追溯、技能可度量、集群可监控、异常可告警