Restart recovery
기준일: 2026-07-26
공식 기준: Restart recovery
Restart recovery 문서는 OpenClaw 공식 문서(gateway/restart-recovery)를 한국어로 정리한 가이드입니다. What survives a gateway restart or crash: interrupted agent turns resume automatically, subagents and background tasks recover, queued deliveries drain 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.
핵심 요약
What survives a gateway restart or crash: interrupted agent turns resume automatically, subagents and background tasks recover, queued deliveries drain
한국어 가이드 범위: gateway/restart-recovery 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.
문서 구성
공식 문서의 주요 섹션은 다음과 같습니다.
- What survives a restart
- Graceful restarts drain first
- How interrupted work is detected
- Automatic resume
- Subagents
- Background tasks
- Agent-requested restarts
- Safety valves and observability
- What is not resumed
상세 내용
본문
Restarting the gateway does not lose agent state. Conversations, transcripts, scheduled jobs, background task records, and queued outbound messages all live on disk, and work that was interrupted mid-turn is detected and resumed automatically after the gateway comes back up. Recovery is always on and normally needs no manual intervention. Repeatedly failing recovery is bounded and may quarantine one session until you inspect or replace it.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
What survives a restart
| State | Storage | Behavior across restart |
|---|---|---|
| Conversation history | Per-agent SQLite database | Untouched; sessions continue from the stored transcript |
| Interrupted main-session turn | Per-agent SQLite session row and transcript | Automatically resumed or reconciled a few seconds after startup |
| Subagent runs | SQLite (shared state database) | Registry restored on boot; interrupted runs resumed |
| Background tasks | SQLite (shared state database) | Reconciled on boot; orphaned runs recovered or marked lost |
| Queued outbound deliveries | SQLite delivery queue | Drained after restart; undelivered replies are retried |
| Scheduled (cron) jobs | SQLite cron store | Schedules persist; the scheduler re-arms on boot |
| Restart continuation | SQLite restart sentinel | One-shot follow-up dispatched to the session that asked for the restart |
Graceful restarts drain first
A requested restart (openclaw gateway restart, a config change that requires a restart, or a gateway update) does not kill in-flight work immediately. The gateway stops accepting new work, then waits for active agent turns and background tasks to finish, up to a drain budget (5 minutes by default). Most restarts therefore interrupt nothing at all.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
How interrupted work is detected
Three complementary mechanisms mark sessions whose turn did not finish:
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
주요 항목:
- At turn admission: for an ordinary text turn on an existing main session,
- At shutdown: during the restart drain, every session with an active run
- At startup: the gateway scans session stores for sessions that still
Automatic resume
A few seconds after startup, the gateway re-dispatches each marked session with a synthetic system message telling the agent its previous turn was interrupted by a restart and to continue from the existing transcript. If a final reply had already been produced but not delivered, its text is included so the agent can deliver it instead of redoing the work.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
Subagents
Subagent runs are persisted in the shared SQLite state database, so the subagent registry survives the process. On boot the registry is restored and interrupted subagent sessions are resumed with their original task context. Two safety valves apply:
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
주요 항목:
- Runs interrupted more than 2 hours ago are finalized instead of resumed, so
- A session that repeatedly fails to recover is tombstoned as wedged so
Background tasks
The background task registry is SQLite-backed and reconciled on boot and on a periodic interval: durable outcomes recorded by finished runs are recovered, and runs whose owning process disappeared are marked lost after a grace period instead of hanging forever.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
Agent-requested restarts
When the agent itself triggers a restart (applying a config change, updating the gateway, or an explicit restart request), a restart sentinel is written to SQLite before the process exits. After boot the gateway posts the outcome back to the originating chat and dispatches a one-shot continuation turn so the agent picks up exactly where it left off, on the same channel and thread.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
Safety valves and observability
suppresses auto-start side services on the next boot, so a crashing gateway does not amplify itself. It recovers once the unclean-boot window drains.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
주요 항목:
- Crash-loop breaker: 3 unclean boots within 5 minutes trip a breaker that
- Main-session attempt budget: three charged automatic dispatch attempts
- Metrics: recovery activity is exported via
- Logs: recovery decisions are logged under the
What is not resumed
handles them: subagent sessions (subagent recovery), cron sessions (the scheduler re-runs on schedule), and ACP-managed sessions (the connected IDE or client owns the resume).
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
주요 항목:
- Sessions excluded from main-session recovery because another owner already
- Sessions whose transcript tail cannot be safely continued; these get the
- Work that was never admitted: messages arriving during the drain window are
- Standalone embedded turns cannot take over a main session with pending
실습 체크리스트
- 공식 문서와 로컬 버전을 대조합니다:
https://docs.openclaw.ai/gateway/restart-recovery - 관련 CLI는
openclaw --help및 하위 명령--help로 옵션을 확인합니다. - 설정 변경 시
openclaw config/openclaw doctor로 유효성을 검사합니다. - Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.
관련 링크
이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.