接入 OpenClaw 應用 - Cloud Monitor

OpenClaw 可通過 opentelemetry-instrumentation-openclaw 和 diagnostics-otel 兩個外掛程式協同工作，將 AI Agent 的完整調用鏈路（Trace）和運行指標（Metrics）上報至CloudMonitor 2.0 應用監控。opentelemetry-instrumentation-openclaw 負責 Trace 上報，遵循 OpenTelemetry GenAI 語義規範，為每一次請求產生結構化的調用鏈路；diagnostics-otel 負責 Metrics 上報，即時採集 Token 消耗速率、調用 QPS、隊列深度等運行指標。啟用後，您可以在CloudMonitor 2.0 中查看 OpenClaw 的完整調用鏈路、模型調用耗時、Token 消耗明細、工具調用詳情等監控資料。

使用限制

限制項	說明
OpenClaw 版本	v26.2.19 及以上。低於此版本不包含 `diagnostics-otel` 外掛程式，請先升級。
上報協議	僅支援 HTTP/Protobuf，暫不支援 HTTP/JSON 和 gRPC。
資料類型	當前僅支援接收 Trace 和 Metric 資料，暫不支援 Log 資料。
CloudMonitor服務	已開通CloudMonitor 2.0 服務，並建立了工作空間。

步驟一：擷取接入命令

在安裝外掛程式之前，您需要先從CloudMonitor 2.0 控制台擷取接入命令。

登入CloudMonitor 2.0 控制台，選擇目標工作空間。
在左側導覽列單擊接入中心。
在AI 應用可觀測地區單擊 OpenClaw 卡片。

在參數配置地區輸入應用程式名稱，根據需求選擇串連方式，然後單擊 LicenseKey 右側的點擊擷取。

頁面下方將根據配置參數產生相應的接入命令，單擊右上方可一鍵複製。命令中包含 Endpoint、LicenseKey 等存取點資訊，如需手動安裝請記錄：

參數	說明	樣本
Endpoint	OTLP Trace/Metric 資料上報地址	`https://proj-xtrace-xxx.cn-hangzhou-intranet.log.aliyuncs.com/apm/trace/opentelemetry/v1/traces` `https://proj-xtrace-xxx.cn-hangzhou-intranet.log.aliyuncs.com/apm/trace/opentelemetry/v1/metrics`
x-arms-license-key	資料寫入鑒權的 LicenseKey	`d95vgxi0cn@xxxxx`
x-arms-project	Log Service專案名稱	`proj-xtrace-xxx-cn-hangzhou`
x-cms-workspace	CloudMonitor 2.0 工作空間標識	`default-cms-xxx-cn-hangzhou`
serviceName	應用程式名稱	openclaw-xxx

步驟二：安裝接入

方式一：一鍵安裝（推薦）

開啟 OpenClaw 所在機器的終端，粘貼上一步複製的安裝命令然後執行：

curl -fsSL https://arms-apm-cn-hangzhou-pre.oss-cn-hangzhou.aliyuncs.com/opentelemetry-instrumentation-openclaw/install.sh | bash -s -- \
  --endpoint "https://你的Endpoint地址" \
  --x-arms-license-key "你的License-Key" \
  --x-arms-project "你的Project" \
  --x-cms-workspace "你的Workspace" \
  --serviceName "你的服務名"

安裝指令碼將自動完成以下操作：

檢查環境（Node.js、npm、OpenClaw CLI）。
下載並解壓 opentelemetry-instrumentation-openclaw 到 OpenClaw 擴充目錄。
安裝外掛程式的運行時依賴。
自動定位 diagnostics-otel 擴充，如果未安裝依賴會自動安裝。
更新 openclaw.json 配置（兩個外掛程式的配置一次寫完；OpenClaw版本 >= 2026.4.25 時自動寫入 hooks.allowConversationAccess: true）。
重啟網關使配置生效。

預期輸出類似如下內容：

