OpenClaw OpenTelemetry 监控配置：全栈可观测性

2026-04-28 · 12 分钟安全运维

OpenTelemetry 是什么

OpenTelemetry（简称 OTel）是云原生计算基金会（CNCF）旗下的可观测性标准：

三大支柱：Tracing、Metrics、Logs
厂商中立：兼容 Jaeger、Datadog、New Relic 等
多语言：覆盖主流编程语言
开源：Apache 2.0

OpenClaw v2026.4.25 大幅扩展了 OpenTelemetry 覆盖。

覆盖范围

OpenClaw 的 OpenTelemetry 监控覆盖：

维度	监控内容
Model Calls	每次 LLM 请求的延迟、状态
Token Usage	精确的输入/输出 Token
Tool Loops	工具调用链路和耗时
Harness Runs	Agent 执行流程
Exec Processes	命令执行细节
Outbound Delivery	消息发送状态
Context Assembly	上下文组装过程
Memory Pressure	记忆系统状态

基本上覆盖了 OpenClaw 的所有关键流程。

启用 OpenTelemetry

基础配置

# config.yaml
observability:
  opentelemetry:
    enabled: true
    serviceName: "openclaw-prod"
    endpoint: "http://localhost:4317"
    protocol: "grpc"  # grpc | http

通过引导

openclaw onboard --enable-otel

引导会询问你的 OTel 后端并配置。

部署 OpenTelemetry Collector

本地开发

# otel-collector-config.yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

exporters:
  jaeger:
    endpoint: jaeger:14250
    tls:
      insecure: true
  prometheus:
    endpoint: 0.0.0.0:8889

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [jaeger]
    metrics:
      receivers: [otlp]
      exporters: [prometheus]

docker run -p 4317:4317 -p 8889:8889 \
  -v $(pwd)/otel-collector-config.yaml:/etc/otelcol/config.yaml \
  otel/opentelemetry-collector

生产部署

集成 Jaeger

启动 Jaeger

docker run -d --name jaeger \
  -p 16686:16686 \
  -p 14250:14250 \
  jaegertracing/all-in-one:latest

查看 Trace

访问 http://localhost:16686

可以看到：

每次 OpenClaw 请求的完整 Trace
各步骤的耗时
错误的精确位置

集成 Prometheus + Grafana

Prometheus 配置

# prometheus.yml
scrape_configs:
  - job_name: 'openclaw'
    static_configs:
      - targets: ['otel-collector:8889']

Grafana 仪表板

OpenClaw 提供官方 Grafana Dashboard：

Token 使用趋势
API 延迟分布
工具调用热力图
Agent 健康度
错误率

# 导入官方 Dashboard
openclaw observability dashboard --target grafana

集成 SaaS APM

Datadog

observability:
  opentelemetry:
    enabled: true
    endpoint: "https://trace.agent.datadoghq.com"
    headers:
      DD-API-KEY: "$DATADOG_API_KEY"

New Relic

observability:
  opentelemetry:
    endpoint: "https://otlp.nr-data.net:4317"
    headers:
      api-key: "$NEW_RELIC_LICENSE_KEY"

Honeycomb

observability:
  opentelemetry:
    endpoint: "https://api.honeycomb.io:443"
    headers:
      x-honeycomb-team: "$HONEYCOMB_API_KEY"

关键指标解读

Token 使用

openclaw_tokens_input_total{provider="anthropic",model="claude-opus-4-7"}
openclaw_tokens_output_total{provider="anthropic",model="claude-opus-4-7"}

监控 Token 消耗趋势和分布。

模型延迟

openclaw_model_latency_seconds{provider="anthropic",model="claude-opus-4-7"}

P50、P95、P99 延迟。

工具调用

openclaw_tool_calls_total{tool="exec",status="success"}
openclaw_tool_calls_duration_seconds{tool="web_search"}

工具调用频率和耗时。

Agent 健康

openclaw_agent_active{agent="coder"}
openclaw_agent_session_duration_seconds{agent="coder"}

Agent 活跃度和会话时长。

告警规则

Prometheus AlertManager

# alert-rules.yaml
groups:
  - name: openclaw
    rules:
      - alert: HighTokenUsage
        expr: rate(openclaw_tokens_input_total[5m]) > 1000
        annotations:
          summary: "Token 消耗速率过高"
      
      - alert: HighModelLatency
        expr: openclaw_model_latency_seconds_p99 > 30
        annotations:
          summary: "模型 P99 延迟超过 30 秒"
      
      - alert: ToolFailureRate
        expr: rate(openclaw_tool_calls_total{status="error"}[5m]) > 0.1
        annotations:
          summary: "工具调用失败率过高"
      
      - alert: MemoryPressure
        expr: openclaw_memory_pressure > 0.8
        annotations:
          summary: "记忆系统压力过大"

性能分析

找出慢请求

通过 Trace 分析：

# Jaeger 查询
service:openclaw operation:model_call duration:>10s

找出延迟超过 10 秒的请求，分析原因。

Token 优化

通过 Metrics：

top 10 sessions by token usage

找出 Token 消耗大户，针对性优化。

工具瓶颈

top 5 slowest tools

识别需要优化的工具。

实际案例

案例 1：成本暴增排查

问题：本月 API 费用突然暴增 3 倍

排查：

查看 Token 使用 Dashboard
发现某个 Cron 任务消耗激增
Trace 分析发现重试逻辑 Bug
修复后费用恢复

案例 2：性能下降

问题：用户反馈响应变慢

排查：

查看 P99 延迟 → 上升
Trace 分析 → 工具调用慢
具体到 web_search 工具
切换 Provider 解决

案例 3：可靠性问题

问题：偶发的 Agent 卡住

排查：

查看错误率 → 缓慢上升
日志显示 OAuth token 过期
启用 Active Memory 自动续期
问题解决

进阶配置

采样

为了降低开销：

observability:
  opentelemetry:
    sampling:
      strategy: "probabilistic"
      rate: 0.1  # 采样 10%

自定义属性

observability:
  opentelemetry:
    attributes:
      environment: "production"
      team: "ai-platform"
      version: "${OPENCLAW_VERSION}"

Trace 上下文传播

observability:
  opentelemetry:
    propagation:
      - "tracecontext"  # W3C
      - "baggage"
      - "b3"  # Zipkin 兼容

隐私和合规

敏感数据处理

observability:
  opentelemetry:
    redact:
      enabled: true
      patterns:
        - "api_key=*"
        - "password=*"
        - "token=*"

避免敏感信息进入 Trace。

数据驻留

observability:
  opentelemetry:
    region: "cn-shanghai"  # 数据驻留中国

合规要求下选择就近区域。

故障排查

Trace 没有数据

openclaw doctor observability

检查：

Collector 是否运行
网络连接
配置正确性

指标缺失

# 检查导出
curl http://localhost:8889/metrics | grep openclaw

性能影响

监控 OpenTelemetry 自身的开销：

openclaw_otel_exporter_latency_seconds
openclaw_otel_dropped_spans_total

如果开销过大，调整采样率。

注意事项

OpenTelemetry 全栈覆盖需要 OpenClaw v2026.4.25 或更高
Collector 部署是最佳实践，不要直接发送到后端
采样率根据流量调整
敏感数据务必 redact
SaaS 后端注意成本（Datadog 等按使用量收费）
个人开发者用 Jaeger + Prometheus 免费组合
企业建议 Honeycomb 或 Datadog 商业方案
定期审查 Dashboard 和告警规则