用腾讯云可观测平台监控 OpenClaw：Trace、Metrics 与 Token 成本分析

OpenClaw 这类 AI Agent 框架的复杂度不在入口接口，而在请求进入系统后的执行过程。

一个用户问题看起来只是一次普通调用，但 OpenClaw 内部可能会经历 Agent 编排、大语言模型推理、工具调用、上下文拼接、消息队列流转、Webhook 回调和会话状态更新。只看最终输入和输出，很难判断问题发生在哪一层。

可观测能力要解决的正是这个问题：把 OpenClaw 从“只知道结果”的黑盒，变成可以追踪、可以度量、可以告警的运行系统。

腾讯云可观测平台对 OpenClaw 的接入方案，核心由三部分组成：

• OpenTelemetry：统一可观测数据标准和上报协议。
• openclaw-tencent-plugin：采集 OpenClaw 请求链路 Trace。
• diagnostics-otel：采集 OpenClaw 运行指标 Metrics。

整体效果可以概括为一句话：Trace 看清每次请求怎么执行，Metrics 看清系统是否健康，Token 统计看清大模型调用成本花在哪里。

OpenClaw 为什么需要可观测

AI Agent 系统和普通后端接口不太一样。传统接口的执行路径通常比较固定，而 Agent 会根据上下文、模型输出和工具结果动态决定下一步动作。请求失败或结果异常时，问题可能出现在很多地方。

常见问题可以分成三类。

OpenClaw 的一次请求可能不是“一进一出”，而是一棵调用树。比如一次对话可能先进入系统，再触发 Agent 推理，随后调用 LLM（Large Language Model，大语言模型），如果模型决定使用工具，还会继续执行工具并把结果写回上下文。

flowchart TD
    A[用户请求] --> B[OpenClaw Gateway]
    B --> C[进入 OpenClaw 系统]
    C --> D[Agent 执行]
    D --> E[LLM 推理]
    E --> F{是否需要工具}
    F -- 是 --> G[执行工具调用]
    G --> H[工具结果写入上下文]
    H --> D
    F -- 否 --> I[生成最终响应]
    I --> J[返回用户]

如果没有链路追踪，排查时只能看到请求开始和请求结束；如果加上 Trace，每个环节都会变成一个 Span 节点，耗时、入参、出参、状态码和错误信息都可以关联起来。

整体架构：OpenTelemetry 加双插件

腾讯云可观测平台接入 OpenClaw 时，不是单纯依靠某一个插件，而是把 OpenTelemetry 作为统一底座，再用两个插件分别处理链路和指标。

flowchart LR
    User[用户请求] --> Gateway[OpenClaw Gateway]
    Gateway --> Runtime[OpenClaw Runtime]

    Runtime --> Agent[Agent 编排]
    Agent --> LLM[大语言模型]
    Agent --> Tool[外部工具 / 插件]
    Runtime --> Queue[消息队列]
    Runtime --> Session[会话管理]

    subgraph Observability[OpenClaw 可观测插件]
        TencentPlugin[openclaw-tencent-plugin<br/>采集 Trace]
        Diagnostics[diagnostics-otel<br/>采集 Metrics<br/>提供 OTel SDK]
    end

    Runtime -. Hook .-> TencentPlugin
    Runtime -. Runtime Metrics .-> Diagnostics
    TencentPlugin --> OTel[OpenTelemetry OTLP]
    Diagnostics --> OTel

    OTel --> TencentCloud[腾讯云可观测平台<br/>LLM 可观测 / APM]

这里有几个关键点。

OpenTelemetry 负责统一标准

OpenTelemetry 是通用可观测框架，常缩写为 OTel。它负责定义 Trace、Metrics、Logs 等数据格式，也定义了 OTLP（OpenTelemetry Protocol）这类上报协议。

对 LLM 场景来说，OpenTelemetry 还支持 GenAI（Generative AI，生成式 AI）相关语义约定，可以用统一字段描述模型名、服务商、输入 Token、输出 Token、工具调用等信息。这样做的好处是，数据不会只绑定在某个框架内部，后续接入其他可观测系统或做二次分析也更容易。

openclaw-tencent-plugin 负责 Trace

openclaw-tencent-plugin 是面向 OpenClaw 的链路追踪插件，主要作用是把一次请求拆成带父子关系的 Span 树。

典型链路可以拆成这些节点：

enter_openclaw_system
└── invoke_agent
    ├── chat
    │   ├── LLM 请求
    │   └── Token 统计
    └── execute_tool
        ├── 工具入参
        ├── 工具返回
        └── 工具耗时 / 错误

这样一来，一次请求中哪个 Agent 慢、哪个模型调用失败、哪个工具返回异常，都可以在 Trace 里定位。

diagnostics-otel 负责 Metrics

diagnostics-otel 是 OpenClaw 内置的指标采集插件，主要负责采集系统运行态 Metrics，例如：

