#Config System

#One-line summary

The config system loads, validates, and manages openclaw.json — a JSON5 configuration file with environment variable substitution, include resolution, Zod validation, and atomic writes with backup rotation.

#Responsibilities

• Parse JSON5 config with ${ENV_VAR} substitution and $include resolution
• Validate against Zod schema (OpenClawSchema) with plugin config extensions
• Migrate legacy config formats automatically
• Provide cached config access with invalidation
• Perform atomic writes (temp file + rename) with backup rotation
• Audit log config changes

#Architecture diagram

#Key source files

#OpenClawConfig structure (30+ sections)

meta, auth, env, wizard, diagnostics, logging, update, browser, ui,
skills, plugins, models, nodeHost, agents, tools, bindings, broadcast,
audio, messages, commands, approvals, session, web, channels, cron,
hooks, discovery, canvasHost, talk, gateway, memory

Key token-related settings:

• agents.defaults.compaction.reserveTokensFloor — compaction trigger
• agents.defaults.compaction.reserveTokens — reserve budget
• agents.defaults.compaction.keepRecentTokens — recent history protection
• skills.limits.* — skill catalog limits
• tools.allow/deny — tool policy
• memory.* — RAG settings

#How it connects to other modules

• Depends on: zod (validation), json5 (parsing), file system
• Depended by: Every module reads OpenClawConfig — this is the universal settings source

#My blind spots

• $include resolution — how deep nesting works and circular reference prevention
• Plugin config schema registration — how extensions add their own validation
• Backup rotation — how many backups are kept and rotation strategy
• Shell env fallback — env.shellEnv behavior
• Config change event propagation — how subsystems react to config updates

#Change frequency

• io.ts: Medium — migration logic and env handling evolve
• zod-schema.ts: High — every new feature adds config sections
• types.openclaw.ts: High — mirrors zod-schema changes