---
read_when:
    - Gateway를 다시 시작하면 진행 중인 에이전트 작업이 손실되는지 알고 싶습니다
    - 에이전트 실행이 재시작, 충돌 또는 구성 다시 로드로 인해 중단되었습니다
    - Gateway가 다시 가동된 후 자동 세션 복구를 디버깅하고 있습니다
summary: 'Gateway 재시작 또는 충돌 후에도 유지되는 항목: 중단된 에이전트 턴은 자동으로 재개되고, 하위 에이전트와 백그라운드 작업은 복구되며, 대기열에 있는 전송 항목은 처리됩니다.'
title: 재시작 복구
x-i18n:
    generated_at: "2026-07-12T15:20:52Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 15
    provider: openai
    source_hash: b2701cb9cdc5aabffc395a2956260389cbe81a6c3ca2876830ef4ed83db2fb53
    source_path: gateway/restart-recovery.md
    workflow: 16
---

Gateway를 다시 시작해도 에이전트 상태는 손실되지 않습니다. 대화, 트랜스크립트,
예약된 작업, 백그라운드 작업 기록, 대기열에 있는 발신 메시지는 모두
디스크에 저장되며, 턴 도중 중단된 작업은 Gateway가 다시 가동된 후 감지되어
자동으로 재개됩니다. 수동 개입이 필요하지 않으며 구성할 것도 없습니다.
복구는 항상 활성화되어 있습니다.

이 페이지에서는 재시작 후에도 유지되는 항목, 중단된 작업을 감지하는 방법,
자동 재개의 작동 방식을 설명합니다.

## 재시작 후에도 유지되는 항목

| 상태                          | 저장소                                              | 재시작 시 동작                                                           |
| ----------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------- |
| 대화 기록                     | JSONL 트랜스크립트 + 디스크의 에이전트별 세션 저장소 | 변경되지 않으며, 세션은 저장된 트랜스크립트에서 계속됩니다               |
| 중단된 기본 세션 턴           | 세션 저장소의 복구 마커                             | 시작 후 몇 초 뒤 자동으로 재개됩니다                                     |
| 서브에이전트 실행             | SQLite(공유 상태 데이터베이스)                      | 부팅 시 레지스트리가 복원되고 중단된 실행이 재개됩니다                    |
| 백그라운드 작업               | SQLite(공유 상태 데이터베이스)                      | 부팅 시 조정되며, 소유자를 잃은 실행은 복구되거나 손실로 표시됩니다       |
| 대기열에 있는 발신 전달       | SQLite 전달 대기열                                  | 재시작 후 처리되며, 전달되지 않은 응답은 재시도됩니다                     |
| 예약된(Cron) 작업             | SQLite Cron 저장소                                  | 일정이 유지되며, 부팅 시 스케줄러가 다시 설정됩니다                      |
| 재시작 후속 처리              | SQLite 재시작 센티널                                | 재시작을 요청한 세션에 일회성 후속 처리가 전달됩니다                     |

## 정상적인 재시작은 먼저 작업이 끝나기를 기다립니다

요청된 재시작(`openclaw gateway restart`, 재시작이 필요한 구성 변경 또는
Gateway 업데이트)은 진행 중인 작업을 즉시 종료하지 않습니다. Gateway는
새 작업 수락을 중단한 다음, 활성 에이전트 턴과 백그라운드 작업이 완료될 때까지
드레인 예산 범위 내에서 대기합니다(기본값은 5분). 따라서 대부분의 재시작은
어떤 작업도 중단하지 않습니다.

드레인 예산 내에 완료할 수 없는 작업(또는 강제 재시작이나 충돌로 중단된 실행)만
중단되며, 중단하기 전에 영향을 받는 각 세션에 복구 표시가 지정됩니다.

## 중단된 작업을 감지하는 방법

턴이 완료되지 않은 세션은 서로 보완적인 두 메커니즘으로 표시됩니다.

- **종료 시:** 재시작 드레인 중에 활성 실행이 있는 모든 세션은 실행이
  중단되기 전에 세션 저장소에 복구 마커가 기록됩니다.
- **시작 시:** Gateway는 여전히 실행 중이라고 표시되어 있지만 새 프로세스에
  활성 소유자가 없는 세션을 세션 저장소에서 검색합니다. 이를 통해 종료 코드가
  실행되지 않은 강제 종료와 심각한 충돌도 감지합니다. 오래된 트랜스크립트 잠금
  파일도 동시에 정리됩니다.

## 자동 재개

시작 후 몇 초가 지나면 Gateway는 표시된 각 세션을 다시 디스패치하며,
이전 턴이 재시작으로 중단되었으므로 기존 트랜스크립트에서 계속하라는
합성 시스템 메시지를 에이전트에 전달합니다. 최종 응답이 이미 생성되었지만
전달되지 않은 경우에는 해당 텍스트가 포함되므로, 에이전트가 작업을 다시
수행하지 않고 이를 전달할 수 있습니다. 복구는 지수 백오프를 적용하여
최대 3회 재시도됩니다.

