1. 从一句 Done 说起OpenClaw 全链路可观测到底缺什么如果你正在用 OpenClaw 跑自动化 Agent大概率遇到过这种场景群里 一下机器人丢过去一个需求链接几秒后它回你一句「Done」。任务到底做没做工具调没调中间哪一步被 Prompt 规则拦下来了没人知道。这不是 OpenClaw 的问题而是所有 Agent 系统在进入真实业务后都会撞上的墙——执行过程不可见。OpenClaw 一次看似简单的对话背后可能经历了意图理解、Prompt 组装、模型推理、工具调用、外部结果回填、二次生成、流式输出等多个阶段。传统文本日志面对这种链路会迅速失效System Prompt 很长、JSON 层层嵌套、模型中间输出和 HTTP 上下文混在一起信息不是没有而是太碎、太难关联。最后大家只能回到最原始的方式——盯日志、猜原因、改 Prompt、再试一次。OpenClaw-Observability就是为解决这个问题而生的插件。它把 Agent 生命周期中的关键事件结构化采集下来用DuckDB做本地列存分析底座把原本黑盒的执行过程还原成可追踪的 Trace 瀑布图。配合TaoToken统一 Key 接入模型侧调用整条链路——从用户输入到模型响应再到工具执行——都能落库、可查、可聚合。这篇文章适合三类人正在用 OpenClaw 搭建 Agent 但排障靠猜的开发者想给现有 Agent 加一层可观测能力但不想引入重型组件的工程师以及希望用统一 API 通道管理多模型调用的团队。下面我会从环境准备、DuckDB 建表、OpenClaw 埋点配置、TaoToken 接入参数到完整链路验证一步步给出可复制的片段。2. TaoToken 前置准备统一 Key 与 API 通道配置在开始配置 OpenClaw-Observability 之前先把模型侧的调用通道理顺。OpenClaw 的 Agent 在执行过程中会多次调用 LLM如果每个组件各自维护一套 Key 和 Base URL排障时很难区分是模型侧问题还是 Agent 逻辑问题。用 TaoToken 统一 Key 接入的好处是所有模型调用走同一个 API 通道Trace 里的 LLM 事件能对应到统一的调用记录排查时不会因为多套凭证而串线。2.1 获取 API Key 与确认 Base URL首先到 TaoToken 控制台创建一个 API Key。登录后进入控制台的 API Keys 页面新建一个 Key 并复制保存。这个 Key 会同时用于 OpenClaw 的模型调用和后续的验证请求。TaoToken 的 API 接入地址是https://taotoken.net/api注意这个地址不带任何查询参数直接作为 Base URL 使用。如果你用的是 OpenAI 兼容的 SDK 或客户端Base URL 填这个即可如果是 Anthropic 风格的调用路径会在此基础上拼接。2.2 在 OpenClaw 中配置模型通道OpenClaw 的模型配置通常在 Gateway 的配置文件或环境变量中。以环境变量方式为例你需要设置三个核心参数export TAOTOKEN_API_KEYsk-你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_MODELclaude-sonnet-4-20250514如果你用的是 OpenClaw 的配置文件通常是~/.openclaw/config.toml或项目根目录下的openclaw.toml可以写成[llm] provider taotoken base_url https://taotoken.net/api api_key sk-你的Key model claude-sonnet-4-20250514这里有个容易踩的坑Base URL 末尾不要多加/v1或/chat/completionsOpenClaw 和大多数 OpenAI 兼容客户端会自动拼接路径。多写了会导致 404而 404 在 Trace 里看起来像是工具调用失败容易误判。2.3 验证 Key 是否可用在正式接入 OpenClaw 之前先用一条 curl 确认 Key 和通道没问题curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: reply with ok}], max_tokens: 16 }如果返回里有choices字段和正常的 content说明通道通了。这一步很重要——先确认模型侧可用再去配可观测插件否则后面 Trace 里出现 LLM 事件报错时你分不清是 Key 问题还是插件问题。2.4 为什么要在可观测之前先统一 KeyOpenClaw 的 Agent 可能同时调用多个模型主推理模型、子任务模型、工具内嵌的小模型。如果这些调用走不同的 Key 和 Base URLObservability 插件采集到的 LLM 事件虽然有时间戳和 Token 数但无法关联到统一的调用来源。用 TaoToken 统一 Key 之后所有 LLM 事件在 Trace 里都能对应到同一条 API 通道聚合分析时「按模型统计 Token 消耗」这类查询才有意义。另外TaoToken 的 Coding Plan 适合长期跑 Agent 任务的场景如果你打算让 OpenClaw 持续执行代码修复、需求解析这类任务可以了解一下套餐的调用额度避免跑到一半 Key 限额了导致 Trace 里出现大量 429。3. 可复制配置DuckDB 建表与 OpenClaw 埋点开关这一节是整篇文章的核心操作部分。我会给出 DuckDB 的建表语句、OpenClaw-Observability 的安装与配置、以及埋点开关的具体参数。所有片段都可以直接复制使用。3.1 安装 OpenClaw-Observability 插件OpenClaw 的插件安装通过 CLI 完成openclaw plugins install openclaw-observability安装完成后重启 Gatewayopenclaw gateway restart重启后插件会自动启动并在本地创建 DuckDB 数据库文件。默认路径通常在~/.openclaw/observability/observations.duckdb。你可以通过插件配置修改这个路径。3.2 DuckDB 建表语句插件会自动建表但如果你需要手动初始化或想了解底层 Schema下面是核心表的建表语句。这张表是整个可观测体系的基础CREATE TABLE IF NOT EXISTS observations ( id BIGINT PRIMARY KEY, trace_id VARCHAR NOT NULL, parent_id VARCHAR, run_id VARCHAR, observation_type VARCHAR NOT NULL, name VARCHAR, start_time TIMESTAMP NOT NULL, end_time TIMESTAMP, duration_ms DOUBLE, input_json TEXT, output_json TEXT, model VARCHAR, prompt_tokens INTEGER, completion_tokens INTEGER, total_tokens INTEGER, status VARCHAR DEFAULT ok, error_message TEXT, metadata_json TEXT ); CREATE INDEX IF NOT EXISTS idx_observations_trace ON observations(trace_id); CREATE INDEX IF NOT EXISTS idx_observations_type ON observations(observation_type); CREATE INDEX IF NOT EXISTS idx_observations_start ON observations(start_time);几个字段值得说明trace_id和parent_id构成树状调用关系前端瀑布图就是靠这两个字段还原的observation_type区分llm、tool、stream等事件类型input_json和output_json保存完整的输入输出快照支持事后复盘run_id用于关联主任务和并行子任务避免链路串线。3.3 OpenClaw 侧埋点开关配置插件的配置文件通常在~/.openclaw/plugins/observability/config.toml。下面是一份完整的配置片段[observability] enabled true db_path ~/.openclaw/observability/observations.duckdb flush_interval_ms 500 buffer_size 1000 async_write true [observability.hooks] session_start true message_received true llm_start true llm_end true tool_before true tool_after true stream_thinking true stream_assistant true run_switch true [observability.redaction] enabled true patterns [sk-[a-zA-Z0-9], Bearer [a-zA-Z0-9\\-_.]]async_write true是关键——采集事件先进入内存缓冲区通过串行队列批量 flush 到 DuckDB主链路只做轻量入队不等待磁盘 I/O。这样可观测插件不会反过来拖慢 Agent 的执行速度。redaction部分用于脱敏避免 API Key 被写进input_json或output_json。如果你在 Prompt 里传了凭证这个配置能自动替换掉。3.4 流式输出时长回填配置流式输出阶段有些时长信息并不天然完整比如 thinking 事件的结束时间可能缺失。插件后端会按下一节点的时间点回填保证前端时间轴稳定可读。这个行为通过下面的配置控制[observability.stream] backfill_duration true thinking_timeout_ms 30000thinking_timeout_ms是兜底值如果下一个节点迟迟不来超过这个时间就按超时处理避免 Trace 里出现无限长的 thinking 段。3.5 可视化界面访问配置完成后可视化界面默认在http://localhost:18789/plugins/observability打开后可以看到三类视图Trace 视图按时间顺序展示一次执行链路中的 LLM、工具、子任务与输出过程分析视图聚合 Token、会话数、耗时分布、失败率等指标安全视图展示规则扫描与高危行为链告警。3.6 与 TaoToken 的配置对齐确保 OpenClaw 的 LLM 配置和 Observability 插件使用的是同一套 TaoToken 参数。如果你在openclaw.toml里配了base_url https://taotoken.net/api那么 Trace 里的 LLM 事件会记录这个来源。聚合查询时可以用model字段统计不同模型的 Token 消耗SELECT model, COUNT(*) AS calls, SUM(total_tokens) AS tokens, AVG(duration_ms) AS avg_ms FROM observations WHERE observation_type llm AND start_time now() - INTERVAL 7 DAY GROUP BY model ORDER BY tokens DESC;这条查询在 DuckDB 的列存引擎下跑 50 万条记录通常在一秒内返回这也是选 DuckDB 而不是 SQLite 的核心原因——可观测场景最常见的需求就是「对过去 7 天的 Token 消耗做求和」或「统计不同模型的分布」列存引擎在这类聚合上有天然优势。4. 验证请求一次完整链路的数据落库与聚合查询配置完成后需要跑一次完整的请求链路来验证数据是否正常落库、指标是否可聚合。这一节给出具体的验证步骤和预期结果。4.1 触发一次 Agent 执行在 OpenClaw 的对话入口发送一条会触发工具调用的消息。比如帮我查一下项目 DEMO-123 的状态这条消息会触发 Agent 解析意图、调用工具、生成回复。执行完成后打开可视化界面http://localhost:18789/plugins/observability你应该能看到一条新的 Trace。4.2 用 DuckDB CLI 直接查库除了界面你也可以直接用 DuckDB CLI 查库验证。先安装 DuckDB CLI如果还没装brew install duckdb然后打开数据库文件duckdb ~/.openclaw/observability/observations.duckdb查询最近 10 条 observationSELECT trace_id, observation_type, name, duration_ms, status FROM observations ORDER BY start_time DESC LIMIT 10;预期结果里应该能看到llm、tool、stream等不同类型的事件且同一个trace_id下有多条记录构成一条完整链路。4.3 还原一次完整调用链用下面的查询还原某条 Trace 的完整执行过程SELECT observation_type, name, start_time, duration_ms, status, prompt_tokens, completion_tokens FROM observations WHERE trace_id 你的trace_id ORDER BY start_time;这条查询返回的结果就是瀑布图的数据源。你会看到类似这样的顺序session_start→llm意图理解→tool工具调用→llm二次生成→stream流式输出。每一步的耗时和 Token 消耗都清晰可见。4.4 聚合指标验证验证指标聚合是否正常SELECT DATE_TRUNC(hour, start_time) AS hour, COUNT(*) AS total_events, SUM(CASE WHEN status error THEN 1 ELSE 0 END) AS errors, SUM(total_tokens) AS tokens FROM observations WHERE start_time now() - INTERVAL 24 HOUR GROUP BY hour ORDER BY hour;如果这条查询能正常返回按小时聚合的事件数、错误数和 Token 消耗说明整条链路——从 OpenClaw 埋点采集、异步写入 DuckDB、到聚合查询——全部打通。4.5 验证 TaoToken 调用是否被正确记录重点检查 LLM 事件的model字段和 Token 数SELECT model, COUNT(*) AS calls, SUM(prompt_tokens) AS prompt_tokens, SUM(completion_tokens) AS completion_tokens, AVG(duration_ms) AS avg_latency_ms FROM observations WHERE observation_type llm AND start_time now() - INTERVAL 1 HOUR GROUP BY model;如果model字段显示的是你在 TaoToken 配置里指定的模型名且 Token 数不为零说明模型侧调用被正确采集。如果 Token 数为零但调用成功检查插件的llm_endhook 是否开启以及 TaoToken 返回的响应里是否包含 usage 字段。4.6 流式输出时长回填验证检查 thinking 事件的时长是否被正确回填SELECT name, start_time, end_time, duration_ms FROM observations WHERE trace_id 你的trace_id AND observation_type stream ORDER BY start_time;正常情况下每个 stream 事件都应该有非空的end_time和合理的duration_ms。如果某个事件end_time为空说明回填逻辑没有触发检查backfill_duration配置是否为 true。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth配置过程中最容易撞上的几类报错这里逐一给出排查路径。这些报错在 Trace 里可能表现为 LLM 事件 status 为 error或者插件启动失败。5.1 401 Unauthorized现象Trace 里 LLM 事件 status 为 errorerror_message 包含 401或者 curl 验证时直接返回 401。排查步骤第一确认 API Key 是否正确复制有没有多余空格。TaoToken 的 Key 通常以sk-开头复制时容易带上换行符。第二确认 Base URL 是否正确。TaoToken 的 API 地址是https://taotoken.net/api不要写成https://taotoken.net/api/v1或带其他路径。OpenClaw 和 OpenAI 兼容客户端会自动拼接/v1/chat/completions。第三确认请求头格式。必须是Authorization: Bearer sk-xxxBearer 和 Key 之间有一个空格。第四如果用的是 Anthropic 风格的调用确认路径和请求头格式是否匹配。Anthropic 用的是x-api-key头而不是Authorization。5.2 local proxy failed现象插件启动时报local proxy failed或者 Trace 里 LLM 事件全部失败。排查步骤这个报错通常和网络配置有关。首先确认你的环境能正常访问https://taotoken.net/api。可以用 curl 直接测试curl -v https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d {model:claude-sonnet-4-20250514,messages:[{role:user,content:test}],max_tokens:8}如果 curl 能通但 OpenClaw 报 local proxy failed检查 OpenClaw 的代理配置是否覆盖了 Base URL。有些环境会设置HTTP_PROXY或HTTPS_PROXY环境变量导致请求被转发到不可达的地址。可以临时 unset 这些变量再试unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy openclaw gateway restart另外检查 OpenClaw 配置文件里有没有proxy相关的字段如果有且指向本地端口确认那个端口是否有服务在监听。5.3 reading choices 报错现象Trace 里 LLM 事件 error_message 包含reading choices或cannot read property choices of undefined。排查步骤这个报错说明客户端期望返回体里有choices字段但实际返回的结构不匹配。常见原因有三个第一Base URL 配错了请求打到了错误的端点返回的不是 OpenAI 兼容格式。确认 Base URL 是https://taotoken.net/api。第二模型名写错了服务端返回了错误信息而不是正常的 completions 结构。检查model字段是否和 TaoToken 支持的模型名一致。第三请求体格式不对比如messages字段缺失或格式错误导致服务端返回 400 而不是正常的 choices 结构。用 curl 单独验证请求体curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: hello}], max_tokens: 16 } | head -c 500如果 curl 返回正常但 OpenClaw 报错检查 OpenClaw 的 LLM provider 配置是否和 TaoToken 的接口格式匹配。5.4 OAuth 相关报错现象Trace 里出现 OAuth 相关错误或者插件启动时提示认证失败。排查步骤OpenClaw 的某些组件可能使用 OAuth 流程获取凭证。如果你同时配置了 TaoToken 的 API Key 和 OAuth确认两者没有冲突。检查配置文件里是否有oauth字段如果有且不需要可以注释掉。另外如果你用的是 Claude Code 或类似的客户端OAuth 和 API Key 是两种不同的认证方式。用 TaoToken 统一 Key 接入时应该走 API Key 方式不需要 OAuth 流程。确认客户端的认证配置里没有残留的 OAuth 设置。5.5 插件安装后 Trace 为空现象插件安装成功Gateway 也重启了但可视化界面里没有任何 Trace。排查步骤第一确认enabled true在配置文件里。第二确认 DuckDB 文件路径可写。检查~/.openclaw/observability/目录是否存在权限是否正确。第三确认 hooks 配置里至少开启了session_start和llm_start。如果全部是 false采集不到任何事件。第四检查 Gateway 日志里有没有插件加载失败的报错openclaw gateway logs | grep observability第五如果用的是云上 RDS DuckDB确认连接串和凭证正确。本地单文件模式下一般不会有连接问题。5.6 Token 数为零现象LLM 事件被采集到了但prompt_tokens和completion_tokens都是零。排查步骤第一确认 TaoToken 返回的响应里包含 usage 字段。有些模型或某些调用方式可能不返回 usage。第二检查插件的llm_endhook 是否开启。如果只开了llm_start结束事件不会被采集Token 数自然为零。第三检查output_json里是否有 usage 信息。如果有但没写入 Token 字段可能是插件的解析逻辑问题检查插件版本是否最新。6. 语义一致 CTA把可观测能力接到你的 OpenClaw 工作流到这里OpenClaw-Observability 的核心配置已经跑通了。你有了 DuckDB 本地列存底座、完整的埋点采集、以及可聚合的 Trace 数据。接下来可以根据自己的场景做扩展。如果你还在配置 TaoToken 的 Key 和通道可以直接到控制台创建 API Key接入文档里有各语言 SDK 的示例。模型对话页面可以快速验证 Key 是否可用不用写代码就能测通。对于长期跑 Agent 任务的团队Coding Plan 提供了更适合持续调用的额度方案。如果你的 OpenClaw 需要频繁调用模型做代码修复、需求解析这类任务可以对比一下套餐的调用量避免跑到一半 Key 限额导致 Trace 里出现大量 429 错误——这类错误在可观测体系里很容易被误判为模型侧故障实际上是额度问题。可观测性不是锦上添花而是 Agent 系统进入真实业务后的基础能力。模型会幻觉工具会失败上下文会被污染规则会互相冲突。没有可观测能力系统越复杂维护成本越高。先把执行过程看得见后面的一切优化、治理和扩展才有基础。最后分享一个实用技巧定期把 DuckDB 的数据导出成 Parquet接入下游的分析体系。DuckDB 的COPY命令可以直接导出COPY (SELECT * FROM observations WHERE start_time now() - INTERVAL 30 DAY) TO observations_30d.parquet (FORMAT PARQUET);这样既保留了本地单文件的轻量优势又能在需要时把数据接到更大的分析平台。