Boot Resume

Boot Resume

Zero-cooperation session recovery after gateway restart. No checkpoints, no hooks, no agent involvement — just reads the evidence and picks up where it left off.

Problem

When the gateway restarts, any in-flight agent turn dies mid-execution. Session history is preserved on disk, but the agent doesn't know it needs to continue. Users must manually tell each interrupted session to resume.

Checkpoint-based approaches require the agent to save state _before_ dying. Unexpected kills (SIGKILL, OOM, power loss) bypass this entirely.

Solution

A deterministic shell script runs on every gateway start via systemd ExecStartPost. No LLM in the detection loop.

┌─────────┐     ┌──────────┐     ┌──────────┐
│  Scan   │ ──▶ │  Detect  │ ──▶ │  Resume  │
│sessions │     │  JSONL   │     │ cron add │
│ .json   │     │  tail    │     │--sys-evt │
└─────────┘     └──────────┘     └──────────┘

1. Scan — finds sessions updated within the last 20 minutes 2. Detect — reads the last 5 JSONL lines to classify session state 3. Resume — schedules a one-shot openclaw cron add --system-event --wake now to inject a continuation prompt

Key insight: the JSONL session files already contain all the evidence needed to detect an interruption — no pre-save required.

Detection Rules

| Last JSONL Entry | Status | Meaning | |---|---|---| | toolResult | INTERRUPTED | Tool returned, agent never processed it | | assistant (empty text) | INTERRUPTED | Tool call dispatched, killed before response | | user (non-trivial) | INTERRUPTED | Message received, never processed | | assistant (with text) | COMPLETE | Session ended normally — skip | | user (trivial: "ok", emoji) | TRIVIAL | No meaningful request pending — skip |

Install

One command

bash {baseDir}/install.sh

Deploys three components:

Manual

cp {baseDir}/scripts/boot-resume-check.sh ~/.openclaw/workspace/scripts/
chmod +x ~/.openclaw/workspace/scripts/boot-resume-check.sh
mkdir -p ~/.config/systemd/user/openclaw-gateway.service.d
cp {baseDir}/templates/boot-resume.conf ~/.config/systemd/user/openclaw-gateway.service.d/
cp {baseDir}/templates/boot-resume-wake.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable boot-resume-wake.service

Verify

systemctl --user restart openclaw-gateway
sleep 20
cat /tmp/openclaw/boot-resume.log

Expected output:

[boot-resume] now=... cut=... (20min window)
[boot-resume] scanning agent: main
[boot-resume] candidates: 0 (agent=main)
[boot-resume] done

Test

1. Send a message that triggers a multi-step task (web search, code analysis, etc.) 2. Wait for the agent to start processing (tool calls in flight) 3. systemctl --user restart openclaw-gateway 4. Agent resumes automatically within ~35 seconds

Slash Command

When invoked as /boot-resume, run the script with --no-wait to skip the startup delay:

bash {baseDir}/scripts/boot-resume-check.sh --no-wait

Report results to the user: which sessions were resumed, or that none were found.

Configuration

| Variable | Default | Description | |----------|---------|-------------| | WINDOW_MINUTES | 20 | How far back to scan for interrupted sessions | | DELAY | 20s | Delay before injecting the resume event |

Edit at the top of scripts/boot-resume-check.sh.

Features

Comparison

| Approach | Pre-save required | Survives SIGKILL | LLM-free | |---|---|---|---| | Checkpoint / snapshot files | Yes | No | No | | Pre-restart state dump | Yes | No | No | | Session history replay | Yes | Partial | No | | Post-hoc JSONL detection (this skill) | No | Yes | Yes |

Logs

Output: /tmp/openclaw/boot-resume.log

Each run logs: timestamp, scan window, candidate count, per-session status, and whether a resume job was armed.

Limitations

Uninstall

rm ~/.config/systemd/user/openclaw-gateway.service.d/boot-resume.conf
systemctl --user disable boot-resume-wake.service 2>/dev/null
rm ~/.config/systemd/user/boot-resume-wake.service
systemctl --user daemon-reload
rm ~/.openclaw/workspace/scripts/boot-resume-check.sh
rm -rf ~/.openclaw/workspace/skills/boot-resume

| Variable | Default | Description | |----------|---------|-------------| | WINDOW_MINUTES | 20 | How far back to scan for interrupted sessions | | DELAY | 20s | Delay before injecting the resume event |

Edit at the top of scripts/boot-resume-check.sh.