재개하기 전에 Gateway는 트랜스크립트 끝부분에서 안전하게 계속할 수 있는지
확인합니다. 안전하지 않은 경우(예: 턴이 오래된 대기 중 승인에서 끝난 경우)
세션을 무조건 다시 실행하지 않습니다. 대신 에이전트가 사용자에게 마지막
요청을 다시 보내 달라는 짧은 알림을 게시합니다.

OpenClaw는 중단된 읽기 전용 [코드 모드](/ko/reference/code-mode) 작업도
재구성할 수 있습니다. 코드 모드는 이러한 실행을 재시작 안전 상태로 표시하고,
부작용을 일으키는 카탈로그 도구 또는 Plugin 네임스페이스를 실행 전에
거부합니다. 재시작 시점이 `wait` 제어에 해당하면 새 Gateway는 트랜스크립트에서
턴을 재구성하며, 모델이 해당 플래그를 생략하거나 해제하더라도 재구성된 실행이
계속 재시작 안전 상태를 유지하도록 강제합니다. 호스트는 재시작 후 코드 모드가
비활성화된 경우를 포함하여, 재구성된 전체 턴을 감사된 읽기 전용 코어 도구와
명시적으로 재실행 안전성이 보장된 Plugin 도구로 제한합니다. 부작용을 일으키는
작업에는 중복 쓰기 위험을 감수하는 대신 재전송 알림 보호가 계속 적용됩니다.

### 서브에이전트

서브에이전트 실행은 공유 SQLite 상태 데이터베이스에 영구 저장되므로,
서브에이전트 레지스트리가 프로세스 종료 후에도 유지됩니다. 부팅 시
레지스트리가 복원되며, 중단된 서브에이전트 세션은 원래 작업 컨텍스트와 함께
재개됩니다. 두 가지 안전장치가 적용됩니다.

- 2시간보다 오래전에 중단된 실행은 재개하는 대신 완료 처리되므로,
  밤새 중단되었던 Gateway가 오래된 작업을 되살리지 않습니다.
- 복구에 반복적으로 실패하는 세션은 멈춤 상태로 툼스톤 처리되므로
  복구가 무한히 반복되지 않습니다.

### 백그라운드 작업

[백그라운드 작업 레지스트리](/ko/automation/tasks)는 SQLite를 기반으로 하며
부팅 시와 주기적인 간격으로 조정됩니다. 완료된 실행이 기록한 영구적인 결과는
복구되고, 소유 프로세스가 사라진 실행은 영원히 멈춰 있지 않도록 유예 기간 후
손실된 것으로 표시됩니다.

### 에이전트가 요청한 재시작

에이전트 자체가 재시작을 트리거하는 경우(구성 변경 적용, Gateway 업데이트
또는 명시적 재시작 요청), 프로세스가 종료되기 전에 재시작 센티널이 SQLite에
기록됩니다. 부팅 후 Gateway는 결과를 원래 채팅에 다시 게시하고 일회성 후속
턴을 디스패치하므로, 에이전트는 동일한 채널과 스레드에서 중단한 정확한
지점부터 계속합니다.

## 안전장치 및 관찰 가능성

- **충돌 루프 차단기:** 5분 이내에 3회의 비정상 부팅이 발생하면 차단기가
  작동하여 다음 부팅 시 자동 시작 사이드 서비스를 억제하므로, 충돌하는 Gateway가
  문제를 증폭시키지 않습니다. 비정상 부팅 기간이 지나면 복구됩니다.
- **메트릭:** 복구 활동은 [Prometheus](/ko/gateway/prometheus)를 통해
  `openclaw_session_recovery_total` 및
  `openclaw_session_recovery_age_seconds`로 내보내집니다.
- **로그:** 복구 결정은 `main-session-restart-recovery` 및
  `subagent-interrupted-resume` 하위 시스템에 기록됩니다.

## 재개되지 않는 항목

- 다른 소유자가 이미 처리하므로 기본 세션 복구에서 제외되는 세션:
  서브에이전트 세션(서브에이전트 복구), Cron 세션(스케줄러가 일정에 따라
  다시 실행), ACP 관리 세션(연결된 IDE 또는 클라이언트가 재개를 담당).
- 트랜스크립트 끝부분에서 안전하게 계속할 수 없는 세션. 이러한 세션은
  자동으로 다시 실행되는 대신 위에서 설명한 재전송 알림을 받습니다.
- 수락되지 않은 작업: 드레인 기간에 도착한 메시지는 종료 중인 프로세스의
  대기열에 조용히 추가되지 않고 명시적인 재시작 오류와 함께 거부됩니다.