1. 生产环境里 OpenClaw 为什么需要可观测性OpenClaw 在本地跑通和在生产环境稳定运行完全是两件事。本地调试时你盯着终端输出就够了但一旦部署到生产环境Agent 内部执行逻辑就变成了一个黑盒——用户发来一条消息Agent 内部经历了什么、调用了哪些工具、LLM 请求花了多久、Token 消耗了多少这些信息如果拿不到排查问题基本靠猜。我遇到过的典型场景某个工具调用偶发超时但日志里只看到最终失败中间链路完全不可见又或者某天 Token 消耗突然翻倍却不知道是哪个模型、哪个 Agent 环节导致的。这类问题在单机开发时几乎不会遇到但生产环境一旦多实例部署没有分布式追踪就根本定位不了。OpenTelemetry 和 Logfire 的组合就是来解决这个问题的。OpenTelemetry 负责采集追踪、指标、日志三类数据Logfire 负责可视化展示和查询。而 TaoToken 在这里扮演的角色是统一 Key 和 API 通道——OpenClaw 的 LLM 调用、工具调用都走 TaoToken 的 API 入口这样监控数据里的模型调用链路才能和实际的 API 请求对应上。这篇内容适合已经在用 OpenClaw 做生产部署、或者正准备把 Agent 从测试环境推到线上的开发者。我会从配置文件骨架开始一步步给出可复制的 settings.json 和 config.toml 配置然后验证请求是否成功上报最后把常见的坑列出来。2. TaoToken 前置准备统一 Key 与 API 通道在配置可观测性之前先把 TaoToken 的接入准备好。OpenClaw 的 LLM 调用需要走统一的 API 通道这样 OpenTelemetry 采集到的 gen_ai 语义数据才能和实际请求对应上。2.1 获取 API Key访问 TaoToken 控制台创建 API Key。建议按环境区分 Key比如生产环境用一个、测试环境用一个这样在 Logfire 里可以通过 serviceName 和 API Key 的映射关系快速定位问题来源。创建 Key 的入口在控制台的 API Keys 页面。拿到 Key 之后不要直接写进配置文件后面会讲怎么用环境变量管理。2.2 确认 API 端点TaoToken 的 API 端点是https://taotoken.net/api这个地址在 OpenClaw 的配置里会用到。模型对话、Coding Plan 等不同场景的接入方式略有差异但底层都是通过这个 API 入口。如果你用的是 Claude Code 或者 Anthropic 风格的接口TaoToken 也提供了对应的兼容端点具体可以参考接入文档里的说明。2.3 环境变量管理在~/.openclaw/.env里写入TAOTOKEN_API_KEYsk-your-key-here LOGFIRE_TOKENyour-logfire-token-here OTEL_EXPORTER_OTLP_ENDPOINThttps://logfire.pydantic.dev/v1/otlp这里把 TaoToken 的 Key 和 Logfire 的 Token 分开管理避免混在一起。生产环境建议用密钥管理服务不要明文放在 .env 里。3. 可复制配置settings.json 与 config.toml 骨架OpenClaw 的配置分两块settings.json 管插件和运行时行为config.toml 管模型和 API 通道。下面给出的是可以直接复制修改的骨架。3.1 settings.json 配置{ plugins: { entries: { ultrathink-solutions/openclaw-logfire: { enabled: true, config: { projectUrl: https://logfire.pydantic.dev/your-org/your-project, environment: production, serviceName: openclaw-prod-gateway, distributedTracing: { enabled: true, injectIntoCommands: true, extractFromWebhooks: true, urlPatterns: [ https://taotoken.net/api/*, https://api.mycompany.com/* ] }, captureToolInput: true, captureToolOutput: false, toolInputMaxLength: 2048, captureMessageContent: false, redactSecrets: true, captureStackTraces: true, sampling: { rate: 0.1 } } } } } }几个关键点说明。urlPatterns里把 TaoToken 的 API 地址加进去这样 OpenClaw 调用 LLM 时注入的 traceparent 头部才能正确传播到 TaoToken 的 API 请求上。sampling.rate设为 0.1 表示只上报 10% 的追踪数据生产环境高吞吐场景下这个值可以平衡可观测性和成本。3.2 config.toml 配置[model] provider openai-compatible base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model_name gpt-4o [model.observability] enabled true otel_endpoint https://logfire.pydantic.dev/v1/otlp otel_headers { Authorization Bearer ${LOGFIRE_TOKEN} } [gateway] host 0.0.0.0 port 8080 log_level info [gateway.telemetry] metrics_enabled true traces_enabled true logs_enabled truebase_url指向 TaoToken 的 API 地址api_key_env引用环境变量而不是硬编码。otel_headers里的 Authorization 用 Logfire 的 Token这样 OTLP 导出器才能把数据推到 Logfire。3.3 安装插件cd ~/.openclaw npm install ultrathink-solutions/openclaw-logfire如果是开发模式可以用符号链接git clone https://github.com/Ultrathink-Solutions/openclaw-logfire.git cd openclaw-logfire npm install ln -s $(pwd) ~/.openclaw/extensions/openclaw-logfire安装完成后重启 Gatewayopenclaw gateway restart openclaw plugins status | grep logfire看到插件状态是 enabled 就说明加载成功了。4. 验证请求与成功结果配置写完不代表数据就能上报需要做几步验证。4.1 检查插件加载状态openclaw plugins status输出里应该能看到ultrathink-solutions/openclaw-logfire的状态是 enabled。如果显示 disabled检查 settings.json 里的 enabled 字段和插件路径是否正确。4.2 发一条测试请求curl -X POST http://localhost:8080/v1/chat \ -H Content-Type: application/json \ -d {message: hello, test observability}这条请求会触发 OpenClaw 的 Agent 执行流程插件会在 message-received、before-agent-start、llm-input、llm-output 等钩子点创建 Span。4.3 在 Logfire 控制台确认数据打开 Logfire 项目页面在 Traces 视图里应该能看到一条 invoke_agent 的根 Span下面挂着 gen_ai.chat 和 execute_tool 的子 Span。点开 gen_ai.chat 可以看到模型名称、输入输出 Token 数、调用耗时。如果用的是 TaoToken 的 API 通道Span 里的 gen_ai.provider.name 应该显示对应的提供商信息gen_ai.request.model 显示实际调用的模型名。4.4 验证分布式追踪如果 OpenClaw 调用了外部服务检查外部服务的日志里是否收到了 traceparent 头部。可以在 urlPatterns 里加一个测试用的 HTTP 端点然后看那个端点的访问日志里有没有traceparent: 00-xxx-xxx-01格式的头部。5. 本篇常见错排查5.1 数据未上报到 Logfire症状是 Logfire 控制台看不到任何数据。按顺序排查# 检查环境变量 echo $LOGFIRE_TOKEN echo $TAOTOKEN_API_KEY # 检查网络连通性 curl -I https://logfire.pydantic.dev # 查看 Gateway 日志 tail -f ~/.openclaw/logs/gateway.log | grep -i logfire\|otel\|export常见原因有三个LOGFIRE_TOKEN 没设置或者设置错了网络策略阻止了 OTLP 端口4317/4318projectUrl 写错了。如果日志里出现OTLP export failed基本就是网络或 Token 的问题。5.2 Span 数据量过大导致成本激增如果 Logfire 账单突然涨了先检查这几个配置{ captureToolOutput: false, toolInputMaxLength: 1024, captureMessageContent: false, sampling: { rate: 0.05 } }把工具输出关掉、输入截断长度减小、消息内容不记录、采样率降到 5%数据量能降一个数量级。生产环境不建议全量采集除非你有明确的合规要求。5.3 追踪链路断裂分布式追踪里某些 Span 没有关联到父 Span表现为多个独立的根 Span。检查三点urlPatterns 是否包含了目标 URL目标服务是否支持 OTEL 追踪injectIntoCommands 是否启用。如果目标服务不支持 OTEL那链路断裂是正常的你只能在 OpenClaw 这一侧看到 Span跨服务的关联需要目标服务也接入 OTEL。5.4 TaoToken API 调用没有出现在追踪里如果 gen_ai.chat Span 里看不到 TaoToken 相关的模型信息检查 config.toml 里的 base_url 是否指向了https://taotoken.net/api以及 api_key_env 引用的环境变量是否生效。另外确认 settings.json 的 urlPatterns 里包含了https://taotoken.net/api/*否则 traceparent 头部不会注入到 TaoToken 的 API 请求上。6. 接入与排障入口可观测性链路搭起来之后日常排障主要看两个地方Logfire 的 Traces 视图定位慢请求和错误链路Metrics 视图看 Token 消耗和延迟趋势。如果你在接入过程中遇到 API Key 或者通道配置的问题可以直接在 TaoToken 控制台检查 Key 状态和用量。模型对话相关的调试可以用模型对话页面快速验证请求是否通。长期做编码和 Agent 开发的Coding Plan 里可以管理多个项目的接入配置。接入文档里有完整的 API 端点和参数说明配置过程中对照着检查能省不少时间。排障时优先看 Gateway 日志里的 OTLP export 相关输出大部分上报问题都能从那里找到线索。