프로덕션에서 OpenClaw Gateway를 돌릴 때 어려운 부분은 openclaw update를 입력하는 일이 아니라 stable／beta／dev 채널을 변경 창에 맞추는 일, 인시던트 도중 자동 업데이트로 예기치 않게 재시작되지 않게 하는 일, 그리고 npm으로 고정할지 git으로 되돌릴지 순서를 틀리지 않는 일입니다. 본문은 롤백을 잘못 탓하는 일곱 가지 가정, 설치 표면·업데이트 진입·롤백 레버 매트릭스, 순서에 민감한 여섯 단계 Runbook(백업 → 채널 확인 → 업데이트 → 선택적으로 OPENCLAW_NO_AUTO_UPDATE → 재시작／프로브 → doctor), 그리고 gateway install --force가 필요할 때 split brain 가이드로 넘길 타이밍을 정리합니다. Docker 사용자는 Compose 프로덕션 업그레이드와 함께 읽고, 기준선은 헬스 로그와 롤백에 둡니다.
「OpenClaw 품질」 티켓을 다시 열기 전에 아래 함정을 짚습니다.
openclaw update를 「패키지만, 서비스는 안 건드린다」로 여기기: launchd／systemd 메타데이터는 유닛이 호출하는 바이너리와 맞아야 하며, 어긋나면 재부팅 뒤에도 되돌아옵니다.
프로덕션 SLA를 beta／dev에 얹기: 프리뷰 피드는 샌드박스용입니다. 변경 티켓은 기본 stable과 명시적 semver를 적습니다.
바이너리를 내리기 전에 openclaw.json을 대량 편집하기: 먼저 실행 면을 검증된 빌드로 고정한 뒤 스키마 마이그레이션 필요 여부를 판단합니다.
OPENCLAW_NO_AUTO_UPDATE를 커뮤니케이션 대체재로 보기: 제어 레버입니다. 유지보수 창, 담당자, 롤백 명령은 별도로 공유합니다(의미는 최신 upstream 문서 기준).
깨끗한 트리 검증 없이 git 롤백하기: git checkout <tag> 후 서브모듈, 락파일, 로컬 패치를 확인해 릴리스 아티팩트와 일치시킵니다.
Docker 안내를 베어 메탈 npm에 그대로 적용하기: 태그, 볼륨, 엔트리포인트가 다릅니다. 컨테이너는 Compose 가이드를 따르고 명령 체인은 분리합니다.
doctor가 끝나기 전에 전 트래픽을 되돌리기: 유지보수 배너를 내리기 전에 최소 한 번 channels status --probe와 cron list 확인을 요구합니다.
7단계가 녹색인데도 가드가 바이너리 불일치를 말하면 npm만 반복하기 전에 split brain 플레이북으로 이동합니다.
롤백을 스크립트화하기 전에 OpenClaw를 무엇으로 설치했는지 이름을 붙입니다.
| 표면 | 전형적 업데이트 진입 | 주 롤백 레버 | 다음 읽을 글 |
|---|---|---|---|
| npm 글로벌 | openclaw update／npm install -g … | @scope/[email protected] 고정 후 재설치 및 서비스 패키징 정렬 | split brain |
| git 트리 | git pull／벤더 빌드 스크립트 | 태그에서 git checkout 후 재빌드 | 3절 순서; Docker와 섞지 않기 |
| 인스톨러 스크립트 | 벤더 CLI／curl 인스톨러 | 고정된 인스톨러 번들 재실행 | 티켓에 체크섬 첨부 |
| Docker／compose | 새 이미지 태그 pull | 태그／다이제스트와 볼륨 스냅샷 정책 되돌리기 | Compose 업그레이드 |
황금 순서: (1) 증거 백업 → (2) 바이너리 정체 고정 → (3) 그다음에 JSON 이전을 논의한다.
원격 토폴로지에서는 gateway.mode와 URL 확인이 여전히 필요합니다. 자세한 내용은 원격 모드 가이드를 참고합니다.
순서에 민감합니다. CLI와 사용자 서비스 바이너리가 갈라지면 split brain 가이드를 엽니다.
증거·백업: openclaw --version, gateway status, 마스킹한 env 발췌, openclaw.json 또는 마운트 볼륨 스냅샷을 확보합니다.
채널 확인: upstream 문서에 따라 stable／beta／dev를 맞춥니다. 프로덕션은 stable 기본과 티켓의 명시적 semver를 둡니다.
업데이트 적용: 문서화된 openclaw update를 우선합니다. npm install -g를 쓰면 직후 서비스 유닛이 올바른 prefix를 가리키는지 검증합니다.
인시던트 게이트(선택): 동결·핫픽스 고정 시 문서대로 systemd／launchd 셸 또는 컨테이너에 OPENCLAW_NO_AUTO_UPDATE를 주입해 예기치 않은 업그레이드를 멈춥니다. 해제 조건을 기록합니다.
콜드 재시작·프로브: openclaw gateway restart → channels status --probe. 리소스 증상은 not ready로 넘깁니다.
doctor·관측: openclaw doctor 실행 후 헬스 로그 보존 창에 맞춰 로그를 샘플링한 뒤 유지보수를 닫습니다.
openclaw --version openclaw update openclaw gateway restart openclaw doctor openclaw channels status --probe # npm 고정 예 (패키지명은 문서 기준) # npm install -g @your-scope/[email protected]
참고: doctor가 포크된 바이너리를 보고하거나 파괴적 gateway 단계를 거부하면 split brain 체크리스트로 전환하고 npm만으로는 반복하지 않습니다.
OPENCLAW_NO_AUTO_UPDATE와 변경 창자동 업데이트는 드리프트를 줄이지만, 인시던트·감사·팀 간 고정에서는 백그라운드 pull을 멈춰야 할 수 있습니다. 그 의도가 OPENCLAW_NO_AUTO_UPDATE입니다. 정확한 의미, 기본값, 주입 지점(사용자 유닛·셸 프로필·컨테이너 env)은 최신 upstream 문서를 따르고, 본문은 운영 위생만 다룹니다.
주의: 게이트는 영구 정책이 아닙니다. 장기간 자동 업데이트를 끄면 수동 편차가 생깁니다. 이유, 제거 담당, 해제 후 전체 회귀를 기록합니다.
레거시 바이너리가 서비스를 덮어쓰게 허용하는 파괴적 OPENCLAW_*와 달리, 이 게이트는 주로 자동 업그레이드 리듬을 일시 정지합니다. split brain이 이미 있어도 PATH를 맞추고 패키징을 재설치하는 것이 먼저입니다.
변경 티켓에 남길 수 있는 정량 점검입니다.
openclaw --version이 일치하고 티켓 목표와 맞습니다.git rev-parse HEAD와 태그 첨부, npm은 정확한 semver, compose는 이미지 다이제스트(Docker 가이드 기준).소비자 노트북은 수면·재시작이 불규칙하고, Gateway를 VPS처럼 안정적으로 돌리면서 Apple Silicon·GUI 이점을 유지하려면 무한 로컬 업그레이드보다 전용 클라우드 Mac이 더 안전한 경우가 많습니다. NodeMini는 SSH 친화 렌탈 노드와 명확한 요금을 제공합니다. Mac Mini 대여 가격과 헬프 센터를 참고하세요. OpenClaw 권장 읽기 순서: 관측 → cron → 원격 모드 → split brain → 본문(채널과 롤백) → 칼럼 필터.
openclaw update는 벤더 채널 의미를 따릅니다. 단순 npm은 글로벌 prefix 파일만 갈아끼우며 오래된 경로를 가리키는 launchd／systemd 유닛을 자동으로 고치지 않습니다. 그것이 split brain 이야기이며 보통 gateway install --force가 필요합니다.
인시던트, 감사 동결, 필수 패치 고정 시입니다. 의미와 주입은 upstream을 따릅니다. 해제 후에는 doctor와 채널 프로브를 다시 돌리고 로깅은 관측 가이드에 맞춥니다.
Compose 프로덕션 업그레이드를 우선하세요. 이미지 태그／다이제스트, 볼륨, 부팅 순서가 롤백을 결정합니다. 베어 메탈 npm／git 안내는 병행 읽기일 뿐 관련 없는 명령 체인을 섞지 마세요.