OpenClaw won't start after a config edit: crash loops, the breaker, and the clean fix

Why the crash happens later than the edit

Two different code paths judge your config. While the gateway runs, it watches ~/.openclaw/openclaw.json and hot-applies changes, but an invalid edit is skipped with a quiet log line (“config reload skipped (invalid config)”) while the current runtime config stays active. At boot, the standard is stricter and terminal: “OpenClaw only accepts configurations that fully match the schema”: unknown keys cause it to refuse to start rather than guess. So the classic incident reads like a mystery: you edited config last Tuesday, everything kept working, and today’s reboot produced a gateway that won’t come up. The edit was never valid; Tuesday’s gateway just never re-read it.

The trap that causes most of these

The most common invalid key isn’t a typo. It’s a key that’s real, just newer than your install. Docs describe the current release; if you’re pinned to an older version (deliberate in any managed setup), a copy-pasted config block from the docs can reference settings your binary doesn’t know, and the strict schema treats them exactly like typos. The discipline that prevents it costs one command:

openclaw config validate   # checks against YOUR install's schema
# only then:
openclaw gateway restart

Recovering a gateway that won’t start

• Read the error. openclaw logs (or --follow) shows the boot failure naming the offending path; the message is specific.
• Restore last-known-good. The gateway keeps a trusted copy of the last config that booted successfully; openclaw doctor --fix restores it (never automatically; the choice stays yours). Rejected configs aren’t lost: they’re saved beside the file with a .rejected timestamp suffix.
• Re-apply what you meant. Copy only the intended keys back from the rejected file using openclaw config set, validate, then restart. The docs’ own advice if you hand-edit: keep the full JSON5 file intact, not just the fragment you wanted to change.

The crash-loop breaker, explained

If the gateway crashes three times uncleanly within five minutes, a breaker trips: on the next boot, channel plugins and other auto-started services stay down while the control plane comes up, leaving you a stable process to inspect instead of a restart storm. The log line says exactly what happened: “channel autostart suppressed by crash-loop breaker.” It heals itself: once the gateway stays stable through the unclean-boot window, deferred channels start on their own, no extra restart needed. Or start one immediately with openclaw gateway call channels.start. Two adjacent behaviors people confuse with it: each channel also has its own crash-backoff ladder (“auto-restart attempt N/10” in the logs), and on macOS, launchd applies its own respawn-protection gate after a crash burst; launchctl kickstart -k clears that one.

Making this a non-event

The whole failure class reduces to habit: validate before every restart, keep the pin in mind when copying config from docs, and treat restarts as the moment config truth gets re-checked, because it is. On managed pods this discipline is the operator’s job rather than yours, which is most of the argument for having an operator; self-hosting, the two commands above are the difference between a thirty-second fix and an evening of archaeology.