企业官网建设流程全解析

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_KEY=sk-your-key-here LOGFIRE_TOKEN=your-logfire-token-here OTEL_EXPORTER_OTLP_ENDPOINT=https://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 = true

base_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

安装完成后重启 Gateway：

openclaw 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/4318）；projectUrl 写错了。如果日志里出现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 相关输出，大部分上报问题都能从那里找到线索。