OpenClaw 遥测与可观测性指南

凌晨4点17分，我和那个 bug 对视了整整一个时辰。直到我打开了遥测面板，才发现它在第 342 次工具调用时偷偷溜走了。从那以后，我再也不怕黑盒了。

为什么需要可观测性？

AI Agent 就像一只薛定谔的猫——在你打开盒子之前，你永远不知道它在想什么。OpenClaw 的遥测系统就是那个打开盒子的钥匙，让每一次推理、每一个工具调用、每一帧状态都变得可见。

遥测架构

核心组件

Traces - 完整的执行路径追踪
Metrics - 性能指标收集
Logs - 结构化日志输出
Spans - 细粒度的操作片段

启用遥测

// config.json
{
  "telemetry": {
    "enabled": true,
    "exporter": "otlp",
    "endpoint": "http://localhost:4317",
    "sampling": {
      "type": "probabilistic",
      "probability": 0.1
    }
  }
}

集成 OpenTelemetry

# 启动 OpenTelemetry Collector
docker run -d --name otel-collector \
  -p 4317:4317 \
  -p 4318:4318 \
  otel/opentelemetry-collector-contrib:latest

关键指标监控

// 监控的指标
const metrics = {
  // 工具调用延迟
  tool_call_duration: "histogram",
  // Token 使用量
  token_usage: "counter",
  // 错误率
  error_rate: "gauge",
  // 队列深度
  queue_depth: "gauge"
};

可视化面板

推荐使用 Grafana + Prometheus 组合：

# docker-compose.yml
version: "3.8"
services:
  prometheus:
    image: prom/prometheus
    ports:
      - "9090:9090"

  grafana:
    image: grafana/grafana
    ports:
      - "3000:3000"

分布式追踪

当 agent 调用多个外部服务时，分布式追踪能帮你看清完整的调用链：

// 在工具调用中传播 trace context
const result = await tool.execute({
  ...params,
  traceContext: context.traceContext
});

最佳实践

采样策略 - 生产环境使用 1-10% 采样率
敏感数据 - 避免在 trace 中记录敏感信息
告警设置 - 配置错误率和延迟告警
存储优化 - 定期清理历史数据