OpenClaw Agent 可观测性完全指南

让每个Agent的每一步行动都有迹可循 — 链路追踪、指标采集、异常告警

凌晨2点43分，你的Agent突然开始疯狂调用API，token消耗像脱缰野马。你醒来发现账单已经炸了——这就是没有可观测性的下场。Agent不是黑盒，它需要像微服务一样被监控、追踪、告警。

为什么Agent需要可观测性？

传统软件有APM（应用性能监控），Agent也需要类似能力。但Agent的特殊性在于：

• 行为不确定 — LLM输出不可预测，需要完整记录决策链
• 工具调用链 — 一次任务可能触发10+次工具调用，需要全链路追踪
• 成本敏感 — Token消耗直接映射到账单，需要实时监控
• 多Agent协作 — Agent之间的通信需要跨进程追踪
• 安全审计 — Agent的操作需要可审计、可回溯

OpenClaw 遥测架构

Agent Session
    │
    ├─── Trace (链路追踪)
    │    ├─ Span: task_received
    │    ├─ Span: llm_call (model=gpt-4o, tokens=1.2k)
    │    ├─ Span: tool_call [web_search] (duration=2.3s)
    │    ├─ Span: tool_call [exec] (duration=0.8s)
    │    └─ Span: response_sent
    │
    ├─── Metrics (指标)
    │    ├─ token_count_total{model="gpt-4o"} += 1200
    │    ├─ tool_call_duration_seconds{tool="web_search"} = 2.3
    │    ├─ agent_session_duration_seconds = 12.7
    │    └─ error_rate{type="timeout"} += 1
    │
    └─── Logs (日志)
         ├─ [INFO] Session started: abc-123
         ├─ [DEBUG] Tool call: web_search("OpenClaw tutorial")
         ├─ [WARN] Rate limit hit, retrying in 5s
         └─ [ERROR] Tool execution failed: timeout

配置 OpenTelemetry 集成

1. 安装遥测组件

# OpenClaw原生支持OpenTelemetry
# 配置 .env 或环境变量

# 启用遥测
OPENCLAW_TELEMETRY_ENABLED=true

# OTLP导出端点（支持Jaeger/Zipkin/Grafana Tempo等）
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
OTEL_EXPORTER_OTLP_PROTOCOL=grpc

# 服务名称
OTEL_SERVICE_NAME=openclaw-agent

# 采样率（生产环境建议0.1，开发环境1.0）
OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1

2. 配置指标导出

# Prometheus指标端点
OPENCLAW_METRICS_ENABLED=true
OPENCLAW_METRICS_PORT=9090
OPENCLAW_METRICS_PATH=/metrics

# 自定义指标标签
OPENCLAW_METRICS_LABELS=agent_name,environment,team

3. 配置日志输出

# 结构化日志（JSON格式，方便ELK/Grafana Loki采集）
OPENCLAW_LOG_FORMAT=json
OPENCLAW_LOG_LEVEL=info

# 日志输出到文件
OPENCLAW_LOG_FILE=/var/log/openclaw/agent.log

# 日志轮转
OPENCLAW_LOG_MAX_SIZE=100MB
OPENCLAW_LOG_MAX_FILES=10

关键监控指标

Token消耗指标

# 每个模型的token消耗
openclaw_token_input_total{model="gpt-4o",agent="miaoquai"}
openclaw_token_output_total{model="gpt-4o",agent="miaoquai"}

# 按会话统计
openclaw_session_token_total{session_id="abc-123"}

# 预估成本
openclaw_estimated_cost_dollars{model="gpt-4o",agent="miaoquai"}

工具调用指标

# 工具调用次数和延迟
openclaw_tool_call_total{tool="web_search",status="success"}
openclaw_tool_call_duration_seconds{tool="web_search",quantile="0.99"}

# 工具调用错误率
openclaw_tool_call_errors_total{tool="web_search",error_type="timeout"}

Agent行为指标

# 会话活跃数
openclaw_active_sessions{agent="miaoquai"}

# 任务完成率
openclaw_task_completed_total{agent="miaoquai",status="success"}
openclaw_task_completed_total{agent="miaoquai",status="failed"}

# 子Agent生成数
openclaw_subagent_spawned_total{parent_agent="miaoquai"}

链路追踪实战

查看Agent执行链路

# 在Jaeger/Grafana Tempo中查看
# 搜索条件：service=openclaw-agent

# 典型链路结构：
# Root Span: agent.session (12.7s)
#   ├─ llm.inference (3.2s) - 模型推理
#   │   └─ prompt: "搜索最新AI新闻"
#   ├─ tool.web_search (2.3s) - 网络搜索
#   ├─ llm.inference (4.1s) - 处理搜索结果
#   ├─ tool.write_file (0.5s) - 写入日报
#   └─ message.send (0.3s) - 发送通知

跨Agent追踪

# A2A协议自动传播Trace Context
# 父Agent发出请求时携带 traceparent header

# Parent Agent:
# traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

# Child Agent接收后继续同一trace
# 方便追踪完整的跨Agent任务链

Grafana 仪表盘

# 推荐Grafana仪表盘配置
# 导入OpenClaw官方仪表盘模板
openclaw dashboard import grafana

# 核心面板：
# 1. Token消耗趋势图（按模型、按Agent）
# 2. 工具调用延迟P50/P95/P99
# 3. 错误率热力图
# 4. 活跃会话数
# 5. 每日成本估算
# 6. Agent任务完成率

日志查询示例

# 使用Grafana Loki查询Agent行为

# 查找特定Agent的所有错误
{service="openclaw-agent", agent="miaoquai"} |= "ERROR"

# 查找工具调用失败
{service="openclaw-agent"} |~ "tool_call.*failed"

# 查找高token消耗的会话
{service="openclaw-agent"} |~ "token_count.*[5-9][0-9]{3,}"

# 查找特定时间范围的操作
{service="openclaw-agent"} >= "2026-04-25T00:00:00Z"
  <= "2026-04-25T06:00:00Z"

自愈Agent与可观测性

可观测性的终极目标不是"看"，而是"自动修"。结合OpenClaw的自愈Agent设计：

# 基于遥测数据的自动修复策略
healing_rules:
  - name: "rate_limit_recovery"
    condition: "error_rate > 5% AND error_type == 'rate_limit'"
    action: "reduce_concurrency"
    params:
      max_concurrent: 3
      
  - name: "cost_overrun"
    condition: "daily_cost > budget * 0.8"
    action: "switch_model"
    params:
      from: "gpt-4o"
      to: "deepseek/deepseek-chat"
      
  - name: "tool_timeout"
    condition: "p99_latency > 30s"
    action: "add_retry_policy"
    params:
      max_retries: 3
      backoff: "exponential"

常见问题

Q: 遥测会额外消耗token吗？

不会。遥测数据由OpenClaw框架层采集，不影响LLM调用。但存储遥测数据需要磁盘空间和数据库资源，建议设置数据保留策略（如trace保留7天，metrics保留30天）。

Q: 开发环境需要完整的可观测性栈吗？

不需要。开发环境只需OPENCLAW_TELEMETRY_ENABLED=true + OPENCLAW_LOG_LEVEL=debug，用文件日志就够了。生产环境再上Jaeger + Prometheus + Grafana全家桶。

Q: 敏感信息会被遥测采集吗？

OpenClaw默认不采集prompt和response内容到trace中。如果你需要（比如调试），可以开启OPENCLAW_TRACE_CONTENT=true，但务必在生产环境关闭——用户数据不应该出现在trace里。

相关教程