[INFO]  Checking prerequisites...
[OK]    Node.js v24.14.0
[OK]    npm 11.9.0
[OK]    OpenClaw CLI found
[INFO]  Downloading plugin...
[OK]    Downloaded
[INFO]  Extracting...
[OK]    Extracted
[INFO]  Installing npm dependencies...
[OK]    Dependencies installed
[INFO]  Locating diagnostics-otel extension...
[OK]    Found diagnostics-otel at: /home/.../extensions/diagnostics-otel
[OK]    diagnostics-otel dependencies already present
[INFO]  Updating config...
[OK]    Config updated
[INFO]  Restarting OpenClaw gateway...
[OK]    Gateway restarted
════════════════════════════════════════════════════
  ✅ opentelemetry-instrumentation-openclaw installed successfully!
════════════════════════════════════════════════════

安裝參數

參數	必填	說明
`--endpoint`	是	OTLP 資料上報地址，從CloudMonitor 2.0 接入中心擷取
`--x-arms-license-key`	是	資料寫入鑒權的 LicenseKey
`--x-arms-project`	是	Log Service專案名稱
`--x-cms-workspace`	是	CloudMonitor 2.0 工作空間標識
`--serviceName`	是	上報的服務名稱，將作為應用程式名稱顯示在CloudMonitor 2.0 的應用列表中
`--plugin-url`	否	自訂 tarball 下載地址
`--install-dir`	否	自訂安裝目錄
`--disable-metrics`	否	跳過 diagnostics-otel 配置，僅啟用 Trace 上報，不啟用 Metrics

方式二：手動安裝

如需手動安裝，請按照以下步驟操作。

1. 下載並解壓外掛程式

curl -fsSL -o opentelemetry-instrumentation-openclaw.tar.gz https://arms-apm-cn-hangzhou-pre.oss-cn-hangzhou.aliyuncs.com/opentelemetry-instrumentation-openclaw/opentelemetry-instrumentation-openclaw.tar.gz
tar -xzf opentelemetry-instrumentation-openclaw.tar.gz
cd opentelemetry-instrumentation-openclaw
npm install --omit=dev

2. 啟用 diagnostics-otel 外掛程式

openclaw plugins enable diagnostics-otel

3. 編輯設定檔

編輯 ~/.openclaw/openclaw.json，寫入以下配置（將步驟一存取點資訊替換到以下配置中）：

{
  "plugins": {
    "allow": ["opentelemetry-instrumentation-openclaw", "diagnostics-otel"],
    "load": {
      "paths": ["<opentelemetry-instrumentation-openclaw 的安裝路徑>"]
    },
    "entries": {
      "opentelemetry-instrumentation-openclaw": {
        "enabled": true,
        "hooks": {
          "allowConversationAccess": true
        },
        "config": {
          "endpoint": "<Endpoint>",
          "headers": {
            "x-arms-license-key": "<YOUR-LICENSE-KEY>",
            "x-arms-project": "<YOUR-ARMS-PROJECT>",
            "x-cms-workspace": "<YOUR-WORKSPACE-ID>"
          },
          "serviceName": "<YOUR-SERVICE-NAME>"
        }
      },
      "diagnostics-otel": {
        "enabled": true
      }
    }
  },
  "diagnostics": {
    "enabled": true,
    "otel": {
      "enabled": true,
      "endpoint": "<Endpoint>",
      "protocol": "http/protobuf",
      "headers": {
        "x-arms-license-key": "<YOUR-LICENSE-KEY>",
        "x-arms-project": "<YOUR-ARMS-PROJECT>",
        "x-cms-workspace": "<YOUR-WORKSPACE-ID>"
      },
      "serviceName": "<YOUR-SERVICE-NAME>",
      "traces": false,
      "metrics": true,
      "logs": false
    }
  }
}

版本相容：hooks.allowConversationAccess 僅 OpenClaw版本 >= 2026.4.25 支援。低於此版本請刪除 hooks 段，否則網關啟動會報 "Unrecognized key" 錯誤。

