OpenClaw Gateway Crash: Auto-Repair Without SSH

You can set up your OpenClaw bot to auto-repair a crashed gateway without any manual intervention. This guide covers the full repair sequence — from simple systemd restarts to config corruption recovery — and how to make it completely hands-off.

What happens when the gateway crashes

When OpenClaw's gateway process dies, your bot stops responding immediately. The crash looks different depending on the cause:

Manual repair (the SSH approach)

If you're already SSHed in, here's the fastest path to a working gateway:

journalctl -u openclaw-gateway -n 50 --no-pager
# or: openclaw logs --tail 50

# Validate JSON
node -e "require(fs.readFileSync(process.env.HOME + '/.openclaw/workspace/openclaw.json', 'utf8'))"
# Better: use openclaw's built-in check
openclaw doctor

# Backup first
cp ~/.openclaw/workspace/openclaw.json ~/.openclaw/workspace/openclaw.json.bak

# Auto-repair
openclaw doctor --fix

# Verify token is still there
grep -c "botToken" ~/.openclaw/workspace/openclaw.json

openclaw gateway restart
sleep 5
openclaw gateway status
# Should show: running (PID: XXXXX)

Automated repair: no SSH required

The DIY approach requires you to be awake, have SSH access, and know which fix to apply. That's fine for your own machine during business hours. It's a problem at 3am from your phone.

There are two approaches to full automation:

Approach A: systemd with auto-restart

For simple crashes (not config corruption), systemd can restart automatically:

# /etc/systemd/system/openclaw-gateway.service
[Service]
Restart=on-failure
RestartSec=10
StartLimitBurst=5
StartLimitInterval=300

Works for: clean crashes, OOM kills, SIGTERM. Fails for: config corruption (gateway will fail to start and systemd eventually gives up).

Approach B: repair agent (handles all failure modes)

Mechanic Bot runs a repair loop that handles every failure mode in order:

Phase 1: Try systemd restart
  → Success: notify + log. Done.
  
Phase 2: Config check
  → If broken: backup → deep-merge repair → restart
  → Config repair preserves: botToken, API keys, channel settings
  
Phase 3: Environment check
  → Check disk space: if >90%, clear logs + npm cache first
  → Check Node version: if incompatible, re-link nvm version
  
Phase 4: Hard reset
  → pkill -9 gateway process
  → Start fresh
  
Phase 5: Escalate
  → All above failed → Telegram + email alert to operator
  → Detailed diagnostics included in alert

The critical difference in Phase 2: config repair uses a deep-merge, not a full overwrite. Your Telegram bot token stays intact.

Setting up automated repair

Mechanic Bot installs a lightweight agent that handles all of this automatically:

curl -fsSL https://mechanicbot.io/onboard.sh | sudo bash -s -- \
  --token YOUR_INSTALL_TOKEN

curl -fsSL https://mechanicbot.io/onboard-mac.sh | bash -s -- \
  --token YOUR_INSTALL_TOKEN

What you see when a crash happens

With Mechanic running, the typical experience after a gateway crash:

• T+0s: Gateway dies
• T+30s: Mechanic detects it
• T+45s: Repair attempt begins
• T+90s (typical): Gateway back online
• T+95s: You get a Telegram message: "✅ Fixed in 90s — systemd restart"
• Morning: Full repair summary in your daily health report

You don't need to do anything. You find out it happened, not that it needs fixing.