You open openclaw.json in a text editor, make a change, save it, and restart the gateway. The change does not take. The old value is back, and somewhere beside your config there is now a timestamped file named openclaw.json.clobbered.2026-07-28T17-22-51-777Z or similar.
Here is the truth about that moment: OpenClaw did not quietly revert you. Direct editor writes are treated as untrusted until they validate, and the recovery machinery that runs after a broken edit keeps a full backup of your file. Nothing is lost, and the fix is a three-command habit. This guide explains the mechanism, how to recover an edit that vanished, and the commands that make config changes stick on the first try.
Why a hand edit can vanish
Every config write in OpenClaw is checked before it counts. Two different safety paths cover the two ways config gets changed:
- OpenClaw-owned writes self-validate. Commands like
openclaw config setandconfig patchvalidate the full post-change config against the schema before committing it to disk. If the new payload fails validation or looks like a destructive clobber, the active config is left untouched and the rejected payload is saved beside it asopenclaw.json.rejected.*. - Direct editor writes are untrusted until they validate. Hand-editing the JSON file is still allowed, but the running gateway does not assume the result is valid. A broken direct edit fails startup (fail closed), or, when the gateway is already running, hot reload skips it with a log line like
config reload skipped (invalid config). Crucially, the gateway does not rewriteopenclaw.jsonitself; the repair tooling does, and only when you run it.
That last point is the piece most older write-ups get wrong. In earlier OpenClaw versions the story was simpler: a version stamp mismatch and an automatic restore. Current versions keep the version stamp (meta.lastTouchedVersion records which OpenClaw version last wrote the config), but the restore is deliberate and doctor-driven rather than automatic. You run the repair, OpenClaw restores the last-known-good config, and your broken edit is preserved as a timestamped backup file rather than deleted. The gateway keeps the latest 32 of those backup files per config path and rotates older ones.
The proof: backups sitting beside your config
If you suspect a repair ran on your machine, look for the backup files. This is a real listing from a host that has been through a few repair sessions:
Each of those files is a full snapshot of what the config looked like at repair time. If you need a value back from one, open the newest file, find the keys you changed, and re-apply them through the proper commands. Do not copy the whole file over the live config; that recreates the exact untrusted-edit problem you are trying to leave behind.
Step 1: Read what the gateway said
Before touching anything, check the log for the signature that names the failure mode:
user@host:~$ openclaw logs --follow # Look for one of these: Invalid config at ... config reload skipped (invalid config): ... Config write rejected: ...
Those three lines tell you which path rejected your edit: startup validation, hot reload, or an OpenClaw-owned write. All three end the same way: the old config stays active, and the rejected payload is saved to disk.
Step 2: Recover the vanished edit
Confirm where the active file lives, then list the rejected and repaired payloads next to it:
Run the repair in this order. openclaw config validate tells you whether the active config is currently healthy before you let doctor anywhere near it. openclaw doctor --fix is the repair owner: it can restore the last-known-good copy and it saves what it replaces as openclaw.json.clobbered.*. After the repair, re-apply only the keys you actually intended to change, using the validated write commands below.
The right way to change config
None of this is a reason to fear config changes. It is a reason to make them through the commands that validate as they write:
Three notes on the toolbox:
- There is no
config editsubcommand in current OpenClaw. Older guides (and some earlier versions of this post) recommended one; the interactive path today isopenclaw configure, which edits and validates in one flow. - Watch the apply hint. After every successful
config set,config patch, orconfig unset, the CLI prints one of three hints:Restart the gateway to apply.,Change will apply without restarting the gateway., orNo gateway restart needed.Writes underplugins.entriesalways require a restart. - The active config must be a regular file. Symlinked
openclaw.jsonlayouts are unsupported for writes; useOPENCLAW_CONFIG_PATHto point directly at the real file instead.
The diagram puts the whole flow on one page:
If the gateway still rejects config after CLI commands
When validated writes are also refused, the cause is usually version skew rather than syntax. Check which binary you are running versus the version that last wrote the config:
user@host:~$ which openclaw :~$ openclaw --version :~$ openclaw config get meta.lastTouchedVersion 2026.7.1-2
An older binary talking to a config written by a newer version refuses service mutations, including forced reinstalls. Fix the PATH so the correct binary resolves first, then reinstall the service wrapper to lock everything to the same install: openclaw gateway install --force, then openclaw gateway restart. The CLI vs gateway config mismatch guide covers this case end to end.
Quick rule of thumb
Use openclaw config set for targeted changes, openclaw config patch for multi-key changes, openclaw configure for interactive full-config edits, and openclaw doctor after anything that felt wrong. If you do hand-edit the file, run openclaw config validate before restarting and be ready for the gateway to skip or fail the edit until it is fixed. Those four commands cover everything you would otherwise do by hand, and none of them produce a surprise .clobbered file.
Related fixes
Config that will not stick is often version skew in disguise, so CLI vs gateway config mismatches and rolling back a broken update safely are the natural companions. If the gateway refuses to start because the config lost its gateway.mode key, that is its own fix in the local mode guide. New to OpenClaw? Start with The Complete OpenClaw Guide.
Not Ready to Self-Host? Try ClawTrust
Building agents locally is powerful, but managing infrastructure, security, and scaling takes effort. ClawTrust provides managed OpenClaw hosting: your agents run securely in the cloud with automatic scaling, no DevOps overhead, and 24/7 monitoring.
This post contains affiliate links. If you buy through them, I may earn a small commission at no extra cost to you.
About The Author
