Where Is the OpenClaw Config File?

You need to change a model, add a channel, or fix a setting the docs mention, but you cannot find where OpenClaw actually keeps its configuration. The answer is short, and the details around it (how to edit safely, what happens when you break it, which fields bite back) are worth two minutes of your time before you open an editor.

The Short Answer: ~/.openclaw/openclaw.json

OpenClaw reads a single optional config file from a hidden .openclaw folder in your home directory:

1. macOS: /Users/<you>/.openclaw/openclaw.json
2. Linux: /home/<you>/.openclaw/openclaw.json
3. Windows: C:\Users\<you>\.openclaw\openclaw.json (that is %USERPROFILE%\.openclaw\openclaw.json)

The file is JSON5, not strict JSON, so comments and trailing commas are allowed. If the file does not exist at all, OpenClaw simply runs with safe defaults; it is created and filled in during onboarding.

Find the Active Config File in One Command

Do not guess the path, ask OpenClaw. The CLI prints the exact file the gateway is using:

openclaw config file

Two situations where the answer differs from the default location:

1. The OPENCLAW_CONFIG_PATH environment variable overrides the default. If someone set it (common in Docker or systemd setups), the active file lives wherever it points. Check with echo $OPENCLAW_CONFIG_PATH on macOS and Linux or echo $env:OPENCLAW_CONFIG_PATH in PowerShell.
2. On a server, the config belongs to the user running the gateway. If OpenClaw runs under a service account, look in that account's home directory, not yours.

How to View and Edit the Config Safely

You have four editing routes, from safest to most manual:

1. Back up first. One command spares you a bad afternoon: cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
2. Read a value without opening the file: openclaw config get agents.defaults.model
3. Set a value through the CLI so the syntax stays valid: openclaw config set gateway.port 18790
4. Edit the file directly in any editor. The gateway watches the file and hot-reloads safe changes automatically, so you usually do not need a manual restart.
5. Use the Control UI at http://127.0.0.1:18789, which has a Config tab with the same settings in a form.

After any manual edit, validate before you walk away:

openclaw config validate

OpenClaw uses strict schema validation: unknown keys, wrong types, or invalid values make the gateway refuse to start. The safety nets are good, though. Invalid edits get saved aside as openclaw.json.rejected.<timestamp> for inspection, and the gateway keeps a trusted last-known-good copy from its last successful start.

How to Regenerate the Config From Scratch

If the file is mangled beyond repair, you do not need to reinstall OpenClaw.

1. Move the broken file out of the way: mv ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.broken
2. Run the interactive setup to build a fresh one: openclaw configure (or the fuller openclaw onboard flow).
3. Restart and confirm: openclaw gateway restart, then openclaw gateway status.
4. Copy any custom sections you still need from the broken file back in, one block at a time, validating after each paste.

What NOT to Touch

A few fields cause a disproportionate share of broken gateways:

1. The model field expects a string. Set agents.defaults.model to a plain provider/model string such as "anthropic/claude-opus-4-8". Pasting a nested object where a string belongs fails validation, and there are reports of an invalid model config leaving the gateway spinning at high CPU instead of exiting cleanly. If you need fallbacks, use the documented structured form exactly, and validate afterwards.
2. Do not invent keys. The schema is strict, so a guessed setting name does not get ignored, it blocks startup. Check openclaw config get for the real key first.
3. Do not symlink the config file. OpenClaw writes the file atomically by renaming a new file onto the path, which replaces a symlink's target instead of writing through it. Keep the real file at the real path, or use OPENCLAW_CONFIG_PATH if you want it elsewhere.
4. Treat secrets as secrets. The file can contain gateway auth tokens and API keys. Do not commit it to git or paste it whole into chat or forums; redact before sharing.

Frequently Asked Questions

Can I move the OpenClaw config file somewhere else?

Yes. Set the OPENCLAW_CONFIG_PATH environment variable to the full path of the real file and restart the gateway. This is the supported way to keep config in a custom location, for example on a mounted volume. Point it at a regular file, not a symlink.

What format is openclaw.json? My editor flags the comments as errors.

It is JSON5, a superset of JSON that allows comments, trailing commas, and unquoted keys. Editors linting it as plain JSON will complain incorrectly. Either switch the file type to JSON5 in your editor or ignore those specific warnings; openclaw config validate is the verdict that actually matters.

I broke the config and the gateway will not start. Now what?

Run openclaw doctor to see the exact complaint. Look for an openclaw.json.rejected file next to your config, which holds the edit that failed validation. Then either restore your backup, fix the flagged line, or regenerate with openclaw configure. Your sessions and pairing data live in separate files, so fixing the config does not erase them.

On a managed OpenClaw host, the config ships pre-validated and stays that way through updates, so this file is one you rarely have to open.