2026-05-08 OpenClaw 세션 상태 체크포인트와 게이트웨이 재시작 복구 — 헤드리스 임대 Apple Silicon 클라우드 Mac (HK / JP / KR / SG / US)

헬스 프로브를 안정적으로 맞춰 둔 직후, npm 업그레이드 도중 launchctl이 게이트웨이를 재시작하고 Slack에는 “봇이 모든 걸 잊었다”는 메시지가 쏟아집니다. 실제로는 모델이 잊은 것이 아니라 OPENCLAW_STATE_DIR을 스냅샷하지 않았거나 청소 작업이 CI 산출물 옆 스크래치를 지워 영구 경계가 달라진 경우입니다. 홍콩·도쿄·서울·싱가포르·미국의 임대 Mac mini M4에서는 절차가 답입니다. 세션 잔재를 코드 서명 키와 같은 수준의 데이터 플레인 상태로 다룹니다. 이번 2026-05-08 가이드에서는 체크포인트 디렉터리가 launchd 환경과 어떻게 얽히는지, 합성 트래픽으로 복구를 리허설하는 방법, 그리고 구조화 로깅·KeepAlive 트리아지·게이트웨이 업그레이드·롤백·새로운 파일 전송 플러그인 정책의 신호를 묶어 재시작을 지루하게 만드는 법을 설명합니다.

게이트웨이 재시작이 온콜을 속이는 이유

OpenClaw는 빠른 반복과 내구성 있는 자동화를 동시에 겨냥합니다. npm postinstall 이 전역을 바꾸거나 엔지니어가 CI와 동일 사용자로 SSH 하면 프로세스는 깨끗이 재시작돼도 다른 환경 의미를 읽어옵니다. 체크포인트 규율이 없으면 채팅뿐 아니라 webhook 중복 제거 캐시와 도구 허용 목록까지 잃습니다. 기대하는 영구 상태를 launchctl 레이블과 같은 README에 명시적으로 적으세요.

OPENCLAW_STATE_DIR 해부

계층으로 생각합니다:

• 세션 단서 — 재연결 후 운영자가 기대하는 대화 골격.
• 도구 캐시 — 짧은 게이트웨이 정지 후에도 남아야 하는 상한이 있는 메타데이터.
• Webhook 장부 — 중복 처리를 막는 중복 제거 키.

가능하면 계층마다 마운트나 ACL을 분리해 CI 정리가 어시스턴트 상태로 올라가 탐색하지 못하게 합니다. 동일 UID를 공유하면 병렬 CI 레인의 분리 가이드를 따릅니다.

launchd: ThrottleInterval, 종료 코드, 재기동

공격적인 KeepAlive에서는 사람이 깨닫기 전에 launchd가 게이트웨이를 재시작합니다. 재기동 트리아지와 함께 읽고 종료 코드를 기록하며 ThrottleInterval로 조밀한 크래시 루프를 막고 StandardOutPath에서 stderr 분기를 잡습니다. plist를 바꿨다면 승장 선언 전에 헬스 프로브 curl 매트릭스를 반드시 실행하세요.

유지보수 창 이전 체크포인트 플레이북

1. 동결: npm/Mint 핀을 고정하고 의존성 트리를 내보냅니다.
2. 스냅샷: tar 또는 가능하면 APFS 스냅샷으로 OPENCLAW_STATE_DIR.
3. 통지: 리플레이 테스트 중 중복 전달 가능성을 webhook 제공자에 알립니다.
4. 재시작: launchctl kickstart로 게이트웨이를 — 임시 kill -9는 피합니다.
5. 검증: 합성 인바운드로 중복 제거 키가 다시 채워지는지 확인합니다.

각 단계의 경과 분을 공개해 재무가 추가 증인 노드를 임대할지 장애 MTTR을 늘릴지 비교하게 합니다.

실패 유형표

징후	유력 원인	완화
재시작 후 고객에게 중복 이메일	중복 제거 캐시 소실	리플레이 안전한 webhook id + 외부 장부
업그레이드 후 도구 거부	정책 파일 미이전	플러그인 문서대로 허용 목록을 버전 관리
재시작 후 RSS 증가	스킬 번들 이중 로드	npm ls 트리와 tarball 백업 비교

플러그인과 파일 전송 근접성

2026-05-07 파일 전송 플러그인은 재시작 후에도 남아야 할 파일 시스템 의미를 추가합니다. 허용이 휘발성 환경 변수에만 있으면 재시작 후 조용히 범위가 줄어듭니다. 상태 디렉터리 아래에 Git 또는 봉인 설정으로 추적되는 정책 파일을 두고 청킹 규율과 결합해 재개 세션이 즉시 거대 fetch를 날리지 않게 합니다.

구조화 로그와 상관 ID

각 게이트웨이 이벤트에 세션 id, 게이트웨이 세대 카운터, 재시작 nonce를 넣어 Grafana가 바운스 전후를 분리할 수 있게 합니다. 리플레이 부하로 인바운드가 급증하면 리버스 프록시 가이드에 따라 nginx 엣지와 로그를 연결하세요.

8단계 복구 런북

1. 프로세스 시작 시각과 하트비트 편차로 재시작을 감지합니다.
2. 상태 디렉터리 tarball 해시와 실제 디렉터리를 비교합니다.
3. 스테이징 채널로 합성 CLI 대화를 보냅니다.
4. 멱등 토큰으로 webhook 샘플을 리플레이합니다.
5. 플러그인 정책이 의도치 않은 루트를 여전히 거부하는지 검증합니다.
6. 손상이 의심되면 npm 핀을 앞당겨 롤합니다.
7. 재시작 nonce와 함께 인시던트 타임라인을 기록합니다.
8. 증인 노드가 MTTR을 줄이는지 레트로를 잡습니다.

SLO 표

신호	임계값	조치
세션 재개 실패	재연결 중 > 0.5%	배포 동결·plist 환경 감사
중복 제거 충돌	모든 중복 부작용	리플레이 장부 무결성 점검
체크포인트 tarball 신선도	> 36시간 낡음	야간 스냅샷 잡 자동화

FAQ

질문	실무 답변 (2026-05-08)
ZFS/APFS 스냅샷?	리스 허용 시—프로바이더와 조율; 아니면 tarball을 객체 스토리지로.
체크포인트를 리전 간 동기?	아니오. 세션은 지역 로컬. 설정은 복제하고 라이브 대화 캐시는 복제하지 마세요.

스테이트풀 게이트웨이에 Mac mini M4가 맞는 이유

통합 메모리와 빠른 NVMe는 인시던트 동안 체크포인트 비교와 tarball diff를 실행 가능하게 합니다 — GB 규모 상태 트리를 압력 아래 비교할 때는 시끄러운 이웃보다 예측 가능한 하드웨어가 낫습니다. 예산 논의는 지역별 가격, 온보딩은 도움말, GUI 동의가 불가피하면 VNC도 함께 쓰세요.