The OpenClaw config file

OpenClaw reads one optional JSON5 config file from the OpenClaw directory under your home folder, and if the file is missing it runs on safe defaults. Every channel, model, tool, sandbox and automation setting ends up in that file, which is why the docs spend more words on how it is validated and reloaded than on any single key. Here is where it lives, the four ways to edit it, the rule that decides where a setting goes, what happens when it is wrong, and what hot reload does with a change.

Four ways to edit it

• The wizards: the onboarding flow for a first setup and the configure command for a section at a time.
• One-liners: config get, set and unset with a dotted path, which is also the form the docs use in every recipe.
• The Control UI Config tab, a form rendered from the live schema with titles and descriptions, common fields first and each section’s advanced fields collapsed, and a raw JSON editor as the escape hatch.
• A direct edit: the Gateway watches the file and applies changes, treating a hand edit as untrusted until it validates. The path must be a regular file; OpenClaw replaces it atomically, so a symlinked config gets its target replaced, and a file kept elsewhere is pointed to with an environment variable.

The two-bucket rule

Root-level sections hold infrastructure and cross-agent defaults: the Gateway, channels, tools, plugins, sessions, media. The agent defaults section holds the behaviour of the agent loop: workspace, model, heartbeat, memory. Per-agent entries may override either where the schema allows it. The minimal config the docs show is two lines, a workspace and a WhatsApp allow-from list, and the docs tell agents and tooling to look a field up in the schema before editing it.

OpenClaw only accepts configurations that fully match the schema.

Strict validation

• Unknown keys, malformed types or invalid values make the Gateway refuse to start; the only tolerated extra is a schema pointer at the root. Startup first applies safe legacy-key migrations, the same prompt-free transforms the doctor uses, and keeps the previous file in a backup ring.
• With an invalid file only the diagnostic commands work: doctor, logs, health and status. Doctor shows the exact issues, and its fix flag applies the repairs.
• The Gateway keeps a trusted last-known-good copy after each successful start but never restores it on its own; it also blocks writes that look like accidental clobbers, such as dropping the Gateway mode or shrinking the file by more than half, and tries to save the rejected payload beside the file for inspection.

OpenClaw terminal commands lists the commands that matter here, doctor first, and OpenClaw not responding is where an invalid config shows up as a symptom: a Gateway that is simply not there.

Hot reload, and where the keys live

Reload has two modes: hybrid, the default, applies hot-reloadable settings and restarts the Gateway automatically when a change needs it; off keeps watching and validating but waits for a manual restart. Each changed path is classified as restart, hot or no action, the longest matching prefix decides, and a path that matches no rule defaults to a restart. An invalid reload is skipped and the runtime keeps the last accepted config. Secrets have their own rules:

• OpenClaw reads environment variables from the parent process, a dot-env file in the working directory and a global one in the OpenClaw directory; neither file overrides what is already set.
• Any string value can reference an uppercase variable with the dollar-brace syntax; a missing variable stays visibly unresolved with a warning rather than becoming an empty string.
• Fields that accept a secret reference can point at an environment variable, a file, a command or a store instead of holding the value.

On Diali

On Diali the file is generated for each assistant from what you set in the dashboard, validated before it is written and replaced on every release, so there is nothing to hand-edit and no way for an upgrade to leave it invalid. Hosted OpenClaw on Diali is the assistant.

• One JSON5 file, safe defaults without it, strict schema with it.
• Infrastructure at the root, agent behaviour under defaults.
• Hybrid reload restarts when it must; doctor repairs when it cannot.