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.

CODEBLOCK0

1. 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
INLINECODE2	INLINECODE3	Tool returned, agent never processed it
INLINECODE4 (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

CODEBLOCK1

Deploys three components:

• - boot-resume-check.sh → INLINECODE13
• INLINECODE14 → systemd drop-in (triggers script on every gateway start)
• INLINECODE15 → systemd user service (triggers script on system wake from sleep/suspend)

Manual

CODEBLOCK2

Verify

CODEBLOCK3

Expected output:
CODEBLOCK4

Test

1. 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. INLINECODE16
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:

CODEBLOCK5

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

Configuration

Variable	Default	Description
INLINECODE19	INLINECODE20	How far back to scan for interrupted sessions
INLINECODE21

20s | Delay before injecting the resume event |

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

Features

• - Dual trigger — covers both gateway restart (ExecStartPost) and system sleep/wake (systemd sleep.target)
• Multi-agent support — scans all agents under ~/.openclaw/agents/, not just INLINECODE25
• Smart filtering — skips system, heartbeat, cron, and subagent sessions automatically
• Deduplication — respects restart-resume.json to avoid double-resuming planned restarts
• Log rotation — auto-truncates log at 1000 lines
• Error visibility — Python and cron errors are logged, not swallowed
• Unique job names — timestamp-based to prevent conflicts on rapid restarts

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: INLINECODE27

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

Limitations

• - 20-minute scan window (configurable) — sessions idle longer than this are not resumed
• Resume prompt is generic — the agent relies on session context for continuity
• Telegram/Discord message queues already handle unprocessed incoming messages — this skill targets mid-execution interruptions
• Requires systemd (Linux); macOS users need manual launchd setup

Uninstall

CODEBLOCK6