OpenClaw Observability Plugin——为 AI Agent 网关提供 OpenTelemetry 全链路可观测性

一句话结论

henrikrexed/openclaw-observability-plugin（⭐42，Apache 2.0）是一个为 OpenClaw AI Agent 网关提供 OpenTelemetry 可观测性的插件，支持 traces、metrics、logs 全链路采集。当前版本 v0.6.0 提供模型调用 Span、工具调用耗时、会话追踪、Token 用量跟踪、安全检测提示和内置仪表盘。该插件支持两种可观测性路径：OpenClaw 内置的官方 OTel 插件（简易配置）和本仓库的自定义钩子插件（深度追踪）。

来源说明：基于 GitHub 仓库 README 综合整理。

项目概览

两种可观测性路径

推荐：两者配合使用可覆盖完整可观测性。

Approach 1：官方内建 OTel 支持

OpenClaw v2026.2+ 内置 OpenTelemetry 支持，仅需在 openclaw.json 中添加：

{
  "diagnostics": {
    "enabled": true,
    "otel": {
      "enabled": true,
      "endpoint": "http://localhost:4318",
      "serviceName": "openclaw-gateway",
      "traces": true,
      "metrics": true,
      "logs": true
    }
  }
}

捕获指标

Approach 2：自定义 Hooks 插件（深度追踪）

追踪链路

openclaw.request (根 Span)
├── openclaw.session (长生命周期会话 Span)
├── openclaw.agent.turn
│   ├── openclaw.dispatch.prepare
│   ├── chat {model} (模型调用 Span，GenAI 语义约定)
│   ├── execute_tool Read (工具 Span)
│   ├── execute_tool Write (工具 Span)
│   └── execute_tool Bash (工具 Span)
└── openclaw.message.sent

V3 核心能力

深度追踪范围总览

插件对以下六大类行为和数据进行全量深度追踪：

1. Agent 全生命周期

2. 模型调用链

3. 工具调用（核心深度追踪）

4. 安全检测数据

5. Metrics 指标

6. Cron 与子 Agent 调度

注册的 Hooks（18 个）

安装使用

npm 安装（推荐）

npm install @henrikrexed/openclaw-otel-observability

openclaw.json 配置：

{
  "plugins": {
    "load": {
      "paths": ["./node_modules/@henrikrexed/openclaw-otel-observability"]
    },
    "entries": {
      "otel-observability": {
        "enabled": true
      }
    }
  }
}

Kubernetes 安装

apiVersion: openclaw.io/v1alpha1
kind: OpenClawInstance
spec:
  plugins:
    - name: "@henrikrexed/openclaw-otel-observability"
      version: "^0.3.1"

支持矩阵

与近期 Agent 安全的关联

可观测性是 Agent 安全的重要基础：

插件内置的安全检测（prompt injection、dangerous command、sensitive file access detection）直接关联此前发布的 SkillCloak 和 Gaslight 等威胁。

参考

• GitHub：henrikrexed/openclaw-observability-plugin（⭐42，Apache 2.0）
• 文档：https://henrikrexed.github.io/openclaw-observability-plugin/