Configuration
Environment variables#
ClawMetry is zero-config by design; everything here is an override for a
situation auto-detection cannot see. Nothing on this page is required.
Paths and identity#
| Variable | Default | Effect |
|---|
CLAWMETRY_HOME | ~/.clawmetry | ClawMetry's own state directory |
CLAWMETRY_LOCAL_STORE_PATH | inside CLAWMETRY_HOME | The DuckDB store file |
CLAWMETRY_NODE_ID | hostname | This node's identity |
OPENCLAW_HOME | ~/.openclaw | OpenClaw workspace root |
CLAWMETRY_OPENCLAW_DIR | ~/.openclaw | OpenClaw config directory. Same as --openclaw-dir. |
OPENCLAW_DATA_DIR | | OpenClaw data directory |
OPENCLAW_WORKSPACE | | OpenClaw workspace directory |
OPENCLAW_SESSIONS_DIR | | Session transcript directory |
OPENCLAW_LOG_DIR | | Log directory |
OPENCLAW_METRICS_FILE | | Metrics persistence file |
CLAWMETRY_REPO_ROOT | | Repository root, for git-join features |
Gateway#
| Variable | Effect |
|---|
OPENCLAW_GATEWAY_TOKEN | Gateway authentication token |
OPENCLAW_GATEWAY_URL | Gateway URL |
OPENCLAW_GATEWAY_PORT | Gateway port (default 18789) |
CLAWMETRY_ENABLE_WS_TAP | 0 disables the gateway WebSocket tap. Default on. |
Ingest#
| Variable | Default | Effect |
|---|
CLAWMETRY_FAMILY_SESSION_LIMIT | 50 | Recent sessions ingested per runtime per pass |
CLAWMETRY_FAMILY_EVENT_CAP | | Events pulled per session |
CLAWMETRY_INTERCEPT | 0 | Activate the HTTP interceptor at startup |
CLAWMETRY_TRACK | 0 | Activate the interceptor on package import |
CLAWMETRY_NO_INTERCEPT | | Opt out even when clawmetry.track is imported |
CLAWMETRY_SOURCE | | Name the intercepted source |
CLAWMETRY_INTERCEPT_HOSTS_EXCLUDE | | Comma-separated hosts to skip |
CLAWMETRY_INGEST_TOKEN | | Token for the custom-runtime ingest API |
CLAWMETRY_VM_USAGE_LOG | | Hosted-VM loopback usage log path |
CLAWMETRY_VM_USAGE_RUNTIME | | Which runtime that log belongs to |
CLAWMETRY_DISABLE_CLAUDE_SESSION_INGEST | | Turn off the Claude Code adapter |
OpenTelemetry#
| Variable | Default | Effect |
|---|
CLAWMETRY_OTLP_ALLOW_UNAUTH | 0 | Accept unauthenticated OTLP. Loopback only. |
CLAWMETRY_OTLP_MAX_DECOMPRESSED_MB | 64 | Reject payloads expanding beyond this |
CLAWMETRY_OTLP_APP_CAP | | Cap on distinct applications accepted |
CLAWMETRY_OTEL_EXPORT_ENDPOINT | | OTLP endpoint to push ClawMetry's own metrics to |
CLAWMETRY_OTEL_EXPORT_HEADERS | | JSON object of headers for that push |
CLAWMETRY_OTEL_EXPORT_INTERVAL | | Export cadence in seconds |
Store#
| Variable | Default | Effect |
|---|
CLAWMETRY_LOCAL_FLUSH_SECS | | Flush cadence |
CLAWMETRY_LOCAL_FLUSH_BATCH | | Flush batch size |
CLAWMETRY_LOCAL_MAX_GB | | Soft cap on store size |
CLAWMETRY_DUCKDB_MEMORY_LIMIT | | DuckDB memory limit |
CLAWMETRY_DUCKDB_THREADS | | DuckDB thread count |
CLAWMETRY_AUTO_VACUUM | | Automatic compaction |
CLAWMETRY_RETENTION_DAYS | tier cap | Retention window, within tier limits |
CLAWMETRY_RETENTION_INTERVAL_HOURS | | How often retention runs |
CLAWMETRY_ROLLUP_BACKFILL_CHUNK | 5000 | Rows per rollup-backfill pass |
CLAWMETRY_INTEGRITY | | Maintain the tamper-evident hash chain |
CLAWMETRY_CCR | 0 | Compress content on write |
CLAWMETRY_ROLE | | Process role. The dashboard sets dashboard so it never takes a writer lock. |
Guard and detectors#
| Variable | Default | Effect |
|---|
CLAWMETRY_DETECTORS | 1 | Run the trajectory detectors |
CLAWMETRY_STUCK_DETECT | 1 | The same switch, older spelling |
CLAWMETRY_GUARD_POLICIES | 1 | Evaluate policies at all |
CLAWMETRY_POLICY_ENFORCE | 0 | Let a policy actually signal a process |
CLAWMETRY_DETECT_WINDOW | 200 | Newest events any detector examines |
CLAWMETRY_LOOP_IDENTICAL_K | 3 | Identical calls for stuck_loop |
CLAWMETRY_LOOP_MAX_CYCLE | 4 | Maximum cycle length |
CLAWMETRY_LOOP_CYCLE_REPEATS | 3 | Cycle repeats needed |
CLAWMETRY_NOPROG_TOOLS | 20 | Tool calls for no_progress |
CLAWMETRY_REPEAT_FAIL_M | 3 | Failures for repeated_tool_failure |
CLAWMETRY_ACTION_DISCREPANCY_MIN | 1 | Occurrences for action_discrepancy |
CLAWMETRY_BLAST_FILES | 25 | Files for file_blast_radius |
CLAWMETRY_EGRESS_HOSTS | 8 | Distinct hosts for network_egress |
CLAWMETRY_BASELINE_MIN_SESSIONS | 20 | Sessions before a learned baseline is used |
CLAWMETRY_BASELINE_SIGMA | 2.0 | Standard deviations above the mean |
CLAWMETRY_BASELINE_FLOOR | 0.5 | Lower clamp, as a ratio of the default |
CLAWMETRY_BASELINE_CEIL | 5.0 | Upper clamp, as a ratio of the default |
CLAWMETRY_GUARD_CRITICAL_USD | 5 | Spend at which a warning becomes critical |
Per-runtime tuning. Append __<RUNTIME> to any detector threshold variable
to scope it:
bash
CLAWMETRY_NOPROG_TOOLS__CODEX=40
CLAWMETRY_BLAST_FILES__CLAUDE_CODE=60
→ Thresholds and baselines
Proxy and budgets#
| Variable | Effect |
|---|
CLAWMETRY_PROXY_DAILY_USD | Daily budget |
CLAWMETRY_PROXY_MONTHLY_USD | Monthly budget |
CLAWMETRY_PROXY_AUTO_ROUTE | Automatic model routing |
CLAWMETRY_HARD_BLOCK | Hard block behaviour |
CLAWMETRY_HARD_BLOCK_ESCAPE | Escape hatch for a hard block |
Cloud and licensing#
| Variable | Effect |
|---|
CLAWMETRY_ENDPOINT | Where snapshots are pushed |
CLAWMETRY_INGEST_URL | Ingest URL override |
CLAWMETRY_API_KEY | API key |
CLAWMETRY_TOKEN | Auth token for API calls |
CLAWMETRY_NO_CLOUD | 1 forces local-only mode |
CLAWMETRY_OFFLINE | Skip every network call |
CLAWMETRY_SELF_HOSTED | Self-hosted server mode |
CLAWMETRY_SELF_HOSTED_DB | Database for that server |
CLAWMETRY_SELF_HOSTED_E2E | End-to-end encryption on a self-hosted endpoint |
CLAWMETRY_FLEET_KEY | Fleet authentication key |
CLAWMETRY_FLEET_DB | Fleet database path |
CLAWMETRY_LICENSE_SERVER | Alternative license server |
CLAWMETRY_LICENSE_PING | Whether an optional check-in happens |
CLAWMETRY_ENFORCE | Enable entitlement enforcement |
CLAWMETRY_ENFORCE_AT | Enforce as though at a given tier |
Security and network#
| Variable | Default | Effect |
|---|
CLAWMETRY_API_TOKENS | | Comma-separated tokens accepted on the API |
CLAWMETRY_REDACT | 1 | Redact secret-shaped values. 0 opts out. |
CLAWMETRY_CA_BUNDLE | | Custom CA bundle |
CLAWMETRY_TLS_NO_VERIFY | | Disable TLS verification. Diagnostics only. |
CLAWMETRY_MAX_REQUEST_MB | | Global request size cap |
CLAWMETRY_ADMIN_USER | | Admin user for protected surfaces |
Updates#
| Variable | Default | Effect |
|---|
CLAWMETRY_AUTO_UPDATE | 1 | Kill switch for unattended upgrades |
CLAWMETRY_UPDATE_CHECK_SECS | 60 | PyPI check cadence |
CLAWMETRY_AUTOUPDATE_MIN_AGE_HOURS | 0 | Stability window before installing a release |
CLAWMETRY_AUTOUPDATE_RETRY_SECS | | Retry interval after a failed update |
Evals and insights#
| Variable | Effect |
|---|
CLAWMETRY_EVALS_ENABLED | Master switch for the eval subsystem |
CLAWMETRY_EVALS_REGRESSION_ENABLED | Switch for regression replay |
CLAWMETRY_EVALS_REGRESSION_MAX | Default replay ceiling |
CLAWMETRY_EVALS_AGENT_CMD | Command used to run a replay |
CLAWMETRY_INSIGHTS | Enable the insights digest |
CLAWMETRY_NARRATOR_MODEL | Model used for narrative summaries |
CLAWMETRY_REVIEW_SAMPLE_SIZE | Sample size for review accuracy |
CLAWMETRY_SELFEVOLVE_AUTO | Allow Self-Evolve to act automatically |
CLAWMETRY_OUTCOME_FAILURE_PATTERNS | Pipe-separated regexes classifying a session as failed |
Behaviour and diagnostics#
| Variable | Effect |
|---|
DEBUG | Verbose logging |
CLAWMETRY_NO_BROWSER | Never open a browser |
CLAWMETRY_NO_TELEMETRY | Disable ClawMetry's own usage telemetry |
CLAWMETRY_SHOW_INTERNAL_SESSIONS | Surface ClawMetry's own internal sessions. For debugging ClawMetry itself. |
CLAWMETRY_PROVIDER | Data backend: local or turso |
CLAWMETRY_QUERY_CACHE_PUSH | Push cached query results in the snapshot. Default off. |
CLAWMETRY_HARNESS_HOOKS | Enable test-harness hooks. Not for production. |
NO_COLOR | Plain output |
Per-runtime data locations#
Each runtime has its own override. The full list, with the discovery order, is
on each runtime's reference page. The pattern:
| Runtime | ClawMetry override | Runtime's own |
|---|
| Claude Code | CLAWMETRY_CLAUDE_DESKTOP_DIR | CLAUDE_CONFIG_DIR |
| Codex | — | CODEX_HOME |
| Cursor | CLAWMETRY_CURSOR_DB, CLAWMETRY_CURSOR_AGENT_ROOT, CLAWMETRY_CURSOR_CHATS_ROOT | — |
| Cline | CLAWMETRY_CLINE_DATA_DIR | CLINE_DATA_DIR, CLINE_DIR |
| Copilot | CLAWMETRY_COPILOT_HOME | — |
| Gemini CLI | CLAWMETRY_GEMINI_CLI_HOME | GEMINI_CLI_HOME |
| Qwen Code | — | QWEN_HOME |
| Antigravity | CLAWMETRY_ANTIGRAVITY_HOME | — |
| Goose | CLAWMETRY_GOOSE_DB | GOOSE_PATH_ROOT, XDG_DATA_HOME |
| opencode | CLAWMETRY_OPENCODE_DB | XDG_DATA_HOME |
| Devin | CLAWMETRY_DEVIN_DB, CLAWMETRY_DEVIN_HOME | XDG_DATA_HOME |
| OpenHands | CLAWMETRY_OPENHANDS_HOME | OPENHANDS_PERSISTENCE_DIR |
| OpenWorker | CLAWMETRY_OPENWORKER_STATE_DIR | COWORKER_STATE_DIR |
| Deep Agents | CLAWMETRY_DEEPAGENTS_DB | — |
| DeepSeek Harness | — | DSH_HOME |
| Kimi | CLAWMETRY_KIMI_ROOTS | KIMI_SHARE_DIR |
| Grok | CLAWMETRY_GROK_HOME | — |
| Hermes | — | HERMES_HOME |
| PicoClaw | — | PICOCLAW_HOME |
| NanoClaw | CLAWMETRY_NANOCLAW_DIR | — |
| Pi | CLAWMETRY_PI_DIR | PI_CODING_AGENT_SESSION_DIR |
| Exo | CLAWMETRY_EXO_ROOTS | — |
| n8n | CLAWMETRY_N8N_DB, CLAWMETRY_N8N_URL, CLAWMETRY_N8N_API_KEY | N8N_USER_FOLDER |
| QM | CLAWMETRY_QM_DATABASE_URL | DATABASE_URL |
| Aider | — | AIDER_HISTORY_DIRS |