4. 重啟網關

openclaw gateway restart

方式三：容器環境下接入

請你首先選擇OpenClaw基礎鏡像（如果您已經基於官方的基礎鏡像構建了自己的基礎鏡像，可以直接使用您自己構建的OpenClaw基礎鏡像），之後在基礎鏡像的基礎上，安裝OpenClaw可觀測相關外掛程式，之後重新構建您自己的OpenClaw鏡像，如下所示：

FROM ghcr.io/openclaw/openclaw:latest
RUN curl -fsSL https://arms-apm-cn-hangzhou-pre.oss-cn-hangzhou.aliyuncs.com/opentelemetry-instrumentation-openclaw/install.sh | bash -s -- \
  --endpoint "https://你的Endpoint地址" \
  --x-arms-license-key "你的License-Key" \
  --x-arms-project "你的Project" \
  --x-cms-workspace "你的Workspace" \
  --serviceName "你的服務名"

安裝指令碼與方式一種一鍵安裝的指令碼一致。

之後基於此Dockerfile構建您自己的OpenClaw鏡像，並用這個鏡像來作為容器環境下的運行鏡像。

如果您需要可以動態配置OpenClaw執行個體的上報端點，上報應用程式名稱等資訊，可以按照如下方式構建OpenClaw鏡像：

FROM ghcr.io/openclaw/openclaw:latest
RUN curl -fsSL https://arms-apm-cn-hangzhou-pre.oss-cn-hangzhou.aliyuncs.com/opentelemetry-instrumentation-openclaw/install-ack.sh | bash -s

之後在運行鏡像時，配置如下環境變數以指定上報端點，應用程式名稱等資訊：

環境變數名	描述
`ARMS_OTLP_ENDPOINT`	你的Endpoint地址
`ARMS_LICENSE_KEY`	你的License-Key
`ARMS_PROJECT`	你的Project
`ARMS_CMS_WORKSPACE`	你的Workspace
`ARMS_SERVICE_NAME`	你的服務名

配置參數說明

opentelemetry-instrumentation-openclaw 配置

參數	類型	必填	說明
`endpoint`	String	是	OTLP 資料上報地址，從CloudMonitor 2.0 接入中心擷取。
`headers.x-arms-license-key`	String	是	資料寫入鑒權的 LicenseKey，用於身份認證。
`headers.x-arms-project`	String	是	專案標識，指鏈路資料歸屬的Log Service專案名稱。
`headers.x-cms-workspace`	String	是	CloudMonitor 2.0 工作空間標識，指定資料上報的目標工作空間。
`serviceName`	String	是	上報的服務名稱，將作為應用程式名稱顯示在CloudMonitor 2.0 的應用列表中。
`debug`	Boolean	否	啟用調試日誌，預設 `false`。
`batchSize`	Number	否	Span 緩衝區大小，達到後批量發送，預設 `10`。
`flushIntervalMs`	Number	否	最大緩衝等待時間（毫秒），預設 `5000`。
`enableTracePropagation`	Boolean	否	啟用 W3C Trace Context 傳播，關聯上下遊鏈路，預設 `false`。
`propagationTargetUrls`	String[]	否	向匹配的下遊 URL 注入 `traceparent` 頭（URL 子串匹配）。
`resourceAttributes`	Object	否	自訂 Resource 屬性，注入到 OTel Resource（如 `{"deployment.environment": "production"}`）。
`globalSpanAttributes`	Object	否	全域 Span 屬性，注入到所有 span（如 `{"biz.team": "payment"}`）。

說明：hooks.allowConversationAccess: true 必須配置在外掛程式 entries 的 hooks 欄位中（與 config 平級），否則對話類 hooks 將被 OpenClaw 安全性原則攔截。僅 OpenClaw版本 >= 2026.4.25 支援此欄位，低版本請勿配置。

環境變數降級

