OpenClaw Configuration Guide: Edit, Validate, and Safely Reload Your Gateway
OpenClaw configuration is powerful because one file can shape your workspace, model defaults, channels, access rules, tools, automation, and Gateway behavior. It is also strict: an unknown key, malformed type, or invalid value can prevent the Gateway from starting. The safest way to configure OpenClaw is not to copy a large example and hope it works. Make one small, documented change, validate it, and then verify the live behavior.
This OpenClaw configuration guide explains the file location, the available editing paths, the difference between validation and security checks, and a recovery sequence for mistakes. Examples use placeholders rather than real credentials. Always confirm the exact fields supported by the version installed on your machine.
Quick answer: OpenClaw uses
~/.openclaw/openclaw.jsonby default. You can pointOPENCLAW_CONFIG_PATHat another regular file. Start withopenclaw onboardor the Control UI for guided changes; use direct edits or CLI commands for precise work. Before relying on a change, runopenclaw doctor --lint, then check Gateway and channel health.
Know which configuration file is active
The default configuration path is:
~/.openclaw/openclaw.json
The file is optional. If it does not exist, OpenClaw uses safe defaults. If you keep the file elsewhere, set OPENCLAW_CONFIG_PATH to the real file. The active path must be a regular file. Avoid symlinked openclaw.json layouts: OpenClaw-owned writes replace the file atomically, so a symlink target may be replaced rather than updated through the link.
Before editing, establish which profile, user, and service account runs the Gateway. A configuration in your interactive shell may not be the configuration used by a system service. This is especially important after a move to a VPS, a change in supervisor, or a remote-access setup. If the CLI appears healthy but your edits have no effect, check the process environment and endpoint before changing more settings.
Make a private backup before a meaningful change. Store it outside public repositories and redact or protect any credentials. A backup is useful for comparison and rollback, but do not blindly restore an old file if the current release has migrated its schema. Let openclaw doctor identify migration or repair needs.
Choose the least risky editing method
Guided onboarding
For a new installation or a broad first setup, use:
openclaw onboard
The onboarding flow is safer than inventing a complete configuration from memory. It can guide provider and channel setup, then leave you with a configuration that matches the installed release. Use it for initial setup, not as a reason to overwrite a carefully maintained production file without a backup.
Control UI
After the Gateway is running, open the local Control UI at http://127.0.0.1:18789 unless your installation uses another endpoint. The UI renders a form from the live configuration schema, including documentation metadata and available plugin or channel schemas. Settings search covers common and advanced fields, while the editor remains an escape hatch for cases the form does not expose.
The Control UI is useful when you need field descriptions and want to avoid spelling a key incorrectly. It is not a substitute for access control. Keep the UI on a trusted network surface and follow the remote-access guidance before exposing it beyond localhost.
CLI and direct edits
For a small, repeatable change, use the documented CLI configuration commands where available. For a structured review or a change involving several related fields, edit ~/.openclaw/openclaw.json directly with a JSON5-aware editor. JSON5 permits comments and trailing commas, but regular JSON also works.
Do not paste secrets into a chat transcript, shell history, screenshots, or a public issue. Configuration examples should use placeholders such as provider-key-redacted or a masked phone number. Keep the real credential in the supported auth or secret mechanism for your installation.
Put each setting in the right bucket
OpenClaw’s configuration has a useful two-bucket rule. Root-level siblings generally hold infrastructure and cross-agent defaults. agents.defaults holds agent-loop behavior. Entries under agents.entries can override supported values for an individual agent.
A small starter configuration might look like this:
{
agents: {
defaults: {
workspace: "~/.openclaw/workspace",
},
},
channels: {
whatsapp: {
allowFrom: ["+155****0123"],
},
},
}
The important lesson is not the sample values; it is the placement. Do not move a setting under agents.defaults simply because it affects an agent, and do not assume every root setting can be overridden per agent. Use the current configuration reference or schema lookup for the exact field and supported override scope.
When you add a channel, start with a narrow allowlist. When you add a model, verify the provider and model identifier against the current provider documentation. When you change tools, sandboxing, or elevated access, treat that as a security change rather than a cosmetic preference. Our OpenClaw sandboxing guide explains why those boundaries should be evaluated separately.
Validate before you reload
OpenClaw strictly validates configuration. Unknown keys, invalid values, and malformed types can make the Gateway refuse to start. The only root-level exception documented for editor metadata is $schema as a string.
For a read-only automation or preflight check, run:
openclaw doctor --lint
This mode is designed for CI and review gates. It does not prompt, repair, restart, or write config/state. For machine-readable output, add --json; for the full registered lint audit, use --all when appropriate. Treat a nonzero result as a finding to investigate, not as permission to apply an aggressive fix automatically.
The schema command is another useful reference point:
openclaw config schema
Use it to inspect the canonical schema supported by your installed version. If a setting is unclear, check the schema and the official configuration reference instead of assuming that a similarly named option from an older release still applies.
A safe change-and-recovery workflow
Use this sequence for changes to channels, models, tools, access rules, or Gateway exposure:
- Record the current state. Note the active profile, endpoint, and the reason for the change. Back up the configuration privately.
- Change one related group at a time. Avoid combining a channel migration, network exposure, and tool-policy rewrite in one edit.
- Check the schema. Confirm field names, types, defaults, and whether an agent-level override is supported.
- Run read-only lint. Use
openclaw doctor --lintand, when useful,--json. - Observe the Gateway. The Gateway watches the config and applies supported changes automatically. Watch logs and status rather than assuming that every edit has the same reload behavior.
- Check live health. Run
openclaw healthand, when diagnosing a channel,openclaw status --deep. Our Gateway health checks guide shows how to separate Gateway reachability from provider and session symptoms. - Review security after access changes. Run
openclaw security audit; use--deeponly when a live Gateway probe is appropriate. - Document the result. Record the field changed, the validation result, and the observed behavior without storing secrets in the note.
If the Gateway will not boot after a change, do not keep editing randomly. Run diagnostic commands that still work, inspect the exact validation message, and compare the changed block with the current schema. openclaw doctor provides a friendly repair workflow; openclaw doctor --fix applies recommended repairs according to its repair policy, while --yes accepts defaults. Use --force only when you understand that aggressive repairs can overwrite custom supervisor configuration.
openclaw doctor --non-interactive is narrower: it applies safe migrations without prompts and skips actions needing human confirmation. That makes it more appropriate for unattended maintenance than an unreviewed aggressive repair. The documented last-known-good copy is not restored automatically just because startup or hot reload fails; use the supported Doctor repair path and your private backup deliberately.
Common configuration failures
“The Gateway refuses to start”
Usually begin with schema validation: a misspelled key, wrong scalar type, unsupported enum value, or stale field from another version. Remove the smallest changed block, run openclaw doctor --lint, and reintroduce settings one at a time.
“My edit has no effect”
Confirm the active configuration path and profile. A service may run as another user or with OPENCLAW_CONFIG_PATH set. Also check whether the setting is an agent-specific override that wins over a global default.
“The channel is connected but nobody can message the bot”
Configuration and health are different layers. Review DM/group policy and allowlists, then run the health and deep-status checks. A stale session row is not proof of current channel liveness.
“A configuration change expanded exposure”
Run the security audit after changes to binding, authentication, groups, tools, browser control, plugins, or remote access. The audit is designed to surface inbound access, tool blast radius, filesystem permissions, network exposure, and policy drift. For network design, see our OpenClaw remote access guide.
FAQ
Does OpenClaw require a config file?
No. The file is optional and OpenClaw uses safe defaults when it is missing. Add one when you need channel, model, tool, sandbox, automation, session, network, or UI settings.
Is OpenClaw configuration JSON or JSON5?
The official examples use JSON5. Comments and trailing commas are allowed; regular JSON works too. The content still must match the installed schema.
Is doctor --lint the same as doctor --fix?
No. --lint is read-only and intended for checks. --fix applies recommended repairs and may write configuration or state. Review the mode before using it in automation.
Should I expose the Control UI to the internet?
Do not treat the local UI as public infrastructure. Follow the project’s remote-access and security guidance, use authentication, and keep one trusted operator boundary per Gateway. If several mutually untrusted users need isolation, separate Gateway cells are the safer design.
Comments
Loading comments…