OpenClaw telemetry
This service answers the daily update check that OpenClaw installs make. Everything it does is in this repository.
What an install sends
With automatic update checks enabled, a successful version check is reused for 24 hours. The request carries a User-Agent:
openclaw/2026.8.2 (darwin; node/v26.0.1; arm64; gateway)
Anonymous feature statistics are off by default. Operators can enable them during interactive setup, with openclaw telemetry on, or with telemetry.enabled: true. When enabled, the same request carries a small body of feature facts:
{
"schema": 1,
"version": "2026.8.2",
"platform": "darwin-arm64",
"node": "26.0.1",
"surface": "gateway",
"features": {
"channels": ["telegram", "discord"],
"providerFamilies": ["anthropic", "openai"],
"plugins": ["codex", "diagnostics-otel"],
"pluginsEnabled": 7,
"sessionsLast24h": 14
}
}
Interactive setup defaults to No thanks; guided Quick Start skips the question. Scripted installs do not opt in automatically. The enabled setting controls inclusion, not whether a prompt was answered.
Channels and providers describe configuration; plugins describe enabled inventory, not invocations. sessionsLast24h counts retained session-creation events timestamped in the preceding 24 hours, not active sessions or messages. Missing or unreadable local state produces zero.
Aggregate-only installation counts
Ordinary daily update requests send no count header. When its optional D1 binding is configured, a successful 200 update answer advertises OpenClaw-Installation-Count: 1;<server UTC ordinal day> with Cache-Control: no-store. A companion client can claim that server day per endpoint/state root and send one separate empty POST using User-Agent: openclaw-installation-count/1 and OpenClaw-Installation-Count: 1;<server day>;<gap 1–31>. This adds at most one count-only POST per existing uncached successful 24-hour update check, never another update check or a retry. Old/unconfigured receivers get no count claim or metadata. Explicit telemetry off and DO_NOT_TRACK suppress this count POST. Count-only requests never enter raw analytics or geography processing, even when malformed. Only an aggregate D1 histogram (day, gap, reports) is stored: no identifiers, request-level rows or dimensions. It measures observed reporting installation-state roots, not people or engagement. HEAD and update outcomes neither advertise nor increment it. Count failures never discard a valid version answer. The optional production binding and cleanup trigger are absent; separately authorized rollout must configure and monitor 90-day cleanup and review provider recovery retention before collection. See the count contract and private aggregate SQL.
Update outcomes
The receiver also supports identifier-free terminal update outcomes from a companion client implementation. These use a separate dataset, strict public version labels and bounded outcome categories, with no geography, install IDs, raw errors or logs. Uploads are limited to 4096 bytes. Reports are retained for three months; no public individual-report route is provided. The companion client reports outcomes on by default, like the existing update ping, under update-request policy rather than optional feature-statistics consent. update.checkOnStart: false, OPENCLAW_NO_AUTO_UPDATE=1, and Nix mode suppress outcomes; a truthy CI always suppresses outcomes, even when a replacement OPENCLAW_TELEMETRY_ENDPOINT is configured. DO_NOT_TRACK controls feature statistics, not update outcomes. Receiver support does not itself enable client reporting: deploy and verify the receiver and separate dataset before releasing the default-on client, under separately authorized rollout. See the outcome contract and collection boundaries.
Approximate location
Cloudflare provides approximate location: country, region code, city, and timezone. We store no raw IP addresses or precise coordinates in analytics.
Recorded update checks include these fields even when anonymous feature statistics are off or DO_NOT_TRACK is set. Missing or invalid fields stay empty. Records are retained for three months.
What we exclude from Analytics Engine
- Message content, prompts, model output, file contents, or file paths
- Credentials, tokens, or secret references
- IP addresses, hostnames, usernames, or account identifiers
- Any install ID or device ID
- Coordinates, postal codes, or physical-device hardware details
Reports contain no user, account, install, or device identifier. Cloudflare processes connection IP addresses, and the Worker uses them transiently for rate limiting without storing them in Analytics Engine or the installation histogram. Worker logs are disabled; Cloudflare's separate infrastructure processing is outside those settings.
How to turn it off
| Command or setting | Effect |
|---|---|
openclaw telemetry off | Stops anonymous feature statistics and the companion installation-count POST. Update checks and default-on outcomes continue. |
DO_NOT_TRACK=1 | Same, enforced from the environment. |
update.checkOnStart: false | Stops automatic update requests and outcome reporting. Explicit updates and other configured services are separate. |
OPENCLAW_NO_AUTO_UPDATE=1 also prevents automatic update requests. A truthy CI suppresses daily update checks and optional feature statistics unless a replacement OPENCLAW_TELEMETRY_ENDPOINT is explicitly configured. The replacement-endpoint exception applies only to daily update checks and optional feature statistics, not update outcomes.
openclaw telemetry show displays policy and a CLI-built payload preview, not the exact next Gateway payload or server-derived location information. Registry state and collection time can differ. If policy disables requests, it shows Request: none. Disabling requests does not erase previously recorded rows.