• QPS（Queries Per Second，每秒请求数）
• 平均响应耗时
• 最大响应耗时
• 请求错误率
• 队列深度
• 消息等待时间
• 会话数量
• 卡死会话数量
• 上下文大小变化

Trace 更适合看单次请求，Metrics 更适合看整体趋势。两者结合后，既能知道“系统现在是否异常”，也能追到“某个异常请求具体卡在哪里”。

接入前需要准备什么

接入前需要确认三件事：

在腾讯云控制台里进入可观测平台，选择 LLM 可观测的应用接入入口，创建或选择业务系统后，选择 OpenClaw 接入方式，即可获得接入点和 Token。

Token 属于敏感凭据，不建议直接写进公开仓库。生产环境更推荐通过环境变量、密钥管理系统或容器 Secret 注入。

安装 openclaw-tencent-plugin

进入 OpenClaw 的 extensions 目录，安装腾讯云 Trace 插件。

cd ~/.openclaw/extensions
openclaw plugins install openclaw-tencent-plugin

如果 OpenClaw 运行在 Docker 容器里，需要进入容器内部执行，或者在构建镜像时把插件安装进去。

docker exec -it <容器名> sh

cd ~/.openclaw/extensions
openclaw plugins install openclaw-tencent-plugin

openclaw-tencent-plugin 依赖 diagnostics-otel 提供的全局 OpenTelemetry SDK，因此加载顺序很重要：diagnostics-otel 应该先加载，openclaw-tencent-plugin 再加载。

修改 openclaw.json

OpenClaw 的配置文件通常在以下位置：

配置目标有两个：

1. 启用 diagnostics-otel，让 OpenClaw 初始化 OpenTelemetry SDK 并采集 Metrics。
2. 启用 openclaw-tencent-plugin，让请求链路生成 Trace 并上报到腾讯云可观测平台。

可以按下面的结构理解配置项。不同版本的 OpenClaw 插件配置节点可能略有差异，关键字段是插件启用、OTLP 接入点、认证 Token、服务名和环境标识。

{
  "plugins": {
    "diagnostics-otel": {
      "enabled": true,
      "exporter": {
        "type": "otlp",
        "protocol": "http/protobuf",
        "endpoint": "https://<腾讯云可观测平台接入点>",
        "headers": {
          "Authorization": "Bearer <Token>"
        }
      },
      "metrics": {
        "enabled": true
      },
      "traces": {
        "enabled": true
      }
    },
    "openclaw-tencent-plugin": {
      "enabled": true,
      "serviceName": "my-openclaw",
      "serviceVersion": "1.0.0",
      "environment": "prod"
    }
  }
}

如果控制台给出的认证头不是 Authorization: Bearer <Token>，就以控制台显示的 Header 为准。例如有些 OTLP 接入点会要求使用指定 Header 名称传 Token。

配置字段可以这样理解：

如果希望避免 Token 写入配置文件，可以把敏感值放到环境变量中，再在配置中引用。

export OTEL_EXPORTER_OTLP_ENDPOINT="https://<腾讯云可观测平台接入点>"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <Token>"
export OTEL_SERVICE_NAME="my-openclaw"

容器部署时可以写进 docker-compose.yml 的 environment 段。

services:
  openclaw:
    image: <openclaw-image>
    environment:
      OTEL_EXPORTER_OTLP_ENDPOINT: "https://<腾讯云可观测平台接入点>"
      OTEL_EXPORTER_OTLP_HEADERS: "Authorization=Bearer <Token>"
      OTEL_SERVICE_NAME: "my-openclaw"
      OTEL_RESOURCE_ATTRIBUTES: "deployment.environment=prod,service.version=1.0.0"

重启 OpenClaw

配置修改后需要重启 OpenClaw。

直接安装方式：

openclaw gateway restart

Docker Compose 部署方式：

docker compose restart

重启后，插件才会按新配置加载，并开始采集 Trace 和 Metrics。

验证插件是否加载

进入 OpenClaw 运行环境，查看插件列表。

openclaw plugins list

Docker 环境可以这样执行：

docker exec -it <容器名> openclaw plugins list

重点检查两个插件：

diagnostics-otel          loaded
openclaw-tencent-plugin   loaded

如果 diagnostics-otel 没有加载，Trace 插件可能无法获取全局 OpenTelemetry SDK；如果 openclaw-tencent-plugin 没有加载，链路追踪不会生成完整的 OpenClaw Span 树。

验证数据是否上报

插件加载成功后，需要产生一些真实业务流量，例如发送消息、触发 Agent 执行、调用模型或调用工具。没有流量时，可观测平台不会立刻出现完整数据。

验证路径：

1. 打开腾讯云可观测平台控制台。
2. 进入 LLM 可观测。
3. 查看应用列表中是否出现配置的 serviceName，例如 my-openclaw。
4. 进入应用详情页，查看实例分析、调用链路和指标面板。
5. 找一条 Trace，确认能看到 OpenClaw 请求入口、Agent 执行、LLM 调用和工具调用节点。

