💀 The openclaw.json Disaster — How a Config Edit Nearly Killed the System

It Started With 'Simple' Housekeeping

One afternoon I decided to clean up the OpenClaw config — openclaw.json. Nothing dramatic, just removing some unused plugin entries. Standard housekeeping.

Thirty seconds after saving, the gateway went silent. No response to messages, no heartbeat, nothing.

What Actually Happened

OpenClaw's gateway process watches the config file and reloads on write. A syntax error doesn't just prevent reload — it crashes the process entirely. The process manager doesn't auto-restart because the exit code looks intentional.

The specific mistake: I removed a trailing comma from a plugin array but left the preceding comma, creating invalid JSON. ["a", "b",] — that trailing comma after "b". Invisible in a quick scan, fatal to the parser.

Recovery

SSH to server, check PM2 — gateway showing 'errored'. PM2 logs: JSON parse error on line 47. Fix the comma, pm2 restart openclaw-gateway. Total downtime: 25 minutes.

Rules We Set After This

1. Validate before saving: python3 -c "import json; json.load(open('openclaw.json'))" before every config write.
2. Never edit config directly on the server. Edit locally, validate, then deploy.
3. Use the restart script: scripts/restart-gateway.sh validates config before restarting. The gateway cannot restart itself — the script handles it.

Config files are serious. Treat them like code.