OpenClaw 업데이트에서 게이트웨이 재시작까지의 자동화 파이프라인 구축

들어가며

OpenClaw가 워낙 업데이트가 잦다 보니 에이전트에게 "업데이트하고 재시작까지 해줘"라고 요청하는 일이 잦다. 그런데 실제 운영에서는 한 가지 문제가 생각보다 자주 발행한다. 방금 전에도 OpenClaw 2026.4.22 업데이트 자체는 정상적으로 끝났는데, 게이트웨이 재시작까지 이어지지 않고 진행이 중단됐다. 즉 OpenClaw 코드나 패키지는 최신 상태로 올라갔지만, 실제로 떠 있는 프로세스는 이전 버전을 계속 잡고 있는 상태인 것이다.

CLI 명령으로는 2026.4.22로 보이지만, 실제 Telegram이나 Discord 같은 채널에서는 여전히 2026.4.15로 표시됨.

이런 상황은 겉으로 보면 "업데이트 완료"처럼 보인다. 하지만 실제 런타임은 바뀌지 않았기 때문에 새 버전 반영이 안 되거나 설정 변경이 적용되지 않고, 나중에 이상 동작 원인을 추적하기도 어려워진다. 이번 글에서는 이 문제를 해결하기 위해 OpenClaw 업데이트 작업을 phase1 / phase2의 2단계 런북 스크립트로 분리한 과정을 정리한다. 이 글도 나중에 내가 까먹으면 찾아서 보려는 목적이 크다. 글이 꽤 길어질 것 같다.

 

첫 시도 : 단일 스크립트

처음에는 단순하게 생각했다. 하나의 스크립트 안에서 아래 순서로 끝내면 될 것 같았다.

1. 현재 상태 백업
2. OpenClaw 업데이트 실행
3. 게이트웨이 재시작
4. 재시작 후 상태 점검
5. 결과 보고

문제는 재시작 대상이 바로 현재 실행 중인 OpenClaw 자신이라는 점이다. OpenClaw가 자기 자신을 업데이트하고 자기 자신을 재시작하는 순간 현재 컨텍스트가 끊길 수 있다. 그 상태에서 뒤이어 실행되어야 할 검증 단계가 유실되거나 보고가 누락될 수 있다. 아니면 부분 성공 상태로 끝날 가능성도 있다. 실제로 dry run을 돌려봤더니 다음과 같은 문제가 드러났다.

• OpenClaw 버전 업데이트는 성공
• 게이트웨이 재시작이 진행되지 않음.
• 또는 게이트웨이 재시작 직후 현재 세션이 끊겨서 후속 검증이 실행되지 않음
• 결과적으로 “업데이트는 된 것 같은데 확실하지 않은 상태”가 남음

이 상태는 운영 자동화라고 보기 힘든 수준이다. 업데이트 성공보다 중요한 것은 게이트웨이 재시작과 검증까지 포함한 전체 성공이기 때문이다.

 

해결 방향 : phase1 / phase2 분리

그래서 구조를 바꿨다. 핵심 아이디어는 단순하다.

• phase1 : 업데이트와 재시작 트리거까지만 담당
• phase2 : 재기동 이후 살아난 환경에서 검증과 보고를 담당

즉, 자기 자신을 재시작하기 전까지의 일과 재시작된 뒤에 확인해야 할 일을 명시적으로 분리한 것이다. 이렇게 나누면 다음 장점이 생긴다

• 재시작 전후 경계가 분명해진다.
• 검증 로직이 “재시작된 뒤의 실제 환경”에서 실행된다.
• 중간에 세션이 끊겨도 phase2가 독립적으로 이어받을 수 있다.
• 운영 보고 포맷도 단계별로 정리할 수 있다.

 

전체 동작 흐름

최종적으로는 이런 흐름으로 정리됐다.

1. phase1 시작

phase1은 업데이트 작업의 진입점이다. 여기서 먼저 현재 상태를 보존한다. 대표적으로 저장하는 정보는 다음과 같다.

• 업데이트 전 OpenClaw 버전
• 업데이트 전 PID
• 현재 설정 파일 백업본 경로
• 실행 시각과 작업 ID
• 이후 검증에 필요한 상태 파일 경로

이 단계에서 백업을 남기는 이유는 단순하다. 운영 자동화는 실패하지 않는 것이 아니라 실패했을 때 추적 가능해야 하기 때문이다.

2. 공지 및 안전 대기

게이트웨이 재시작이나 설정 반영은 영향 범위가 있기 때문에, 바로 실행하지 않고 운영 채널에 공지를 남긴 뒤 잠깐 대기하는 흐름도 함께 묶었다. 여기서 공지 대상인 내(사람)가 아니라 다른 OpenClaw 에이전트들이다. 이렇게 하면 여러 가지 이점이 있다.

• 누가 언제 작업을 시작했는지 기록
• 반대 의견(실제 자주 반대하는 에이전트가 있음;)이나 긴급 상황 확인
• 자동화 실행 로그를 사람도 따라갈 수 있음

즉, 스크립트는 단순 실행기가 아니라 운영 런북(runbook)의 일부가 된다.

3. phase2 예약

이 구조에서 가장 중요한 부분이다. phase1은 업데이트를 수행하기 전에 먼저 phase2 실행 예약이 정상적으로 등록됐는지 확인한다. 이게 핵심 안전장치다. 왜냐하면 phase2 예약이 실패했는데도 게이트웨이 재시작을 먼저 해버리면, 업데이트 이후 상태를 검증할 주체가 사라질 수 있기 때문이다. 그래서 로직은 이렇게 간다.

