restart-guard

name	restart-guard
description	Safely restart the OpenClaw Gateway with context preservation, health monitoring, and failure notification. Use when the agent needs to restart the Gateway (config changes, model switches, plugin reloads, or any reason requiring a restart). Handles pre-restart context saving, guardian process spawning, gateway restart triggering, post-restart verification, and fallback notifications.

Restart Guard

Safely restart the OpenClaw Gateway with context preservation and automated health verification.

Prerequisites

• commands.restart: true in openclaw.json
• Agent has gateway and exec tools allowed
• Config file ready (copy config.example.yaml, fill in values, pass via --config)

Flow

write_context.py → restart.py → [SIGUSR1] → guardian.py monitors → postcheck.py verifies

1. Write Context

python3 <skill-dir>/scripts/write_context.py \
  --config <config-path> \
  --reason "config change" \
  --verify 'openclaw health --json' 'ok' \
  --resume "report restart result to user"

Generates a context file with YAML frontmatter (machine-readable: reason, verify commands, resume steps, rollback path) and Markdown body (human-readable notes).

2. Restart

python3 <skill-dir>/scripts/restart.py --config <config-path> --reason "config change"

Validates context → checks cooldown lock → backs up openclaw.json → spawns guardian (detached, survives restart) → sends pre-restart notification → triggers gateway.restart.

3. Post-Restart Verification

After gateway pings the session back:

python3 <skill-dir>/scripts/postcheck.py --config <config-path>

Reads verify commands from context frontmatter, runs each, compares output to expected value. Returns JSON (--json) or human-readable report.

4. Guardian Behavior

Runs independently. Polls openclaw health --json every N seconds.

• Success: sends notification, releases lock, exits 0
• Timeout: runs diagnostics (openclaw doctor, log tail), sends failure notification with diagnostics, releases lock, exits 1

Notification priority: OpenClaw message tool (primary) → all configured fallback channels broadcast (Telegram/Discord/Slack/generic webhook). Multiple channels can be enabled simultaneously.

Safety

• Cooldown lock: minimum interval between restarts (default 600s)
• Consecutive failure limit: stops auto-restart after N failures (default 3)
• Config backup: openclaw.json backed up before each restart
• Guardian detached: start_new_session=True (setsid), not exec background

Troubleshooting

See references/troubleshooting.md for common issues (lock cleanup, notification failures, verification mismatches).