> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coze.cn/llms.txt
> Use this file to discover all available pages before exploring further.

本文引导你将 [OpenClaw](https://github.com/openclaw/openclaw) 执行过程的 Trace 数据上报至[扣子罗盘](https://loop.coze.cn/console)。Trace 数据被上报到扣子罗盘后，你可以利用扣子罗盘的分析与可视化能力，深入洞察 OpenClaw 的使用成本、性能与行为。
## 上报 OpenClaw 的 Trace 数据 {#9791eedf}
根据你部署 OpenClaw 的方式，上报 Trace 数据的方式有所不同：

* 如果你的 OpenClaw 是在 **2026 年 3 月 13 日** 或之后通过[扣子编程](https://docs.coze.cn/tutorial/openclaw)部署的，系统会自动将 OpenClaw 的 Trace 数据上报至扣子罗盘。在这种情况下，你无需安装 OpenClaw Trace 上报插件，可以直接参考[查看 Trace 数据](/cozeloop/openclaw_trace_report#c043bcd1)章节的指引，在扣子罗盘中查看 Trace 数据。
* 如果你的 OpenClaw 不是通过[扣子编程](https://docs.coze.cn/tutorial/openclaw)部署的或是在 **2026 年 3 月 13 日**之前通过[扣子编程](https://docs.coze.cn/tutorial/openclaw)部署的，你需要参考 [安装插件](/cozeloop/openclaw_trace_report#61a82f5f)章节的指引安装 OpenClaw Trace 上报插件。

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

1. 访问你的[扣子罗盘](https://loop.coze.cn/console)工作空间。
2. 在扣子罗盘的 **观测 > Trace** 页面，把上报类型设置为 SDK 上报，你应该能看到上报的 Trace 数据。
   ![Image=813x417](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/b1b9126372e64d7d92a8d994274fbc3c~tplv-goo7wpa0wc-image.image)
3. 点击任意一条 Trace 即可查看详细的 Span 调用链、属性和耗时信息。
   ![Image=800x452](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/b72b776d43924352bfd50fa3396088cc~tplv-goo7wpa0wc-image.image)

OpenClaw Trace 数据的结构如下所示（根据实际情况可能略有不同）：
```Plain Text
openclaw_request (root)
├── user_message（用户输入。由于 model 节点也包含此信息，该节点在后续版本中可能会被移除）
└── agent (从 before_agent_start 到 agent_end 的完整时间跨度)
    ├── model_provider/model_name (LLM 调用)
    ├── read (tool 调用)
    ├── write (tool 调用)
    └── ... (其他 tool)
```

## 通过插件上报 OpenClaw 的 Trace 数据 {#6ccb0e50}
如果你的 OpenClaw 不是通过[扣子编程](https://docs.coze.cn/tutorial/openclaw)部署的，你可以通过扣子罗盘提供的插件来实现 OpenClaw 的 Trace 数据上报。
### 安装插件 {#61a82f5f}
[扣子罗盘](https://loop.coze.cn/console)提供了 OpenClaw Trace 上报插件。你只需要安装该插件就能实现 OpenClaw 的 Trace 数据上报。
#### 准备工作 {#eabb611f}
在开始之前，请确保你已完成以下准备工作：

* 获取了扣子罗盘空间 ID 和服务访问令牌。
   * **扣子罗盘空间 ID**：切换到目标空间，点击其右侧的复制按钮获取空间 ID。详细获取方式参考 [获取扣子罗盘空间 ID](https://loop.coze.cn/open/docs/cozeloop/get_workspace_id_and_token#01dede13)。 
      ![Image=365x166](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/51d0c7d4f20c40db8426ce9afe7c80ee~tplv-goo7wpa0wc-image.image)
   * **服务访问令牌**：获取方式参考 [配置服务访问令牌](https://loop.coze.cn/open/docs/cozeloop/authentication-for-sdk#83f924a1)。
* 有一个已安装并可正常运行的 OpenClaw 实例。参考 OpenClaw 的[官方文档](https://docs.openclaw.ai/install)了解如何安装和启动 OpenClaw。

#### 步骤一：安装插件 {#53ebcc51}
运行以下命令安装插件。
```Shell
npx @cozeloop/openclaw-cozeloop-trace-onboard-cli@latest install
```

你需要按照命令行提示分别输入服务访问令牌和扣子罗盘空间 ID。
![Image=791x99](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/b03f14502b0442f4bbe4619f3d5952bb~tplv-goo7wpa0wc-image.image)
#### 步骤二：验证插件 {#b9285a7f}
你可通过以下命令查看插件状态，如果 `Openclaw Cozeloop Trace` 的状态为 `loaded`，则说明插件加载成功。此时，所有与 OpenClaw 对话的 Trace 就可以被上报到扣子罗盘。
```Shell
openclaw plugins list
```

![Image=677x44](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/5d2c0cbc3a024328a1c57f8a652883c0~tplv-goo7wpa0wc-image.image)
### 管理插件 {#43b57644}
#### 升级或重装插件 {#29f70a72}
要升级或重装插件，你可以直接重新执行 [步骤一：安装插件](/cozeloop/openclaw_trace_report#53ebcc51)。
如果在执行过程中遇到关于“插件不存在”的报错，可以尝试运行 `openclaw doctor --fix` 命令进行修复。
#### 更新插件配置 {#6e998931}
你安装插件时，OpenClaw 配置文件（`~/.openclaw/openclaw.json`）中的 `plugins.allow` 和 `plugins.entries` 字段会被自动更新。因此，一般情况下你无需手动修改 OpenClaw 配置文件。
```JSON
{
...
  "plugins": {
    "allow": [
      ...
      "openclaw-cozeloop-trace",
      ...
    ],
    "entries": {
      ...
      "openclaw-cozeloop-trace": { 
        "enabled": true,
        "config": {
          "authorization": "Bearer sat_iH*************A", 
          "endpoint": "https://api.coze.cn/v1/loop/opentelemetry",
          "workspaceId": "74*****"
        }
      }
    },
      ...
  }
...  
}
```

如果你需要手动修改 OpenClaw 配置文件中的插件配置，可参考以下配置项说明。
<!-- @cols-width: 335,100,416,344 -->
| | | | | \
|**配置项** |**是否必选** |**说明** |**示例值** |
|---|---|---|---|
| | | | | \
|`openclaw-cozeloop-trace.config.authorization` |必选 |扣子罗盘的服务访问令牌。获取方式参考 [配置服务访问令牌](https://loop.coze.cn/open/docs/cozeloop/authentication-for-sdk#83f924a1)。 |`"Bearer {sat_iH*************A}"` |
| | | | | \
|`openclaw-cozeloop-trace.config.workspaceId` |必选 |扣子罗盘空间 ID。详细获取方式参考 [获取扣子罗盘空间 ID](https://loop.coze.cn/open/docs/cozeloop/get_workspace_id_and_token#01dede13)。  |`"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 数据的 Metadata 中注入自定义 Tag（可选） {#6fdcc12d}
如果你需要将来自多个来源的 Trace 数据上报到同一个扣子罗盘空间，可以添加自定义 Tag 来区分它们。这些 Tag 会作为 Metadata 注入到该来源的所有 Span 中，方便你进行筛选和查找。为防止与系统保留字段发生冲突，扣子罗盘会自动为所有自定义 Tag 的键（key）添加 `udf_` 前缀。
:::notice 注意
自定义 Tag 注入功能要求插件版本为 0.1.12 或更高版本。
:::
要添加自定义 Tag，你需要设置 `COZELOOP_UDF_TAGS` 环境变量。请使用英文逗号分隔多个键值对，格式为 `key1=v1,key2=v2,key3=v3`。
你可以选择以下任意一种方式加载 `COZELOOP_UDF_TAGS` 环境变量：

* 在 `~/.openclaw/.env` 文件中添加一行：`COZELOOP_UDF_TAGS=key1=v1,key2=v2,key3=v3`
* 将 `COZELOOP_UDF_TAGS` 添加为 OpenClaw 实例所在操作系统的环境变量。

## 应用场景 {#18ae1db0}
将 OpenClaw 的 Trace 数据上报至扣子罗盘后，你可以利用这些数据实现以下应用场景。
### 场景一：统计 Token 消耗 {#4e3b5eb2}
你可以在扣子罗盘中查看 OpenClaw 使用不同模型所产生的 Token 消耗。

1. 访问你的[扣子罗盘](https://loop.coze.cn/console)工作空间。
2. 在扣子罗盘的 **观测 > 统计** 页面，选择上报类型为 **SDK 上报**，然后把模型设置为 OpenClaw 所使用的模型。
   ![Image=1280x644](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/52e842cc3125405b900952c53963161e~tplv-goo7wpa0wc-image.image)

### 场景二：排查问题 {#1f2bfc32}
扣子罗盘的 Trace 数据采用逐步上报机制：已完成的节点会先上报，根节点（Root Span）最后上报。这让你可以根据已完成的节点，实时跟进请求的执行情况，从而高效排查问题。
:::tip 说明
在排查问题时，建议你切换到 **All Span** 视图，以查看请求的最新执行状态。
:::
例如，当你向 OpenClaw 发出“帮我查看桌面上的一个文件”的指令后，若它陷入不断重复 `read` 操作的循环中，你可以立即在 Trace 视图中观察到这一行为。
<div style="text-align: center"><img src="https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/aa30777abc014e9cbddcf985b4331965~tplv-goo7wpa0wc-image.image" width="3010px" height="934px" /></div>

此时，点击该请求的任意 Span，即可查看其详细的执行 Trace，帮助你快速定位问题并采取相应措施（如重启 OpenClaw）。
![Image=522x245](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/1c221e70986f47ca8938325793e0c712~tplv-goo7wpa0wc-image.image)
## 常见问题 {#8f308092}
### 新版 OpenClaw 不上报 Token 用量 {#0036d1e2}
自 openclaw 2026.3.7 版本起，其 `usage` 数据的处理方式发生了变化，且官方未再提供相关的控制选项。
我们正在关注官方进展并探索新的上报方法。在此期间，你可以暂时选择将 OpenClaw 降级。例如，如果你是通过 npm 安装的，可以使用以下命令将版本强制降至 2026.3.2：
```Shell
npm install -g openclaw@2026.3.2 --force
```

参考 OpenClaw 的[官方文档](https://docs.openclaw.ai/install)了解更多降级方式。
### 扣子罗盘中没有 Trace 数据 {#2fb59325}
请按照以下步骤进行排查：

1. **验证插件安装与执行情况**
   * **检查插件状态**：运行 `openclaw plugins list` 命令，确认 `openclaw-cozeloop-trace` 插件的状态为 `loaded`。如果状态不是 `loaded`，说明插件安装或配置未成功，请你重新检查并执行相关步骤。
   * **检查运行日志**：
      1. 在插件配置中，将 `debug` 字段的值设置为 `true`。
      2. 重启 OpenClaw 网关，然后发起一次新的对话以生成日志。
      3. 执行以下命令，查看日志中是否包含关键信息：
      ```Shell
      tail -50 ~/.openclaw/logs/gateway.log | grep -i "CozeloopTrace"
      ```

      日志文件的位置可能会有不同，例如 `/tmp/openclaw/openclaw-2026-xx-xx.log`。具体路径请参考 OpenClaw 的[官方文档](https://docs.openclaw.ai/install)。
      4. 如果日志中没有 `CozeloopTrace` 关键字，说明插件配置有误，请你返回并仔细核对配置步骤。
2. **验证凭证与权限**
   * 请确保配置文件中的 `authorization`（服务访问令牌）与 `workspaceId` 是正确且相互匹配的。
   * 请确认你使用的访问令牌（服务访问令牌）已被授予向指定 `workspaceId` 所在的工作空间上报 Trace 数据的权限（ingestLoopTrace 权限）。

### 无法正常访问扣子罗盘 {#9da97ed0}
如果你的服务器需要通过 HTTP 代理访问网络，请将扣子罗盘的 API 域名添加到代理的白名单中，以避免连接失败。
如果你未在插件中配置 `endpoint` 参数，默认的上报域名为 `https://api.coze.cn`。
### 扣子罗盘中有 Trace 数据，但 Trace 数据缺失部分节点 {#a4131eef}
如果你发现上报的 Trace 数据中缺少部分节点，例如 `model` 和 `tool` 等节点，并且该问题能够稳定复现，这通常是由于 OpenClaw 版本过低所致。
![Image=299x112](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/90875d7fde1443c39735859fa6e5ce49~tplv-goo7wpa0wc-image.image)
请参考以下命令升级版本：
```Shell
sudo su         # 以 root 权限去执行 su 命令
su openclaw     # 切换到openclaw用户
openclaw update # 升级版本

openclaw --version # 升级后，查看版本
```