Clawtrail Docs

Clawtrail connects to OpenClaw via its diagnostics-otel plugin. The CLI handles everything — detecting OpenClaw, installing OTel dependencies, writing the config, and verifying the connection.

First, create an API key in app.clawtrail.dev then run:

$ npx clawtrail install --key ct_live_xxx

✓ Detected OpenClaw at ~/.local/bin/openclaw
✓ Installed 11 OTel dependencies (--legacy-peer-deps)
✓ Config written → ~/.openclaw/openclaw.json
✓ Plugin enabled, gateway restarted
✓ Connected — waiting for first run ▸

Replace ct_live_xxx with your actual API key. Once connected, runs start appearing in your dashboard automatically.

API keys are scoped to your team and identify which OpenClaw gateway is sending telemetry. Each key is in the format ct_live_<32 hex chars>.

Keys are shown once at creation time. Store them securely — Clawtrail only stores a hash.

To create a key: sign in → API Keys → Create key. Give it a name matching your OpenClaw instance (e.g. work-macbook).

After running npx clawtrail install, check the connection:

$ npx clawtrail status --key ct_live_xxx

Gateway: work-macbook
Status:  connected
Last seen: 4 seconds ago

The dashboard also shows a live connection indicator on the Gateways page. If status is waiting, trigger an OpenClaw run — the first event confirms the pipeline is live.

OpenClaw's diagnostics-otel plugin sends telemetry to Clawtrail automatically once installed:

POST https://api.clawtrail.dev/otel/v1/traces
POST https://api.clawtrail.dev/otel/v1/metrics
Authorization: Bearer ct_live_xxx

The CLI writes this config automatically. For manual setup, add the following to ~/.openclaw/openclaw.json:

{
  "diagnostics": {
    "enabled": true,
    "otel": {
      "enabled": true,
      "endpoint": "https://api.clawtrail.dev/otel",
      "protocol": "http/protobuf",
      "headers": { "authorization": "Bearer ct_live_xxx" },
      "traces": true,
      "metrics": true,
      "logs": true
    }
  }
}

Each OpenClaw run appears as a single entry in your dashboard, grouped by session. Multiple events from the same agent run (model usage, message processing) are automatically combined into one run record.

Runs have the following status values:

• completedRun finished successfully
• errorOpenClaw encountered an error (for cron: WhatsApp delivery failed — LLM work still succeeded)
• over_limitMonthly run limit reached — run stored but flagged
• unknownStatus could not be determined from telemetry

OpenClaw's scheduled jobs don't appear in the standard telemetry pipeline. The Clawtrail cron agent bridges this gap — it monitors completed cron runs and syncs them to your dashboard automatically.

$ npx clawtrail cron enable --key ct_live_xxx

✓ Cron agent installed (launchd on macOS, crontab on Linux)
✓ Monitoring cron runs — syncing to dashboard automatically

npx clawtrail install --key ct_live_xxx [--name "work-macbook"] [--endpoint https://api.clawtrail.dev/otel]

Detects OpenClaw, installs OTel deps, writes config, enables plugin, restarts gateway, polls health check.

npx clawtrail status --key ct_live_xxx

Shows gateway connection status and last seen timestamp.

npx clawtrail cron enable --key ct_live_xxx
npx clawtrail cron disable
npx clawtrail cron status

Installs or removes the local cron agent that syncs OpenClaw cron run history to Clawtrail.

npx clawtrail cron run --key ct_live_xxx [--verbose]

Manually runs one sync cycle — picks up new completed runs and syncs them to Clawtrail.

Your ct_live_ API key works for both telemetry ingestion and programmatic access to the Clawtrail API.

POST https://api.clawtrail.dev/api/machine-intent
Authorization: Bearer ct_live_xxx
Content-Type: application/json

{ "model": "Gateway", "command": "health_check" }

Use this to build custom integrations — poll gateway status from your own scripts, trigger cron syncs programmatically, or query run data directly.