openclaw-telemetry

Call-home telemetry reporter for OpenClaw AI workers. Installs globally, asks where home is once, then runs a background job that phones in one imprint every 10 minutes: status, model, token usage, errors, browser health, and host health.

Install and run

npm install -g openclaw-telemetry
openclaw-telemetry

First run asks three questions:

Telemetry URL [https://8examples.com/openclaw/telemetry]:
Access key (oct_...): <token from your 8Examples admin>
Claw name (e.g. openclaw1): openclaw1

then starts the background job. Config is saved to ~/.openclaw-telemetry/config.json (mode 600), so subsequent runs start straight away.

openclaw-telemetry once     # send a single imprint now
openclaw-telemetry status   # daemon state + last sends
openclaw-telemetry stop     # stop the background job
openclaw-telemetry setup    # change URL / key / claw name

Admins issue access keys from the Fleet tab at 8examples.com/account.

Zero-prompt installs

Set the environment instead and no config file or prompt is needed — this is how managed OpenClaw containers run it by default:

OPENCLAW_TELEMETRY_TOKEN=oct_...        # required
OPENCLAW_TELEMETRY_CLAW=openclaw1       # or CLAW_USERNAME
OPENCLAW_TELEMETRY_URL=https://8examples.com/openclaw/telemetry   # optional, this is the default

Environment variables beat the config file key by key.

What it sends

POST <url> with Authorization: Bearer <key>:

{
  "claws": [
    {
      "claw": "openclaw1",
      "at": "2026-08-13T12:00:00.000Z",
      "status": "ok",
      "model": "claude-fable-5",
      "tokens": { "input": 12000, "output": 3400 },
      "errors": [],
      "note": "free text",
      "host": {
        "hostname": "openclaw-vm",
        "platform": "linux 6.8.0",
        "arch": "x64",
        "uptimeHours": 12.5,
        "load": [0.1, 0.2, 0.15],
        "memFreeMB": 2048,
        "memTotalMB": 8192
      },
      "browser": { "ok": true, "bin": "chromium", "url": "https://example.com/", "ms": 850 },
      "portmap": { "ok": true, "url": "https://openclaw1.fusenv.com", "status": 200, "ms": 120 },
      "agent": { "name": "openclaw-telemetry", "version": "0.4.0", "latest": "0.4.0", "upToDate": true }
    }
  ]
}

Letting the claw speak for itself

The reporter merges ~/.openclaw-telemetry/status.json into every imprint, so the worker (or anything else on the machine) can keep it current:

{
  "status": "ok",
  "model": "claude-fable-5",
  "tokens": { "input": 12000, "output": 3400 },
  "errors": [],
  "note": "processed 14 bookings today",
  "extra": { "queueDepth": 0 }
}

status may be ok, warn, or error; it drives the color of the claw's tile on the fleet dashboard.

Browser health check

Every imprint also exercises the machine's web browser: the reporter uses OpenClaw's configured browser path first, then searches PATH and Playwright's shared browser cache for Chromium, Chrome, Brave, or Edge, headless-loads a page that should always work — https://example.com/ by default — and verifies HTML comes back within 30 seconds. The result is reported as the browser field above; a failure (no binary, launch error, timeout, or an empty page) also appends a browser: ... line to errors, which turns the claw's tile amber unless the claw has set its own status.

OPENCLAW_TELEMETRY_BROWSER=off                  # disable the check
OPENCLAW_TELEMETRY_BROWSER=/usr/bin/chromium    # or force a specific binary
OPENCLAW_TELEMETRY_BROWSER_URL=https://...      # load this page instead

Run openclaw-telemetry browser-check to print the discovery/launch result without sending an imprint.

Portmap check

Each claw instance is expected to be reachable at its own subdomain — <claw>.fusenv.com — for inbound webhooks (e.g. phone-gateway pings). Every imprint verifies that mapping actually routes: the reporter requests https://<claw>.fusenv.com and treats any HTTP answer except 404 as mapped (tunnel and wildcard-DNS catch-alls answer 404; a real claw gateway answers 200/401/…). No response at all (NXDOMAIN, timeout, TLS failure) also fails the check. The result is reported as the portmap field; a failure appends a portmap: ... line to errors, turning the tile amber until the tunnel ingress + DNS record exist.

OPENCLAW_TELEMETRY_PORTMAP=off                     # disable the check
OPENCLAW_TELEMETRY_PORTMAP=claw7.example.com       # check this hostname instead
OPENCLAW_TELEMETRY_PORTMAP_DOMAIN=example.com      # keep <claw>. but change the domain

Run openclaw-telemetry portmap-check to print the result without sending an imprint.

Version reporting

agent.version in each imprint is the version actually running on the claw. The reporter also asks the npm registry for the latest published openclaw-telemetry and adds agent.latest and agent.upToDate, so the fleet dashboard can show at a glance which claws still run an old release. If the registry cannot be reached, the two fields are simply omitted — a flaky npm is not a claw problem.

OPENCLAW_TELEMETRY_REGISTRY=off                            # skip the lookup
OPENCLAW_TELEMETRY_REGISTRY=https://registry.example.com   # private mirror

Run openclaw-telemetry version-check to print { "running": ..., "latest": ..., "upToDate": ... } without sending an imprint.

Surviving reboots

The daemon does not install itself as a system service. Add one line to cron if you want it back after a reboot:

@reboot /usr/bin/env openclaw-telemetry start

License

MIT