當設定檔中未設定對應欄位時，外掛程式自動從環境變數讀取（適用於容器/K8s 部署情境）：

環境變數	對應配置	說明
`ARMS_OTLP_ENDPOINT`	`endpoint`	OTLP 上報地址
`ARMS_LICENSE_KEY`	`headers.x-arms-license-key`	ARMS LicenseKey
`ARMS_PROJECT`	`headers.x-arms-project`	ARMS 專案名
`ARMS_CMS_WORKSPACE`	`headers.x-cms-workspace`	工作空間標識
`ARMS_SERVICE_NAME` / `OTEL_SERVICE_NAME`	`serviceName`	服務名
`ARMS_TRACE_DEBUG`	`debug`	調試日誌（`true` / `1`）
`OTEL_RESOURCE_ATTRIBUTES`	`resourceAttributes`	自訂 Resource 屬性（`key1=value1,key2=value2`）
`OTEL_SPAN_ATTRIBUTES`	`globalSpanAttributes`	全域 Span 屬性（`key1=value1,key2=value2`）

優先順序：設定檔 > 環境變數 > 預設值。

注意：OpenClaw gateway 預設以 daemon 模式運行，不繼承調用 shell 的環境變數。本地開發請使用設定檔方式；環境變數適用於 Docker/K8s 等容器環境。

diagnostics-otel 配置

參數	類型	必填	說明
`enabled`	Boolean	是	是否啟用 diagnostics 診斷功能。設定為 `true` 開啟。
`otel.enabled`	Boolean	是	是否啟用 OpenTelemetry 資料匯出。設定為 `true` 開啟。
`otel.endpoint`	String	是	OTLP 資料上報地址。外掛程式會自動追加 `/v1/traces` 或 `/v1/metrics` 路徑。
`otel.protocol`	String	是	上報協議。當前僅支援 `http/protobuf`。
`otel.headers`	Object	是	上報請求攜帶的認證頭資訊。
`otel.serviceName`	String	是	上報的服務名稱，建議與 `opentelemetry-instrumentation-openclaw` 配置的 `serviceName` 保持一致。
`otel.traces`	Boolean	是	是否上報 Trace 資料。建議設為 `false`，Trace 由 `opentelemetry-instrumentation-openclaw` 負責。
`otel.metrics`	Boolean	是	是否上報 Metric 資料。設為 `true` 可查看 Token 用量、調用次數、耗時等指標。
`otel.logs`	Boolean	是	是否上報 Log 資料。CloudMonitor 2.0 暫不支援，建議設為 `false`。
`otel.sampleRate`	Number	否	Trace 採樣率，取值 0.0 ~ 1.0，僅對根 Span 生效。`1` 表示全量採集。
`otel.flushIntervalMs`	Number	否	資料批量重新整理間隔，單位毫秒，最小值 `1000`，預設 `60000`。

步驟三：驗證安裝

執行以下命令檢查外掛程式是否生效：

openclaw plugins list

預期輸出類似如下內容：

┌───────────────────┬─────────────────┬──────────┬──────────┬────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┬────────────┐
│ Name              │ ID              │ Format   │ Status   │ Source                                                                                                                                                                     │ Version    │
├───────────────────┼─────────────────┼──────────┼──────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼────────────┤
│ OpenClaw OTel     │ opentelemetry-  │ openclaw │ enabled  │ ~/.openclaw/extensions/opentelemetry-instrumentation-openclaw/dist/index.js                                                                                                │ 0.1.3-beta │
│ Plugin            │ instrumentation │          │          │ Report OpenClaw AI agent execution traces to any OTLP-compatible backend via OpenTelemetry                                                                                 │            │
│ @openclaw/        │ diagnostics-    │ openclaw │ enabled  │ ~/.openclaw/npm/node_modules/@openclaw/diagnostics-otel/dist/index.js                                                                                                      │ 2026.5.6   │
│ diagnostics-otel  │ otel            │          │          │                                                                                                                                                                            │            │
└───────────────────┴─────────────────┴──────────┴──────────┴────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┴────────────┘