可观测数据从采集到展示会有短暂延迟。刚接入后没有立刻看到应用或实例，可以等待几十秒再刷新。

Trace 能看到什么

Trace 的价值在于还原一次请求的完整执行路径。对 OpenClaw 来说，一条 Trace 不应该只是一个接口耗时，而应该能看到 Agent 内部每个动作。

sequenceDiagram
    participant User as 用户
    participant OpenClaw as OpenClaw
    participant Agent as Agent
    participant LLM as 大语言模型
    participant Tool as 工具服务
    participant Obs as 可观测平台

    User->>OpenClaw: 发送请求
    OpenClaw->>Obs: 创建 enter_openclaw_system Span
    OpenClaw->>Agent: 调用 Agent
    Agent->>Obs: 创建 invoke_agent Span
    Agent->>LLM: 发起模型推理
    LLM-->>Agent: 返回模型结果
    Agent->>Obs: 记录 chat Span 和 Token 信息
    Agent->>Tool: 根据模型结果调用工具
    Tool-->>Agent: 返回工具结果
    Agent->>Obs: 记录 execute_tool Span
    Agent-->>OpenClaw: 返回最终结果
    OpenClaw-->>User: 响应用户

一个设计良好的 Trace 至少应该包含这些信息。

例如一次请求总耗时 15 秒，单看接口日志只能知道“慢”。Trace 展开后，如果 chat Span 耗时 12 秒，说明主要瓶颈在模型推理；如果 execute_tool Span 重试多次，问题可能在工具服务；如果入口到 Agent 之间已经等待很久，就要关注队列堆积或网关层。

Token 成本如何拆解

大模型调用通常按 Token 计费。OpenClaw 的成本问题往往出现在多轮对话中，因为历史消息、工具返回和系统提示词都会进入上下文。如果不做裁剪，首轮对话可能只消耗几千 Token，几轮之后可能膨胀到几万 Token。

Token 统计需要拆开看，而不是只看总量。

Token 数据和 Trace 关联后，可以回答几个关键问题：

• 哪个 Agent 消耗 Token 最多。
• 哪个模型调用成本最高。
• 哪类业务场景上下文膨胀最快。
• 某次请求成本升高是因为输入变长，还是输出过长。
• 工具结果是否把大量无用内容塞进了上下文。

成本优化不能只换便宜模型。更常见的优化动作包括：

1. 删除无用历史消息
2. 对工具返回做摘要
3. 限制单次工具结果长度
4. 拆分长任务，避免所有信息塞进一次上下文
5. 为不同场景选择不同模型
6. 对稳定系统提示词使用缓存能力

Metrics 能监控哪些系统状态

Trace 面向单次请求，Metrics 面向整体运行状态。OpenClaw 稳定性监控至少要覆盖服务性能、队列状态、会话管理和资源趋势。

这些指标可以配置告警阈值。例如：

接入时容易踩的坑

生产环境还要考虑采样策略。全量 Trace 对排障最友好，但高流量场景会增加上报量和存储成本。可以根据业务重要性设置采样率，例如核心链路全量采集，普通请求按比例采样，错误请求始终保留。

一个更实用的排障流程

OpenClaw 出现异常时，可以按“指标发现问题，链路定位问题，Token 分析成本”的顺序处理。

flowchart TD
    A[收到告警或发现异常] --> B{异常类型}
    B -->|耗时升高| C[查看 P95/P99 和慢请求 Trace]
    B -->|错误率升高| D[查看错误 Span 和下游返回]
    B -->|成本升高| E[查看 Token 趋势和高消耗 Agent]
    B -->|无响应| F[查看队列深度和卡死会话]

    C --> G[定位慢节点：LLM / 工具 / 队列 / Agent]
    D --> H[定位错误来源：模型 / 工具 / 鉴权 / 网关]
    E --> I[优化上下文、提示词、模型选择]
    F --> J[处理堆积、超时、会话释放]

    G --> K[修复并观察指标恢复]
    H --> K
    I --> K
    J --> K

这个流程的关键是不要只盯日志。日志适合记录局部事件，但很难自然表达父子调用关系和跨组件耗时。Trace、Metrics 和 Token 统计放在一起，才能把 OpenClaw 的运行状态讲清楚。

小结

OpenClaw 的可观测建设应该围绕三个目标展开：

• 用 Trace 还原每次请求的执行路径，定位 Agent、模型和工具调用中的慢点与错误点。
• 用 Metrics 观察整体运行状态，提前发现队列堆积、会话卡死、错误率升高和响应变慢。
• 用 Token 统计拆解大模型调用成本，判断成本增长来自上下文、输出长度、缓存策略还是模型选择。

腾讯云可观测平台通过 OpenTelemetry、openclaw-tencent-plugin 和 diagnostics-otel 把这些数据统一接入同一套控制台。OpenClaw 接入后，排障不再只靠猜测，成本也不再只能事后核算，系统异常可以通过指标和告警提前暴露出来。