---
title: Environment variables
description: Every ClawMetry environment variable, grouped by what it controls — paths, ingest, store, Guard, cost, cloud, security and the per-runtime overrides.
keywords: clawmetry environment variables, CLAWMETRY_ config, agent observability configuration
eyebrow: 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](/docs/guard/thresholds/)

## 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](/docs/runtimes/overview/). 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` |