openclaw-safe-restart

Safe gateway restart scripts for OpenClaw with full session continuity.

When OpenClaw's gateway restarts, agents wake up with no memory of what they were doing. Any mid-task work is silently dropped — users have to manually prompt each bot to continue. These scripts fix that.

What it does

Before restart:
  1. Lock file — prevents concurrent restarts racing each other
  2. Validates openclaw.json — bails if invalid JSON (no restart on broken config)
  3. Backs up config → ~/.openclaw/config-backups/openclaw-TIMESTAMP.json
  4. Snapshots active session list → config-backups/sessions-TIMESTAMP.json

Restart:
  5. launchctl bootout → pkill → bootstrap (safe launchd flow)
  6. Kicks companion app

After restart:
  7. Polls every 2s until gateway is healthy (up to 60s)
  8. Immediately resumes ALL active sessions by session ID
     — every conversation, every agent, not just one per bot
     — triggering session is skipped (it already knows)

On failure:
  9.  Diffs broken config vs backup → saves config-diff-TIMESTAMP.txt
  10. Rolls back config, restarts, runs same health poll loop
  11. If recovered → fires system event alert with triggering session + diff path
  12. If still down → fires CRITICAL alert + prints manual recovery steps

Usage

# Clone
git clone https://github.com/alexcf/openclaw-safe-restart.git
cd openclaw-safe-restart
chmod +x gateway-restart.sh post-restart-resume.sh

# Run (pass your current session key for best rollback alerts)
bash gateway-restart.sh "agent:kit:discord:channel:YOUR_CHANNEL_ID"

# Or without session key
bash gateway-restart.sh

To find your session key:

openclaw sessions --all-agents --active 60 --json | python3 -c "
import sys, json
for s in json.load(sys.stdin).get('sessions', []):
    key = s.get('key','')
    if 'subagent' not in key and ':cron:' not in key:
        print(s.get('agentId'), key)
"

Requirements

• macOS with OpenClaw running via launchd
• python3 in PATH (standard on macOS)
• Works with single or multiple agents/bots

Files

File	Description
gateway-restart.sh	Main script — validates, backs up, restarts, health-checks, rollback
post-restart-resume.sh	Fires resume events into all active sessions by session ID

Key design decisions

Why not openclaw gateway restart?
That command unloads the launchd plist, which can leave the service in a broken state. This script uses launchctl bootout + bootstrap which is the safe launchd flow.

Why target by session ID?
openclaw system event only fires into the default agent's main session. If you have two Discord channels and a WhatsApp open across multiple bots, you need to target each session individually — which requires openclaw agent --session-id.

Why skip the triggering session?
The session that initiated the restart doesn't need a resume event — it's already in context. Sending one would just create noise.

Why diff on rollback?
When a config change breaks the gateway, you want to know exactly what changed. The diff is saved to ~/.openclaw/config-backups/config-diff-TIMESTAMP.txt and included in the alert message.

Integrating with your agent

When your agent triggers a gateway restart (e.g. after editing config), pass the current session key:

bash ~/path/to/gateway-restart.sh "$CURRENT_SESSION_KEY"

The script will:

• Resume all other active sessions when the gateway comes back
• Name your session in any rollback alerts
• Skip sending you a resume event (you're already continuing)

License

MIT