1. phase2 cron 등록 시도
2. 등록 성공 여부 확인
3. 성공했을 때만 업데이트 및 게이트웨이 재시작 진행
4. 실패하면 즉시 중단

이 조건 하나만 들어가도 운영 안정성이 꽤 올라간다.

4. 업데이트 실행과 게이트웨이 재시작

phase2 예약이 확인되면 그다음에 실제 업데이트를 진행한다. 이 구간의 역할은 명확하다.

• OpenClaw 업데이트 실행
• 필요시 게이트웨이 재시작 수행
• phase2가 읽을 수 있도록 상태 파일 저장

여기서 중요한 건 “업데이트 완료”를 성공으로 보지 않는다는 점이다. 이 단계는 어디까지나 재시작까지 밀어 넣는 단계다. 정확한 성공 조건은 다음과 같이 정의된다.

• 패키지/코드 업데이트 성공
• restart 명령 정상 수행
• phase2가 이어받을 상태 저장 완료

5. 재기동 후 phase2 검증

OpenClaw가 다시 올라오면 예약된 phase2가 실행된다. 이제부터는 "정말 새 상태로 살아났는가"를 본다. 대표 검증 항목은 다음과 같다.

• 업데이트 후 버전 확인
• PID 변경 여부 확인
• 'gateway status' 정상 여부
• 'doctor' 실행 결과
• config diff 존재 여부
• 결과 요약 파일 생성

특히 PID 확인이 중요했다. 단순히 버전 문자열만 보는 것보다 실제로 프로세스가 교체되었는지 보는 게 훨씬 확실하기 때문이다. 예를 들면 이런 식이다.

• 이전 PID: 79018
• 이후 PID: 79743

이렇게 바뀌어야 진짜 재시작이 일어난 것이다.

 

구현 과정에서 부딪힌 문제들

2단계 구조로 바꾸는 과정이 한 번에 바로 끝난 건 아니다. 구현 과정에서 몇 가지 문제가 있었다.

1. self-restart로 현재 세션이 끊기는 문제

이건 처음 구조를 phase 분리하게 만든 직접 원인이었다. 하나의 스크립트 안에서 모든 걸 끝내려 하면 restart 이후 맥락 보존이 어렵다.

2. phase2 cron 등록 실패

처음 dry run에서는 phase2가 예약되지 않았다. 원인은 'openclaw cron add' 호출 방식이 맞지 않았기 때문이다. 이 문제를 잡고 나서 다음 원칙을 넣었다.

phase2 예약 성공 확인 전에는 restart 금지

이 한 줄이 사실상 핵심 안정장치다.

3. 결과 알림이 엉뚱한 채널로 가는 문제

phase2 완료 결과가 기대한 운영 채널이 아니라 다른 delivery 경로로 튀는 부작용도 있었다. 이후에는 결과 delivery를 유지하되,

• 운영 Discord 채널로 고정
• 메시지는 짧은 운영 보고형 포맷으로 정리

하는 쪽으로 다듬었다. 그리고 운영 채널 보고 포맷은 아래와 같이 간단한 형태로 했다.

OpenClaw update runbook 완료
- 결과: OK
- 버전: OpenClaw 2026.4.22 -> OpenClaw 2026.4.22
- PID: 79018 -> 79743
- restart 방식: restart
- gateway status: 0
- doctor: 0
- config diff: 1
- summary: /Users/garibong/.openclaw/tmp/update-runbook/summary-20260424-161200.txt

얼핏 보면 좀 길어 보이지만 (상대적으로) 짧은 것 맞다. 기계가 읽을 수 있는 상세 정보는 파일에 남기고, 사람이 보는 채널에는 짧고 즉시 판단 가능한 정보만 올리는 방식이다.

 

스크립트 분리 후 얻은 것

이번 정리로 가장 크게 얻은 건 세 가지다.

1. 업데이트 성공의 정의가 명확해졌다

예전에는 "업데이트 명령이 끝났다"가 성공처럼 보였지만 이제는 아니다. 이제 성공은 아래까지 포함한다.

• 새 버전 반영
• 실제 프로세스 교체
• 상태 검증 완료
• 운영 채널 보고 완료

즉 업데이트 전체 수명주기를 성공 기준으로 잡게 됐다.

2. 장애 추적이 쉬워졌다

phase1과 phase2가 나뉘어 있으니, 문제가 생겨도 어디서 끊겼는지 파악하기가 쉬워졌다.

• 예약 실패인지
• 업데이트 실패인지
• 게이트웨이 재시작 누락인지
• 재기동 후 검증 실패인지

운영 자동화에서는 이 구분이 꽤 중요하다.

정리

OpenClaw 업데이트 작업에서 진짜 어려운 부분은 update 명령 자체가 아니었다. 문제는 자기 자신을 재시작해야 하는 자동화라는 점이었다. 단일 흐름으로 처리하려고 하면 중간 맥락이 끊기고, 업데이트만 되고 재시작은 빠지는 애매한 상태가 되기 쉽다. 이를 다음 방식으로 정리했다.

• 업데이트 전후를 phase1 / phase2로 분리
• 재시작 전 phase2 예약 성공을 먼저 보장
• 재기동 후 버전, PID, doctor, 상태 점검까지 자동 검증
• 결과는 운영 채널에서 바로 읽을 수 있게 짧게 요약

결국 핵심은 업데이트 자동화에서 중요한 건 "업데이트 실행"이 아니라 "재시작 이후 검증까지 끊기지 않는 구조"라는 것이다. OpenClaw처럼 장기 실행형 에이전트 환경을 운영하고 있다면, self-restart가 포함된 작업은 단일 스크립트보다 재기동 경계를 기준으로 나눈 2단계 런북이 훨씬 안정적이다. 끝.