재시작 복구

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

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

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

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

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

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

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

다음 세 가지 상호 보완적 메커니즘이 턴을 완료하지 못한 세션을 표시합니다.

• 턴 수락 시: 기존 기본 세션의 일반 텍스트 턴에서는 모델 또는 before_agent_reply 훅을 실행하기 전에 Gateway가 하나의 SQLite 트랜잭션에서 사용자 메시지를 추가하고, 세션을 실행 중으로 표시하며, 복구 전송 클레임을 기록합니다. Control UI는 started 확인 응답을 반환하기 전에 이 작업을 수행하며, 채널 디스패치는 준비된 턴이 에이전트 실행을 채택할 때 이 작업을 수행합니다. 명령, 첨부 파일, 턴별 재정의, 보류 중인 전송, 이전 중지 힌트, Plugin 소유 세션 및 실행 훅이 있는 턴은 각각의 특수한 수락 경로를 유지합니다. before_agent_reply 훅이 설치되어 있으면 수락 시 해당 단계도 기록됩니다. 복구는 호출 도중 중단된 훅을 절대 재생하지 않습니다. 처리되지 않은 훅이 완료되면 해당 체크포인트가 결과를 기록하지만, 훅이 활성 상태인 동안 복구는 계속 실패 시 닫힘 방식으로 처리됩니다. 체크포인트만으로는 재시작 후 동일한 Plugin 코드와 구성이 로드되었음을 증명할 수 없기 때문입니다. 처리된 텍스트 결과와 무응답 결과는 결정론적 확정을 위해 별도로 체크포인트됩니다. 이전 버전이 기록한 영구 복구 클레임에는 소스 소유권 표시가 없으므로 업그레이드 중에도 동일한 실패 시 닫힘 훅 검사를 적용받습니다.
• 종료 시: 재시작 드레인 중에는 활성 실행이 있는 모든 세션에 대해 실행을 중지하기 전에 세션 저장소에 복구 표시가 기록됩니다.
• 시작 시: Gateway는 새 프로세스에 활성 소유자가 없는데도 여전히 실행 중이라고 표시된 세션을 찾기 위해 세션 저장소를 검사합니다. 이를 통해 종료 코드가 실행되지 않은 하드 충돌과 강제 종료도 감지합니다. 오래된 트랜스크립트 잠금 파일도 동시에 정리됩니다.

자동 재개

시작 후 몇 초가 지나면 Gateway는 표시된 각 세션을 다시 디스패치하며, 이전 턴이 재시작으로 인해 중단되었으므로 기존 트랜스크립트에서 계속하라는 합성 시스템 메시지를 에이전트에 전달합니다. 최종 응답이 이미 생성되었지만 전송되지 않았다면 해당 텍스트도 포함되므로 에이전트가 작업을 다시 수행하지 않고 이를 전송할 수 있습니다. 복구는 지수 백오프를 적용하여 최대 3번 재시도합니다. 모든 재시도는 하나의 영구 디스패치 식별자를 재사용하므로, 모호한 연결 실패로 인해 동일한 복구가 두 번 시작되지 않습니다. 완료되었거나 재개할 수 없는 Control UI 턴도 제한된 기간 동안 영구 멱등성 툼스톤을 유지하므로, 다시 연결된 보낼 편지함은 요청을 재실행하지 않고 해당 턴을 폐기할 수 있습니다.

메시지 도구만 사용한 응답은 두 번째 영구 상관관계를 사용합니다. 동일 대화의 최종 전송이 채널에 도달하기 전에 Gateway는 정확한 세션과 소스 턴에 미해결 전송 의도를 기록합니다. 공급자의 성공이 확인되면 이를 영구 전송 완료 영수증으로 확정하고, 실패가 확인되면 이를 지웁니다. 복구는 도구를 다시 실행하지 않고 전송 완료 영수증을 완료 처리합니다. 충돌로 인해 공급자 결과를 알 수 없게 되면 외부 효과를 재생하지 않고 실패 시 닫힘 방식으로 처리합니다.

전송된 응답은 소스 메시지 ID와 함께 트랜스크립트에도 복제됩니다. 최종 복제는 별도의 영수증 키를 사용하므로, 동일한 공급자 멱등성 키를 사용하는 진행 상황 전송이 최종 표시를 가릴 수 없습니다. 이전 턴의 진행 상황 전송과 영수증은 현재 턴을 완료할 수 없습니다. 영구 채널 인그레스 클레임만 메시지 작업 권한을 복원할 수 있습니다. 재개된 실행은 요청자 신원과 동일 채널/스레드 제한을 포함하여 원래 소스 전송 모드와 소스 상관관계를 유지하므로, 복구 중에 다시 재시작되더라도 동일한 영수증이 계속 권위 있는 근거로 유지됩니다. 복원 가능한 채널 권한이 없는 메시지 도구 전용 턴은 실패 시 닫힘 방식으로 처리되며 일회성 재전송 알림을 받습니다.

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

OpenClaw는 중단된 읽기 전용 Code Mode 작업도 재구성할 수 있습니다. Code Mode는 이러한 실행을 재시작에 안전한 것으로 표시하고, 부작용을 일으키는 카탈로그 도구 또는 Plugin 네임스페이스가 실행되기 전에 거부합니다. wait 제어에서 재시작이 발생하면 새 Gateway가 트랜스크립트에서 턴을 재구성하며, 모델이 해당 플래그를 생략하거나 지우더라도 재구성된 실행이 재시작 안전성을 유지하도록 강제합니다. 호스트는 재시작 후 Code Mode가 비활성화된 경우를 포함하여 재구성된 전체 턴을 감사된 읽기 전용 핵심 도구와 명시적으로 재생 안전한 Plugin 도구로 제한합니다. 부작용을 일으키는 작업은 중복 쓰기를 감수하지 않고 재전송 알림으로 계속 보호됩니다.

하위 에이전트

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

• 2시간보다 오래전에 중단된 실행은 재개되지 않고 완료 처리되므로, Gateway가 밤새 중단되었더라도 오래된 작업을 되살리지 않습니다.
• 반복적으로 복구에 실패하는 세션은 교착 상태로 툼스톤 처리되어 복구가 무한히 반복되지 않도록 합니다.

백그라운드 작업

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

에이전트가 요청한 재시작

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

안전장치 및 관찰 가능성

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

재개되지 않는 항목

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