步驟四：查看監控資料

安裝完成後，向 OpenClaw 發送幾條訊息，觸發 Agent 執行。之後您可以在CloudMonitor 2.0 控制台查看 OpenClaw 上報的監控資料。

登入CloudMonitor 2.0 控制台，選擇目標工作空間。
在左側導覽列選擇應用可觀測 > AI 應用可觀測。
在應用列表中找到您配置的服務名稱（如 openclaw-gateway）。
單擊應用程式名稱或選擇調用鏈分析查看調用鏈路、Token 消耗、LLM 輸入輸出和耗時分布。

卸載

如需卸載外掛程式，執行以下命令：

curl -fsSL https://arms-apm-cn-hangzhou-pre.oss-cn-hangzhou.aliyuncs.com/opentelemetry-instrumentation-openclaw/uninstall.sh | bash

卸載指令碼將自動清理 opentelemetry-instrumentation-openclaw 的安裝目錄和 openclaw.json 中的所有相關配置，包括 diagnostics-otel 的配置也會一併禁用。

參數	說明
`-y` / `--yes`	跳過確認提示。
`--install-dir`	指定外掛程式安裝目錄（不傳則自動探測）。
`--keep-metrics`	僅卸載 `opentelemetry-instrumentation-openclaw`（Trace），保留 `diagnostics-otel`（Metrics）的配置。

常見問題

配置完成後控制台看不到資料？

請依次排查：

確認 OpenClaw 版本 ≥ v26.2.19（執行 openclaw --version 檢查）。
確認網關已重啟（一鍵安裝會自動重啟，手動安裝需執行 openclaw gateway restart）。如果重啟失敗，可執行openclaw doctor，完成修複後再重啟網關。
確認 Endpoint 地址正確，且網路可達（可通過 curl 測試連通性）。
確認三個 Header 值（x-arms-license-key、x-arms-project、x-cms-workspace）均已正確填寫。
如果 OpenClaw 版本 >= 2026.4.25，確認外掛程式配置中 hooks.allowConversationAccess 設為 true（缺失會導致對話類 hooks 被安全性原則攔截）；如果版本低於 2026.4.25，確認配置中沒有 hooks 欄位（否則會報 "Unrecognized key" 錯誤）。
注意 flushIntervalMs 預設為 60 秒，短時任務可能需要等待一段時間才能看到資料。

接入會影響 OpenClaw 的效能嗎？

影響極小。opentelemetry-instrumentation-openclaw 使用 OpenTelemetry 的大量匯出機制，Span 資料在記憶體中緩衝、定時批量上報，不會阻塞 Agent 的正常處理流程。

可以只裝 Trace 不裝 Metrics 嗎？

可以。安裝時加 --disable-metrics 參數即可跳過 diagnostics-otel 的配置，僅啟用 Trace 上報。

diagnostics-otel 的 Trace 和 opentelemetry-instrumentation-openclaw 的 Trace 會衝突嗎？

不會。安裝指令碼預設將 diagnostics.otel.traces 設為 false，由 opentelemetry-instrumentation-openclaw 專門負責 Trace 上報。兩者同時上報也不會有衝突。

已經配置過 diagnostics-otel 了，安裝會覆蓋我的配置嗎？

不會。安裝指令碼採用合并更新策略——只更新 endpoint、headers 等必要欄位，保留您已有的 traces、logs、sampleRate 等配置不變。

為什麼 Token 消耗一直是 0？

OpenClaw 從 v2026.3.8 版本開始引入了一個 BUG，會導致 Token 消耗採集有誤，已在 v2026.4.5 版本後修複。

可以使用 gRPC 協議上報嗎？

當前 OpenClaw 的 diagnostics-otel 外掛程式僅支援 http/protobuf 協議，設定 grpc 會被靜默忽略，不會有報錯但也不會生效。