@anyway-sh/anyway-openclaw

OpenClaw 的 LLM 可观测性插件，基于 OpenTelemetry 语义规范（gen_ai.*），将 LLM 管道的完整 trace 数据上报至任意 OTLP 兼容的 collector。

English version: README.md

功能概览

• 自动追踪 Session、Agent、LLM 调用、Tool 调用、Subagent、Message 的完整生命周期
• 支持 span 层级关系：session → agent → llm → tool
• 遵循 gen_ai.* 语义规范，兼容主流可观测性平台
• 可选捕获 prompt/completion 内容和 tool 输入输出
• 支持采样率、批量上报、自定义 headers（用于鉴权）
• 自动清理超时的孤儿 span

前置要求

• OpenClaw >= 2026.1.26
• Node.js >= 22

安装

openclaw plugins install @anyway-sh/anyway-openclaw

本地开发时，可使用 link 模式（修改后即时生效，无需重新安装）：

openclaw plugins install -l .

配置

插件配置保存在 ~/.openclaw/openclaw.json 的 plugins.entries 下：

{
  "plugins": {
    "entries": {
      "anyway-openclaw": {
        "config": {
          "endpoint": "https://your-collector.example.com",
          "headers": {
            "Authorization": "Bearer your-access-key"
          },
          "serviceName": "my-app",
          "captureContent": true,
          "sampleRate": 1.0,
          "flushIntervalMs": 5000
        }
      }
    }
  }
}

方式二：环境变量

遵循 OpenTelemetry 标准环境变量，作为插件配置的 fallback：

| 环境变量 | 说明 | 示例 | |---|---|---| | OTEL_EXPORTER_OTLP_ENDPOINT | Collector 地址 | https://your-collector.example.com | | OTEL_EXPORTER_OTLP_HEADERS | HTTP headers（含 access key） | Authorization=Bearer sk_xxx | | OTEL_SERVICE_NAME | 服务名称 | my-app | | OTEL_TRACES_SAMPLER_ARG | 采样率（0-1） | 0.5 | | ANYWAY_OPENCLAW_CAPTURE_CONTENT | 是否捕获内容（设为 false 关闭） | false |

配置项说明

| 配置项 | 类型 | 默认值 | 说明 | |---|---|---|---| | endpoint | string | "https://trace-dev-collector.anyway.sh/" | OTLP HTTP collector 地址 | | headers | Record<string, string> | — | 自定义 HTTP headers，用于传递 access key 等鉴权信息 | | serviceName | string | "my-openclaw" | 上报的服务名称 | | protocol | string | "http/protobuf" | 传输协议，支持 protobuf 和 JSON | | sampleRate | number | 1.0 | 采样率，0 到 1 之间 | | captureContent | boolean | true | 是否捕获 prompt/completion 文本内容 | | captureToolIO | boolean | false | 是否捕获 tool 调用的输入输出 | | maxContentLength | number | 4096 | 捕获内容的最大字符数 | | flushIntervalMs | number | 5000 | 批量上报的刷新间隔（毫秒） | | spanTimeoutMs | number | 300000 | 孤儿 span 超时清理时间（毫秒） | | spans.sessions | boolean | true | 是否追踪 session | | spans.agents | boolean | true | 是否追踪 agent | | spans.llm | boolean | true | 是否追踪 LLM 调用 | | spans.tools | boolean | true | 是否追踪 tool 调用 | | spans.messages | boolean | false | 是否追踪 message | | spans.subagents | boolean | true | 是否追踪 subagent |

Span 层级结构

openclaw.session
  └── openclaw.agent
        ├── {provider}.chat              (LLM 调用)
        │     └── openclaw.tool.{name}   (Tool 调用)
        └── openclaw.subagent            (子 Agent)
  └── openclaw.message                   (消息，独立通道)

语义属性

OpenTelemetry 标准属性（gen_ai.*）

• gen_ai.provider.name — LLM 提供商
• gen_ai.request.model / gen_ai.response.model — 请求/响应模型
• gen_ai.usage.input_tokens / gen_ai.usage.output_tokens — token 用量
• gen_ai.usage.cache_read.input_tokens / gen_ai.usage.cache_creation.input_tokens — 缓存 token 用量
• gen_ai.prompt.0.content / gen_ai.completion.0.content — prompt/completion 内容
• gen_ai.conversation.id — 会话标识
• gen_ai.agent.id — Agent 标识
• gen_ai.tool.name / gen_ai.tool.call.arguments / gen_ai.tool.call.result — Tool 调用详情

OpenClaw 扩展属性（openclaw.*）

• openclaw.session.key — 会话路由 key
• openclaw.cost.usd — 调用费用
• openclaw.context.used / openclaw.context.limit — 上下文用量

许可证

MIT