A broken openclaw.json is one of the fastest ways to make every other OpenClaw symptom look unrelated. The right sequence is backup, automatic repair, then verification with gateway status and logs.
Quick answer
Copy the config to a dated backup, run openclaw doctor --fix, and verify the gateway afterwards. Do not start hand-editing random keys until doctor has had a chance to normalize the file.
Command line steps
1. Create a timestamped backup of the config
Always preserve the broken file first so you can compare before and after.
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.$(date +%Y%m%d-%H%M%S)2. Run the repair tool
Doctor can normalize legacy keys, rewrite stale shapes, and drop unknown config keys when needed.
openclaw doctor --fix3. Verify the gateway and tail the logs
If the repair worked, the service should come back cleanly and the logs should stop repeating parse errors.
openclaw gateway status --require-rpc
openclaw logs --followWhat to check if it still fails
- If doctor keeps reporting the same key, compare the backup and current file instead of retrying blind.
- If the gateway still fails after repair, search the live logs for the first parse or validation error, not the last cascade error.
- If you previously changed config by copying snippets from older guides, run
openclaw doctor --deepto catch related state or service issues too.
Frequently asked questions
What will I learn from How to Fix the 'Failed to Read Config' Error in openclaw.json?
Back up the config, let doctor repair the file first, and only hand-edit the JSON when the CLI tells you exactly what is broken. The guidance is written for practical self-hosted OpenClaw environments, but commands and configuration can change between releases.
Should I back up OpenClaw before changing the configuration?
Yes. Back up the active configuration, credentials references, channel settings, and service definitions before repairs, upgrades, or model changes, then validate the gateway and important workflows after the change.
Can Milan help with OpenClaw setup or troubleshooting?
Yes. Milan provides OpenClaw setup, model and channel configuration, secure remote access, workflow automation, troubleshooting, and deployment support.