Integrate OpenClaw Applications

Method 1: One-click installation (Recommended)

On the machine running OpenClaw, open a terminal, paste the installation command from the previous step, and run it:

curl -fsSL https://arms-apm-cn-hangzhou-pre.oss-cn-hangzhou.aliyuncs.com/opentelemetry-instrumentation-openclaw/install.sh | bash -s -- \
  --endpoint "https://<YOUR_ENDPOINT>" \
  --x-arms-license-key "<YOUR_LICENSE_KEY>" \
  --x-arms-project "<YOUR_PROJECT>" \
  --x-cms-workspace "<YOUR_WORKSPACE>" \
  --serviceName "<YOUR_SERVICE_NAME>"

The installation script automatically performs the following actions:

1. Checks the environment for Node.js, npm, and the OpenClaw CLI.

2. Downloads and extracts the opentelemetry-instrumentation-openclaw plugin to the OpenClaw extensions directory.

3. Installs the runtime dependencies for the plugin.

4. Automatically locates the diagnostics-otel extension and installs its dependencies if they are not already installed.

5. Updates the openclaw.json file with configurations for both plugins. For OpenClaw v2026.4.25 and later, it also automatically adds hooks.allowConversationAccess: true.

6. Restarts the gateway to apply the new configuration.

The expected output is similar to the following:

[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!
════════════════════════════════════════════════════

Method 2: Manual installation

To perform a manual installation, follow these steps.

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

openclaw plugins enable diagnostics-otel

{
  "plugins": {
    "allow": ["opentelemetry-instrumentation-openclaw", "diagnostics-otel"],
    "load": {
      "paths": ["<PATH_TO_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
    }
  }
}

openclaw gateway restart

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://<YOUR_ENDPOINT>" \
  --x-arms-license-key "<YOUR_LICENSE_KEY>" \
  --x-arms-project "<YOUR_PROJECT>" \
  --x-cms-workspace "<YOUR_WORKSPACE>" \
  --serviceName "<YOUR_SERVICE_NAME>"

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

No data appears in the console after configuration?

Check the following items in order:

1. Confirm that your OpenClaw version is v26.2.19 or later. Run openclaw --version to verify.

2. Confirm that the gateway has restarted (it restarts automatically after a one-click installation, but requires you to run openclaw gateway restart for a manual installation). If the restart fails, you can run openclaw doctor and then restart the gateway after the issues are fixed.

3. Confirm that the Endpoint URL is correct and reachable over the network. Test connectivity with curl.

4. Confirm that all three header values (x-arms-license-key, x-arms-project, and x-cms-workspace) are correctly entered.

5. If the OpenClaw version is 2026.4.25 or later, set hooks.allowConversationAccess to true in the plugin configuration to prevent the security policy from blocking conversation-related hooks. If the version is earlier than 2026.4.25, ensure that the configuration does not contain the hooks field to avoid an "Unrecognized key" error.

6. Note that the default flushIntervalMs is 60 seconds. For short-lived tasks, wait a few minutes before data appears.

Does integration affect performance?

The impact is minimal. opentelemetry-instrumentation-openclaw uses the batch export mechanism of OpenTelemetry. Span data is buffered in memory and reported in batches at regular intervals, which does not block the normal processing flow of the agent.

Can I install trace reporting only?

Yes. You can add the --disable-metrics parameter during installation to skip the configuration of diagnostics-otel and enable only Trace reporting.

Will traces from different plugins conflict?

No. The installation script sets diagnostics.otel.traces to false by default. The opentelemetry-instrumentation-openclaw component is specifically responsible for reporting traces. No conflicts will occur even if both report simultaneously.

Will the installation overwrite existing configurations?

No. The installation script uses a merge-update strategy—it only updates necessary fields such as endpoint and headers, and leaves your existing configurations for traces, logs, and sampleRate unchanged.

Why is the token consumption always 0?

OpenClaw v2026.3.8 contains a bug that causes incorrect token consumption collection. This bug was fixed in v2026.4.5 and later versions.

Can I use gRPC to report data?

The diagnostics-otel plugin in OpenClaw supports only http/protobuf. If you set grpc, the setting is silently ignored. No error occurs, but the setting has no effect.