国士九颜最近把 OpenClaw 接进几个真实业务场景之后，我最大的感受是：它能干的事确实多，但你根本不知道它内部到底发生了什么。飞书机器人回错消息、定时任务“按时执行但结果全错”、某个 skill 时好时坏——这些问题不用可观测性去定位，基本就是盲人摸象。这篇文章是“OpenClaw 全面解析：从零到精通”系列的第 024 篇，重点拆解三个方案：OpenClaw 自带的 Clawmetry、Comet 开源的 Opik、以及行业标准的 OpenTelemetry。如果你已经跑通了 OpenClaw 基础功能，但遇到问题只能靠猜，或者正准备把 OpenClaw 放到生产环境，这篇应该能帮你把“黑盒”变成“透明盒”。
1. 为什么 AI 代理比普通服务更需要可观测性：从一次“看似成功”的定时任务说起
1.1 定时任务执行完毕，但答案完全错误：问题出在哪一层
先讲一个我实际踩过的场景。之前用 OpenClaw 跑了一个每天早上 8 点的定时任务，逻辑很简单：把前一天多渠道的销售数据汇总后发到飞书群。某天早上任务照常执行，日志显示一切正常，飞书也收到了消息，但数字明显不对。一开始我怀疑是数据源接口出了问题，花了大半个小时查上游 API，结果发现一切正常；再查计算逻辑，也找不到毛病。最后实在没办法，把那次任务的完整执行过程扒出来，才发现模型在第二步调用工具时，把“汇总近 7 天”理解成了“只汇总昨天”，更隐蔽的是，那个工具有一个可选参数在 prompt 里没有被传递完整，导致过滤维度直接少了一层。
这就是 AI 代理和传统服务的本质区别。传统服务是确定性的：输入不变，输出基本不变，出了问题按调用链一层层查总能找到根因。但 AI 代理每次执行都经过模型推理，工具参数是动态生成的，执行路径可能不同，甚至同一个任务在不同时间跑出来的结果都会不一样。没有可观测性，你连复现问题都做不到——因为下一次模型可能又理解对了。
1.2 传统监控体系的三个盲区
普通服务的监控体系通常围绕 CPU、内存、请求量、错误率来建设，这套思路放到 OpenClaw 上会漏掉三个非常关键的维度。
第一个是模型层盲区。你完全看不到一次任务消耗了多少 token、模型的输出质量如何、成本是多少。很多人以为 OpenClaw 接上 Ollama 本地免费模型就零成本了，但实际上本地推理的显存占用、延迟、失败重试都是有代价的，而且本地模型能力参差不齐，出错率往往比商用 API 高不少。
第二个是工具调用链盲区。OpenClaw 的核心能力在于调用各种 skill、外部 API 和系统命令，但一次任务往往涉及多个工具的多步调用：工具参数是怎么生成的、返回值有没有被正确解析、失败重试了几次，这些在普通日志里根本看不全。
第三个是审批与安全盲区。OpenClaw 的命令审批机制（exec-approvals）是安全闸门，但审批被拒、审批超时同样会导致任务失败，这类事件需要有审计视角才能快速定位。后面我会专门讲这个。
这三个盲区叠加在一起，会让排查问题变成一个体力活：先猜模型层，再猜工具层，最后猜配置层。而搭建一套针对 AI 代理的可观测性体系，本质就是在模型层、工具层、执行链路层三个维度同时装上“监控探头”。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. Clawmetry：OpenClaw 自带的遥测底子，先把它用起来
2.1 Clawmetry 到底是什么，怎么打开
Clawmetry 这个名字是 Claw 和 Telemetry 的组合，你可以把它理解成 OpenClaw 生态里负责采集自身运行状态的遥测能力的总称。它不是像 Prometheus 那样需要单独部署的大型系统，而是一套内嵌在 OpenClaw 里的数据采集能力，主要包括事件日志、工具调用记录、运行时元数据、审批记录这几类。
启用方式并不复杂，以我安装的版本为例，核心是修改 OpenClaw 的配置文件。配置文件在用户目录下的 .openclaw 文件夹里，Linux 通常是 ~/.openclaw/openclaw.json，Windows 上是 C:\Users\<用户名>\.openclaw\openclaw.json。找到 telemetry 或 clawmetry 相关的配置段，把 enabled 设为 true，日志级别可以先用 debug，等稳定后再调回 info 减少噪音。修改之后重启 OpenClaw 服务，再用 openclaw doctor 检查一下遥测是否在正常收集。
需要提醒的是，不同版本之间字段名可能不一样。如果你的版本里找不到 clawmetry 配置段，可以先用 openclaw --version 确认一下版本号，再看同名版本对应的文档。如果你用的是 dev 通道（通过 openclaw update --channel dev 更新），通常日志信息会更详细，但行为也可能有变化，生产环境我不建议长期跑 dev 通道。
2.2 从 Clawmetry 里能扒出哪些关键信息
打开 Clawmetry 之后，你首先能看到的是一组运行时元数据：OpenClaw 的版本、模型提供方、工作区路径、网关命名空间等。热词里提到的 workspace: c:\users\administrator\.openclaw\workspace 就是这类元数据的典型代表。如果你有多台机器同时跑 OpenClaw，这些元数据就是区分实例的“身份证”，后面接入 OpenTelemetry 做多机统一监控时，标记实例就靠它。
其次是事件流。任务什么时候开始、哪一步调用了哪个工具、工具返回了什么样的状态码、审批是什么时候通过或拒绝的，这些事件会按时间顺序记录下来。排查问题时，我通常先看事件流把执行过程还原一遍，再看具体环节的耗时和返回内容。
第三是基础性能指标，包括任务执行时长的分布、模型调用延迟、网关内存占用等。虽然精度不如完整的 metrics 系统，但胜在零成本，本地调试阶段完全够用。
我的建议是，刚上手 Clawmetry 时先主动跑一两个简单的 skill，然后打开日志看每一步记录。不用多久你就会对 OpenClaw 的执行模型建立直觉，后面再接触 Opik 和 OpenTelemetry 时，理解成本会低很多。
2.3 Clawmetry 的局限：它只是起点，不是终点
Clawmetry 最大的问题是它的视角是单机的。日志默认存在本地磁盘，轮转之后历史数据就没了，你想追溯一周前某个失败任务的具体上下文，基本无能为力。其次，它没有跨服务的关联能力，如果 OpenClaw 同时调用多个外部 API，光靠本地日志很难还原完整的分布式调用链。
更重要的是，Clawmetry 对 LLM 层的洞察非常浅。它只能告诉你“模型调用成功了”或者“失败了”，但你看不到具体的 prompt 是什么、模型输出了什么、为什么模型选中了某个工具而不是另一个。这些问题恰好是 AI 代理排障中最常遇到的。所以 Clawmetry 适合作为本地调试的基础工具，但生产环境必须往 Opik 和 OpenTelemetry 延伸。
3. Opik：把提示词、Token 消耗和模型输出对齐到具体任务
3.1 Opik 到底在跟踪什么
Opik 是 Comet ML 开源的一个 LLM 可观测性平台，解决的是 Clawmetry 覆盖不到的模型层问题。它的核心概念包括 Project、Trace 和 Span。Project 是一个业务域，你可以把“飞书日报”和“群聊助手”分成两个 Project；Trace 对应一次完整的任务调用；Span 是 Trace 里的一个环节，比如“调用了一次 LLM”“执行了一次搜索工具”。
每个 Span 会记录输入输出、Token 用量、成本估算和耗时。最关键的是 Prompt 快照功能——它会把模型实际收到的文本完整保存下来。别小看这个功能，很多诡异问题都要靠它复现。之前遇到过同一套 prompt 三天前回答正常、今天开始答非所问的情况，Clawmetry 只能告诉我“模型调用成功”，但 Opik 的 prompt 快照让我发现，系统消息里拼接的工具描述因为太长被截断了，模型根本没看到后面的工具说明。
如果用一句话概括这三者的关系：OpenClaw 是生产线，Clawmetry 是车间门口的打卡机，Opik 是质检流水线上的录像机。打卡机能记录员工几点进出，但录像机能看清每一步操作细节。
3.2 OpenClaw 接入 Opik 的完整链路配置
接入方式通常有两种。第一种是通过 OpenTelemetry 协议对接：Go 应用普遍都内置了 OTel SDK，OpenClaw 也不例外。你只需要在启动 OpenClaw 前设置环境变量，把 OTLP 导出地址指向 Opik 的接收端即可。自托管 Opik 时，把它的 OTel 接收端口（常见的是 4318）暴露出来，然后在 OpenClaw 侧设置 OTEL_EXPORTER_OTLP_ENDPOINT 指向这个地址，再用 OTEL_SERVICE_NAME 区分业务实例。
第二种方式是通过回调或者插件，在 OpenClaw 的模型配置里加一个自定义 handler，把每次模型调用的入参出参 POST 到 Opik 的 API。这种方式更灵活，但需要自己写胶水代码，适合有定制需求的场景。
Opik 本身支持自托管，用 Docker 跑官方镜像即可，数据完全在自己手上。对于 OpenClaw 用户来说，我建议先自托管，因为云端版本虽然方便，但把内部的 prompt 和工具调用数据传到第三方服务，很多人是不放心的。自托管之后你还能保留完整的历史数据，方便后续做回归评估。
3.3 实战案例：用 Opik 定位“模型变笨”的问题
接 Opik 之后，我最常用它做两件事：一是切换模型前后的对比，二是排查失败任务的根因。
先说你最常见的场景：某天某个 skill 突然变蠢了。在 Opik 里，你可以直接按住时间线筛选出这个 skill 相关的所有 trace，对比前后几天的差异。能看到的可能原因包括：prompt 被系统消息污染、模型路由悄悄切换（比如从官方 API 切到了 NVIDIA NIM 或 Ollama）、上下文窗口占用过高导致关键指令被挤出、成本突然飙升等等。这些信息在调 LLM 应用时就是黄金级 debug 资料。
另一个用法是给 trace 打 tag。我在每次切换模型或者调整 prompt 之后，都会在 Opik 里给当天的新 trace 打上对应的 tag。跑一周之后拉出来对比一次，输出质量、token 成本、平均耗时全部一目了然。这个习惯帮我避免了很多“凭感觉调模型”的弯路。
4. OpenTelemetry：将 OpenClaw 接入 Prometheus/Grafana/Jaeger 的标准通道
4.1 OTel 三件套在代理场景下怎么理解
OpenTelemetry（以下简称 OTel）是 CNCF 下的开源标准框架，核心思路是用一套统一的 API、SDK 和协议，把应用产生的遥测数据（Traces、Metrics、Logs）导出到各种后端系统。对 OpenClaw 来说，它是把可观测性数据“标准化”的关键通道。
Traces 在代理场景下，就是一次任务从触发到完成的完整调用链。比如一个定时任务先调用了 LLM，再调用了搜索工具，最后调用飞书 API 发消息——整条链路可以被串起来，每一步的耗时和结果都能看到。Metrics 是计数器类型的状态数据，比如任务成功数、失败数、工具调用次数、Token 总量、网关内存占用，适合拿来配告警和看趋势。Logs 则是 OpenClaw 自己的运行日志，通过 OTel Logs 统一收集之后，就能把日志、指标、追踪三类数据放到同一个平台里关联分析。
4.2 导出配置实操：从 OpenClaw 到 Collector 再到可视化后端
标准的做法是引入一个 OTel Collector 作为中间层，OpenClaw 把数据推给 Collector，Collector 再按需转发给 Prometheus、Jaeger 或者 Grafana。这样做的优势是：OpenClaw 只需面向一个端点做导出，后端无论怎么换都不影响前端配置。
OpenClaw 侧常见的最小配置如下：
bash复制OTEL_SERVICE_NAME=openclaw-prod-01
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
OTEL_METRICS_EXPORTER=otlp
OTEL_TRACES_EXPORTER=otlp
OTEL_LOGS_EXPORTER=otlp
OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1
上面的配置把 OpenClaw 的 trace、metrics、logs 全部导出到 otel-collector，并设置了 10% 的 trace 采样率。Collector 侧再做一次路由，把 metrics 转发给 Prometheus，把 traces 转发给 Jaeger，把 logs 转发给 Loki，最后由 Grafana 统一展示。
针对 OpenClaw 场景，我建议重点采集这些自定义指标：
| 指标名 | 含义 |
|---|---|
| claw.task.duration | 任务总耗时 |
| claw.task.completed_total | 任务成功总数 |
| claw.task.failed_total | 任务失败总数 |
| claw.tool.invocations_total | 工具调用次数 |
| claw.model.prompt_tokens | 模型输入 Token 数 |
| claw.gateway.memory_usage_bytes | 网关内存占用 |
配上这些指标之后，你就可以在 Grafana 里做一张“OpenClaw 健康看板”：任务成功率趋势、工具调用热点、模型 token 消耗趋势，全部实时可见。
4.3 采样策略：AI 代理场景下必须做的成本控制
我强烈建议，接 OTel 时第一件事就要想清楚采样策略。AI 代理产生的 span 数量远大于普通 Web 服务：一次任务可能包含几十个工具调用和模型调用，每个都是独立 span。如果全量采集，存储成本很快会失控，而且高噪音会让真正的问题淹没在数据里。
常用的有两种策略。一种是头部采样，也就是上面配置里的 parentbased_traceidratio，按比例决定整条 trace 是否被采集，非常简单，适合链路数量大但结构稳定的场景。另一种是尾部采样，在 Collector 侧根据结果决定是否保留：失败的 trace 全量保留，成功的 trace 降低采样比例。生产环境我推荐用尾部采样，因为错误的调用链是最需要被保留下来的，成功的链路反倒不那么重要。这个逻辑跟日志领域里“WARN 以上全保存，INFO 按比例采样”是一个道理。
5. 三个方案怎么选：单机调试、业务调优、生产集群的决策路径
5.1 能力边界与成本对比
很多第一次接触这套体系的人会问：我到底该用哪个？其实三个方案不是互斥的，它们解决的是不同层次的问题。
| 方案 | 核心能力 | 部署成本 | 适合阶段 |
|---|---|---|---|
| Clawmetry | 事件日志、运行元数据、基础指标 | 零成本，完全自带 | 本地调试、入门学习 |
| Opik | LLM 调用追踪、prompt 快照、Token 与成本统计 | 中，需起独立服务 | 业务调优、模型评估 |
| OpenTelemetry | 标准 trace/metrics/logs 导出、生态对接 | 高，需 Collector 加后端 | 生产集群、多机统一运维 |
实际抉择的时候可以简单点：如果只是在自己电脑上跑着玩，Clawmetry 就够了，别过度设计；如果开始把一个 skill 接入真实业务流程了，马上把 Opik 接上，因为它能回答“模型为什么这么回答”这个核心问题；如果 OpenClaw 已经部署在服务器上、有多个实例、要配合团队运维了，那 OTel 这条线躲不开。
5.2 推荐组合拳：三层各司其职
我自己目前在用的组合是：Clawmetry 兜底 + Opik 看模型质量 + OpenTelemetry 建统一运维监控。Clawmetry 负责记录本地最原始的事件流，出问题时第一时间能翻开看；Opik 负责模型层的深度追踪，每次调 prompt、换模型都有据可查；OTel 负责把日志、指标、追踪统一汇总到 Grafana，让整个团队的运维同学不需要登录每台机器就能看到 OpenClaw 的整体健康状况。
这套组合在淘汰赛上的价值是：出了问题先看 Grafana 告警，定位到具体实例；然后去 Opik 看对应时间段的模型调用细节；如果再深挖，就回 Clawmetry 翻原始事件流。三层定位下来，90% 的问题能在几分钟内锁定根因。
6. 部署与排障中容易翻车的细节：元数据、网关日志、命令审批与 Windows 环境
6.1 runtime metadata 丢失的排查链路
接入 OTel 之后最常遇到的一个坑是：后端看到的 service name 混乱或者元数据丢失，多个 OpenClaw 实例混在一起没法区分。这个问题的排查链路一般是固定的。
先看 OpenClaw 进程启动时有没有正确加载 OTEL_SERVICE_NAME。有些人的进程是通过 shell 脚本启动的，环境变量只写在当前终端里，进程一重启就丢了。你可以用 ps aux | grep -i openclaw 看一下启动命令，再手动检查进程的 /proc 环境，确认变量是否真被加载。第二步看有没有 OTEL_RESOURCE_ATTRIBUTES 覆盖了默认的 service.name，如果多台机器用了相同的 attribute，也会出现实例互相“顶替”的现象。第三步确认所有机器上的 OpenClaw 版本是否一致，dev 和 stable 通道的元数据格式偶尔会有差异，导致后端识别字段对不上。
这类问题本质是配置一致性的问题，建议把环境变量统一写进 systemd 服务文件或者 Windows 的系统环境变量里，而不是放在 shell 启动脚本中。
6.2 启动卡在“网关启动中”的排查链路
另一个高频问题就是热词里提到的“打开时一直卡在网关启动中”。OpenClaw 启动时会拉起本地网关和 Web UI，如果网关迟迟起不来，界面就会一直停在启动中。
我的排查顺序是这样的：先打开日志目录（Linux 下是 ~/.openclaw/logs/，Windows 下默认写在工作区附近），重点看 gateway 相关日志，确认是端口占用、配置解析失败还是模型连接不上。很多情况下是端口被占用，检查一下 8080 或自定义端口是否被其他进程抢了。其次是模型配置问题，比如配置了远程模型但网络不通，或者本地 Ollama 没启动。排错时我习惯先在配置里临时切到一个本地模型（比如 Ollama），排除外部网络因素，再逐步加回外部服务，这样能快速划定问题边界。
6.3 exec-approvals.json 与审计视角
命令审批是 OpenClaw 的一道安全闸门，它的持久化记录在 exec-approvals.json 文件里，Linux 下通常是 ~/.openclaw/exec-approvals.json，记录哪些命令被允许、哪些被拒绝。
排查任务失败时，很多人忽略先看审批记录，结果绕了一大圈发现根本不是模型问题，而是某条命令在审批环节被拦下了。生产环境我强烈建议把审批事件一并接入 OTel，这样在 Grafana 审计面板里能看到完整的时间线：什么时间、哪个 skill、请求执行什么命令、由谁审批、结果是允许还是拒绝。这不仅是排障工具，也是安全合规的重要依据。审批策略上，生产环境尽量少用完全自动放行的配置，权限收得紧一点，配合审计视图，出问题才能说得清。
6.4 Windows 环境特有问题
热词里活跃着一大批 Windows 用户，比如用 PowerShell 安装、workspace 路径在 C:\Users\administrator\.openclaw\workspace。Windows 部署 OpenClaw 有几个常见的坑值得单独说。
第一是环境变量设置。PowerShell 里用 setx 设置永久环境变量后，需要重启终端甚至重启 OpenClaw 服务才能生效，很多人在这里踩坑，以为设置没成功。第二是路径问题。Windows 路径里如果有空格或中文字符，容易导致某些工具传参失败，建议把 .openclaw 工作目录放在纯英文路径下。第三是防火墙。OTLP 导出的 4318 端口如果没放行，数据根本出不去，但 OpenClaw 本体看起来一切正常，这种“静默失败”最坑人。第四是更新通道。Windows 下用 openclaw update --channel stable 保持稳定版，dev 通道虽然日志更详细，但在 Windows 上遇到兼容性问题的概率也更高。
说回我自己的使用体会。刚开始我也觉得可观测性是“高级功能”，等踩了几次“看似成功实则全错”的坑之后才意识到，对它来说这更像是保住工作时间的保命功能。不管你是用 OpenClaw 跑飞书机器人、对接微信插件、配合 Obsidian 做项目管理，还是接阿里云 API、NVIDIA NIM，只要你开始依赖它自动执行任务，就值得先花半小时把 Clawmetry 打开，再花半天把 Opik 和 OpenTelemetry 接好。最后再分享一个小技巧：每次切换模型或者调整 prompt 之后，在 Opik 里给对应的 trace 打个 tag，一周后回来对比一次质量和成本，你会发现这笔小小的投入，回报率远超预期。