本文引导你将 ArkClaw 执行过程的 Trace 数据上报至扣子罗盘。Trace 数据被上报到扣子罗盘后，你可以利用扣子罗盘的分析与可视化能力，深入洞察 ArkClaw 的使用成本、性能与行为。

安装插件

扣子罗盘提供了 OpenClaw Trace 上报插件。你只需要安装该插件就能实现 ArkClaw 的 Trace 数据上报。

准备工作

在开始之前，请确保你已完成以下准备工作：

获取了扣子罗盘空间 ID 和服务访问令牌。

扣子罗盘空间 ID：切换到目标空间，点击其右侧的复制按钮获取空间 ID。详细获取方式参考获取扣子罗盘空间 ID。

服务访问令牌：获取方式参考配置服务访问令牌。

有一个已创建且正常运行的 ArkClaw。参考 ArkClaw 的官方文档了解如何创建 ArkClaw。

步骤一：安装插件

通过终端进入 ArkClaw，运行以下命令安装插件。

你需要按照命令行提示分别提供服务访问令牌和扣子罗盘空间 ID。

步骤二：验证插件

你可通过以下命令查看插件状态，如果 Openclaw Cozeloop Trace 的状态为 loaded，则说明插件加载成功。此时，所有与 OpenClaw 对话的 Trace 就可以被上报到扣子罗盘。

管理插件

升级或重装插件

要升级或重装插件，你可以直接重新执行步骤一：安装插件。

如果在执行过程中遇到关于“插件不存在”的报错，可以尝试运行 openclaw doctor --fix 命令进行修复。

更新插件配置

你安装插件时，OpenClaw 配置文件（~/.openclaw/openclaw.json）中的 plugins.allow 和 plugins.entries 字段会被自动更新。因此，一般情况下你无需手动修改 OpenClaw 配置文件。

如果你需要手动修改 OpenClaw 配置文件中的插件配置，可参考以下配置项说明。

配置项	是否必选	说明	示例值
openclaw-cozeloop-trace.config.authorization	必选	扣子罗盘的服务访问令牌。获取方式参考配置服务访问令牌。	"Bearer {sat_iH*************A}"
openclaw-cozeloop-trace.config.workspaceId	必选	扣子罗盘空间 ID。详细获取方式参考获取扣子罗盘空间 ID。	"74*****"
openclaw-cozeloop-trace.config.endpoint	可选	Trace 上报地址，默认使用https://api.coze.cn/v1/loop/opentelemetry。	"https://api.coze.cn/v1/loop/opentelemetry"
openclaw-cozeloop-trace.config.debug	可选	用于控制是否开启 Debug 日志。此功能默认关闭。在安装插件时不会添加该参数。	false

查看 Trace 数据

实现 OpenClaw Trace 数据的上报后，启动你的 OpenClaw 应用并发起对话。接下来，你就可以在扣子罗盘中查看 OpenClaw 的 Trace 数据。

访问你的扣子罗盘工作空间。

在扣子罗盘的观测 > Trace 页面，把上报类型设置为 SDK 上报，你应该能看到上报的 Trace 数据。

点击任意一条 Trace 即可查看详细的 Span 调用链、属性和耗时信息。

OpenClaw Trace 数据的结构如下所示（根据实际情况可能略有不同）：

应用场景

将 OpenClaw 的 Trace 数据上报至扣子罗盘后，你可以利用这些数据实现以下应用场景。

场景一：统计 Token 消耗

你可以在扣子罗盘中查看 OpenClaw 使用不同模型所产生的 Token 消耗。

访问你的扣子罗盘工作空间。

在扣子罗盘的观测 > 统计页面，选择上报类型为 SDK 上报，然后把模型设置为 OpenClaw 所使用的模型。

场景二：排查问题

扣子罗盘的 Trace 数据采用逐步上报机制：已完成的节点会先上报，根节点（Root Span）最后上报。这让你可以根据已完成的节点，实时跟进请求的执行情况，从而高效排查问题。

在排查问题时，建议你切换到 All Span 视图，以查看请求的最新执行状态。

例如，当你向 OpenClaw 发出“帮我查看桌面上的一个文件”的指令后，若它陷入不断重复 read 操作的循环中，你可以立即在 Trace 视图中观察到这一行为。

此时，点击该请求的任意 Span，即可查看其详细的执行 Trace，帮助你快速定位问题并采取相应措施（如重启 OpenClaw）。

常见问题

新版 OpenClaw 不上报 Token 用量

自 openclaw 2026.3.7 版本起，其 usage 数据的处理方式发生了变化，且官方未再提供相关的控制选项。

我们正在关注官方进展并探索新的上报方法。在此期间，你可以暂时选择将 OpenClaw 降级。例如，如果你是通过 npm 安装的，可以使用以下命令将版本强制降至 2026.3.2：

参考 OpenClaw 的官方文档了解更多降级方式。

扣子罗盘中没有 Trace 数据

请按照以下步骤进行排查：

验证插件安装与执行情况

检查插件状态：运行 openclaw plugins list 命令，确认 openclaw-cozeloop-trace 插件的状态为 loaded。如果状态不是 loaded，说明插件安装或配置未成功，请你重新检查并执行相关步骤。

检查运行日志：

在插件配置中，将 debug 字段的值设置为 true。

重启 OpenClaw 网关，然后发起一次新的对话以生成日志。

执行以下命令，查看日志中是否包含关键信息：

tail -50 ~/.openclaw/logs/gateway.log | grep -i "CozeloopTrace"

日志文件的位置可能会有不同，例如 /tmp/openclaw/openclaw-2026-xx-xx.log。具体路径请参考 OpenClaw 的官方文档。

如果日志中没有 CozeloopTrace 关键字，说明插件配置有误，请你返回并仔细核对配置步骤。

验证凭证与权限

请确保配置文件中的 authorization（服务访问令牌）与 workspaceId 是正确且相互匹配的。

请确认你使用的访问令牌（服务访问令牌）已被授予向指定 workspaceId 所在的工作空间上报 Trace 数据的权限（ingestLoopTrace 权限）。

扣子罗盘中有 Trace 数据，但 Trace 数据缺失部分节点

如果你发现上报的 Trace 数据中缺少部分节点，例如 model 和 tool 等节点，并且该问题能够稳定复现，这通常是由于 OpenClaw 版本过低所致。

请参考以下命令升级版本：

ArkClaw 企业版