Configuration

Claw Insights uses a three-layer configuration system:

1. Environment variables (highest priority)
2. Config file (~/.claw-insights/config.json)
3. NODE_ENV defaults (lowest priority)

Environment Variables

All variables use the CLAW_INSIGHTS_ prefix. For backward compatibility, OPENCLAW_ prefix is also accepted (lower priority).

Core

Variable	Default	Description
CLAW_INSIGHTS_SERVER_PORT	41041	GraphQL API + web server port
CLAW_INSIGHTS_WEB_PORT	41042	Vite dev server port (development only)
CLAW_INSIGHTS_API_TOKEN	(auto-generated)	Auth token (minimum 32 characters). Empty = auto-generate on startup
CLAW_INSIGHTS_NO_AUTH	false	Disable authentication entirely (true or 1)
CLAW_INSIGHTS_SERVER_ONLY	false	Run API server without serving web UI
CLAW_INSIGHTS_OPEN	false	Open dashboard in browser after start (true or 1)
CLAW_INSIGHTS_GATEWAY	—	OpenClaw gateway URL (set via --gateway flag, e.g., http://127.0.0.1:3578)
LOG_LEVEL	info	Log level override — no CLAW_INSIGHTS_ prefix (pino levels: fatal, error, warn, info, debug, trace)

Data Sources

Variable	Default	Description
CLAW_INSIGHTS_DB	~/.claw-insights/metrics.db	SQLite database path (alias: CLAW_INSIGHTS_DB_PATH)
CLAW_INSIGHTS_SESSIONS_PATH	~/.openclaw/agents/main/sessions/sessions.json	OpenClaw sessions file
CLAW_INSIGHTS_LOG_DIR	/tmp/openclaw/	OpenClaw log directory
CLAW_INSIGHTS_DIR	~/.openclaw	OpenClaw base directory (used as prefix for other paths)
CLAW_INSIGHTS_CLI	(auto-detected)	Path to openclaw CLI binary. Auto-detection checks which openclaw, common install locations, then falls back to bare openclaw
CLAW_INSIGHTS_CRON_PATH	~/.openclaw/cron/jobs.json	OpenClaw cron jobs file
CLAW_INSIGHTS_TRANSCRIPTS_DIR	~/.openclaw/agents/main/sessions	Transcript JSONL files directory
CLAW_INSIGHTS_DEVICE_JSON	~/.openclaw/identity/device.json	Device identity JSON file (used for lifetime stats createdAt)

Note: CLAW_INSIGHTS_TRANSCRIPTS_DIR and CLAW_INSIGHTS_DEVICE_JSON default paths are derived from CLAW_INSIGHTS_DIR when set. For example, setting CLAW_INSIGHTS_DIR=/custom/path makes transcripts default to /custom/path/agents/main/sessions.

Data Retention

Variable	Default	Description
CLAW_INSIGHTS_RAW_RETENTION_DAYS	7	Days to keep raw metric data
CLAW_INSIGHTS_HOURLY_RETENTION	permanent	Hourly aggregate retention (permanent or days)

Config File

Create ~/.claw-insights/config.json:

{
  "serverPort": 41041,
  "apiToken": "your-secure-token-at-least-32-characters"
}

Security: If the file contains apiToken, restrict permissions:

chmod 600 ~/.claw-insights/config.json

Public Keys

These keys are commonly configured:

Key	Type	Default	Description
serverPort	number	41041	GraphQL API + web server port
webPort	number	41042	Vite dev server port
apiToken	string	—	Auth token (min 32 chars)
noAuth	boolean	false (prod)	Disable authentication
dbPath	string	~/.claw-insights/metrics.db	SQLite database path
logLevel	string	—	Log level: debug, info, warn, error
rawRetentionDays	number	7	Days to keep raw metric data
serverOnly	boolean	false	Run API server without web UI
hourlyRetention	string	permanent	Hourly aggregate retention
transcriptsDir	string	~/.openclaw/agents/main/sessions	Transcript JSONL directory
deviceJsonPath	string	~/.openclaw/identity/device.json	Device identity JSON path
sessionHierarchyMode	string	single	Session hierarchy display: single (flat) or dual (parent + sub-agent)

Advanced Keys

Advanced Configuration

These keys are for fine-tuning and rarely need modification.

Token Rotation:

Key	Type	Default	Description
tokenRotationEnabled	boolean	true	Enable automatic token rotation
tokenRotationIntervalMs	number	86400000 (24h)	Rotation interval
tokenGraceMs	number	43200000 (12h)	Grace period for old tokens
tokenRotationCheckIntervalMs	number	300000 (5min)	How often to check rotation
tokenMaxPrevious	number	2	Max previous tokens kept valid

Log Budget:

Key	Type	Default	Description
logBudgetMb	number	1024	Total log budget in MB
logRetentionDays	number	14	Log retention in days
errorFloorMb	number	300	Minimum error log space
errorReserveMb	number	50	Reserved error log space
appSoftMb	number	500	App log soft limit
debugSoftMb	number	200	Debug log soft limit

Queue & I/O:

Key	Type	Default
criticalQueueMax	number	10000
bestEffortQueueMax	number	50000
criticalFsyncMs	number	100
criticalSyncBatch	number	1000
logFileMode	number	0o644

Back-Pressure Thresholds:

Key	Type	Default	Description
pressureQueuePct	number	70	Queue pressure threshold (%)
pressureIoLagMs	number	200	I/O lag pressure threshold
pressureBudgetPct	number	85	Budget pressure threshold (%)
pressureFreeSpaceMb	number	512	Free space pressure threshold
emergencyQueuePct	number	90	Queue emergency threshold (%)
emergencyIoLagMs	number	1000	I/O lag emergency threshold
emergencyBudgetPct	number	95	Budget emergency threshold (%)
emergencyFreeSpaceMb	number	128	Free space emergency threshold

Unknown keys are logged as warnings and ignored.

NODE_ENV Defaults

Settings change based on NODE_ENV:

Setting	development	test	production
Authentication	disabled	disabled	enabled
Server port	41041	4111	41041
Web port	41042	3211	41042
Database	metrics.db	test-metrics.db	metrics.db
Raw retention	7 days	1 day	7 days

Authentication Details

Token flow

1. Server starts → generates token (or reads from env/config)
2. Prints token URL: 🔑 http://127.0.0.1:41041/?token=xxx
3. Browser opens URL → server sets claw_session cookie containing a hash of the token (7 days, httpOnly)
4. Subsequent requests authenticated via cookie (automatic in browsers) or Authorization: Bearer <token> header

Programmatic access

# Bearer token (recommended for scripts)
curl -H "Authorization: Bearer YOUR_TOKEN" http://127.0.0.1:41041/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"{ system { ... on OpenClawSystem { gateway { running version uptime } } } }"}'

Note: Cookie-based auth (claw_session) is handled automatically by browsers after visiting the token URL. The cookie contains a hash of the token, not the raw token itself.

Multi-source Support

Planned

Multi-source support is architected but not yet exposed as a user-facing feature. The internal data source registry already supports multiple sources with independent status tracking. This section will be updated when multi-gateway configuration is available.