Configuration

Configuration

ClawDE reads configuration from clawd.toml. The file location varies by platform:

Platform	Path
macOS	~/Library/Application Support/clawd/clawd.toml
Linux	~/.local/share/clawd/clawd.toml or $XDG_DATA_HOME/clawd/clawd.toml
Windows	%APPDATA%\clawd\clawd.toml

If the file doesn't exist, ClawDE uses defaults. All settings are optional.

All configuration keys

General

Key	Type	Default	Description
log_level	string	"info"	Log verbosity: trace, debug, info, warn, error
max_sessions	integer	0	Max concurrent sessions. 0 = unlimited
port	integer	4300	WebSocket IPC server port

Resources

Controls how the daemon manages memory across multiple sessions.

Key	Type	Default	Description
resources.max_memory_percent	integer	70	Max % of total system RAM for daemon + sessions (10-95)
resources.max_concurrent_active	integer	0	Max active CLI subprocesses. 0 = auto-calculate from RAM
resources.idle_to_warm_secs	integer	120	Seconds before idle session is frozen (SIGSTOP)
resources.warm_to_cold_secs	integer	300	Seconds before frozen session is killed and saved to disk
resources.process_pool_size	integer	1	Pre-warmed CLI workers for fast cold resume
resources.emergency_memory_percent	integer	90	RAM % that triggers aggressive eviction
resources.poll_interval_secs	integer	5	How often the resource governor checks system memory

Provider settings

Key	Type	Default	Description
provider.claude.timeout_secs	integer	300	Session timeout for Claude provider
provider.codex.timeout_secs	integer	300	Session timeout for Codex provider

Environment variables

Every config key can be overridden with an environment variable using CLAWD_ prefix:

Variable	Config key	Example
CLAWD_PORT	port	CLAWD_PORT=4301
CLAWD_LOG	log_level	CLAWD_LOG=debug
CLAWD_DATA_DIR	Data directory	CLAWD_DATA_DIR=/custom/path
CLAWD_MAX_SESSIONS	max_sessions	CLAWD_MAX_SESSIONS=5

Example configuration

# Tuned for a 16 GB machine with moderate AI usage
[resources]
max_memory_percent = 65
idle_to_warm_secs = 60
warm_to_cold_secs = 180
process_pool_size = 1

[provider.claude]
timeout_secs = 600   # 10-minute timeout for long tasks

Hot reload

ClawDE watches clawd.toml for changes and applies non-critical settings (like log_level) without a daemon restart. Session limits and port changes require a restart.