2026 OpenClaw 불량 릴리스 몇 분 롤백: 다이제스트 잠금, Compose와 npm 이중 경로, 읽기 전용 볼륨 점검

약 18분 읽기 · MACCOME

OpenClaw를 방금 올렸는데 Gateway 동작이 이상하거나, CLI와 컨테이너 버전이 갈라지거나, 커뮤니티에서 회귀 구간이 지적된 상황이라면, 이 글은 세 가지를 정리합니다. 즉시 롤백할지 여부, Docker 경로와 npm 경로에서 각각 다이제스트를 어떻게 고정하고 버전을 맞출지, 읽기 전용 볼륨 점검과 검증 사다리로 알려진 양호 상태로 돌아왔음을 어떻게 증명할지입니다. 릴리스 채널 고정 매트릭스(전략 대 사고 운용)를 보완하며, 전용 원격 Mac Gateway로의 SSH 로컬 포워딩 및 업그레이드와 마이그레이션 체크리스트와 함께 읽는 것을 권합니다.

롤백 전에 가려야 할 불량 릴리스처럼 보이는 오탐 여섯 가지

  1. 스플릿 브레인 업그레이드: 호스트 openclaw 바이너리만 새롭고 컨테이너 Gateway는 오래된 경우(또는 그 반대). 누락된 서브커맨드나 알 수 없는 플래그가 나와 WebSocket 1006 소음으로 오인하기 쉽습니다.
  2. 볼륨 권한 또는 마운트 드리프트: 업그레이드 스크립트가 새 UID/GID 의미를 가정하지만 compose가 따라오지 않은 경우. 새 빌드가 옛 상태를 못 읽는 것처럼 보이나 실제로는 파일시스템 계약이 깨진 경우가 많습니다.
  3. 설정 트리 중복: .openclaw가 바인드 마운트와 익명 볼륨에 동시에 존재합니다. 이미지만 되돌려도 빈 트리를 읽어 롤백이 효과 없는 것처럼 보입니다.
  4. 프록시, TLS 가로채기, 기업 MITM: 업그레이드로 새 다운로드 경로에 닿으면 TLS가 실패하고, 상류 빌드 결함으로 돌리기 쉽습니다.
  5. 리소스 상한: 업그레이드 후 기본값이 더 무거운 샌드박스나 동시 세션을 켭니다. 메모리가 작은 호스트에서는 OOM으로 Gateway가 불안정해 보일 수 있으나 비트 자체는 정상일 수 있습니다.
  6. 문서화된 호환성 파괴: 릴리스 노트에 새 동작이 있는데 자동화가 옛 플래그를 호출합니다. 이는 마이그레이션 과제이며 다이제스트 롤백 대상이 아닙니다.

사고 롤백은 증상을 버전 진실 삼중주에 매핑하는 것으로 시작합니다. CLI 시맨틱 버전 또는 빌드 ID, 이미지 다이제스트(또는 감사 가능한 다른 참조), 설정 디렉터리의 inode와 마운트 그래프입니다. 이 스냅샷 없이 되돌리면 이미지만 오래되고 잘못된 볼륨이나 TOKEN 주입 계층을 읽는 무작위 다운그레이드에 가깝습니다. 이 가이드는 그린필드 설치나 doctor 증상 목록 전체를 반복하지 않고, 롤백 후 수락에 필요한 프로브만 남깁니다.

Gateway가 절전이 잦은 노트북이나 데스크톱에 묶인 세션 위에 있으면 전원 정책, VPN 순간 끊김, 디스크 압박이 업그레이드 후 불안정으로 보이며 롤백 예산을 태웁니다. 티켓에 다이제스트 A에서 B로, 다시 A로라고 감사 가능하게 적어야 한다면, 권위 있는 Gateway를 상시 가동 전용 원격 Mac에 두고 노트북은 CLI만 두는 편이 총비용에서 이기는 경우가 많습니다. 네 번째 절에서는 온콜 핸드북에 붙일 KPI 형태의 임계값 세 가지를 제시합니다.

차원 계속 디버깅(롤백 연기) 지금 롤백(먼저 서비스 복구)
파급 반경 격리된 TOKEN과 볼륨을 가진 비프로덕션 샌드박스 프로덕션 트래픽에서 조용한 실패, 작업 유실, 보안 경고가 있거나 커뮤니티가 회귀 범위를 확인한 경우
증거 사슬 삼중주를 확보했고 doctor가 구체적인 설정 손잡이를 가리킴 스냅샷이 없거나 삼중주가 이미 불일치이며 설정 변경이 파급을 넓힘
Docker 레버 한 서비스에 대해 docker compose logs를 좁히고 공식 파괴 변경 메모와 대조 OPENCLAW_IMAGE를 마지막으로 알려진 양호한 다이제스트로 지정. pull 후 up -d. 이어서 읽기 전용 볼륨 점검
npm 레버 Node 메이저 기준선과 단일 전역 PATH 확인 이전 전역 패키지를 상류 문서대로 재설치하고 Gateway 데몬을 재시작한 뒤, 트래픽을 열기 전 최소 프로브 실행
원격 상주 전용 호스트에서 별도 볼륨 이름과 포트로 섀도 다이제스트 실행 가능 프로덕션과 섀도 볼륨 이름을 반드시 분리하여 롤백이 실험 데이터를 지우지 않게 함

릴리스 채널 고정 글과 어떻게 짝을 이루는가

2026-05-13 고정 매트릭스는 어떤 stable/beta/dev 레일을 탈지와 언제 선제적으로 다이제스트를 고정할지에 답합니다. 본 글은 이미 빌드가 나쁘다고 본 뒤에 할 일, 즉 롤백과 검증과 감사 흔적을 몇 분으로 압축하고 읽기 전용 볼륨 감사로 이미지만 되돌렸는데 상태는 어긋난 상황을 막는 데 초점을 둡니다. 페어링, 1006/1008, TOKEN 이중 소스에 막히면 페어링 및 토큰 충돌 런북으로 이동하고, 여기서는 롤백 후 페어링을 다시 해야 하는지에 대한 결정 임계값만 다룹니다.

Docker 프로덕션 경로에서는 로그 보존, cgroup 한도, 노출 정책을 Docker 프로덕션 런북 옆에 두지 않으면 다이제스트는 고정했는데 그날 밤의 compose SHA를 아무도 모르는 상태가 됩니다. 아래 bash 블록은 필드 범주를 나열한 스케치이니 서비스 이름, 볼륨 이름, 레지스트리 호스트를 실제 값으로 바꾸고, 고정한 빌드의 공식 문서와 서브커맨드를 맞추십시오.

warning

참고: 커뮤니티의 불량 소수 릴리스 이야기는 시간에 민감합니다. 이 가이드는 특정 시맨틱 버전을 하드코딩하지 않습니다. 실행 전 티켓에 목표 다이제스트 또는 태그, compose git SHA, 실험 볼륨 삭제 허용 여부를 반드시 적으십시오.

여섯 단계 다이제스트 고정에서 롤백과 수락까지의 런북

  1. 증거 동결: openclaw --version, 이미지 RepoDigests, 잘린 docker compose config, 상태 트리의 읽기 전용 디렉터리 목록을 출력합니다(bash 스케치 참조).
  2. 단일 레일 선택: 한 변경 티켓에서는 Docker 또는 npm 중 하나만 건드리는 것을 선호합니다. 둘 다 움직여야 하면 Gateway에 가까운 쪽부터 되돌리고 즉시 재검증합니다.
  3. Docker 롤백: OPENCLAW_IMAGE를 ghcr.io/.../...@sha256:<known-good>로 설정하고 docker compose pull 후 docker compose up -d를 실행합니다. up 없이 pull만 하지 마십시오.
  4. 읽기 전용 볼륨 감사: 컨테이너 안에서 마운트 지점에 ls -la로 중요 파일 존재를 확인하고 빈 호스트 디렉터리에 묶이지 않았는지 확인합니다.
  5. npm 롤백: 상류 문서에 따라 이전 전역 버전을 재설치하고 Node 기준을 다시 확인한 뒤 Gateway를 감싼 launchd나 systemd 등 유닛을 재시작합니다.
  6. 검증 사다리: gateway status 등가부터 18789 Control UI 도달, 비파괴 최소 프로브, openclaw doctor 순으로 진행합니다. 한 단계라도 실패하면 트래픽을 다시 열지 말고 로그를 보관합니다.
bash
# Evidence snapshot (rename fields to your environment)
openclaw --version 2>/dev/null || true
docker compose config | sed -n '1,160p'
docker image inspect "${IMAGE_REF}" --format '{{json .RepoDigests}}' 2>/dev/null || true

# Read-only volume sweep (replace container and mount path)
# docker exec -it <gw_container> sh -lc 'ls -la /path/to/mounted/state | head'

# Pin OPENCLAW_IMAGE to digest (do not copy a random digest from the internet)
# export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw@sha256:<KNOWN_GOOD>"
# docker compose pull && docker compose up -d

온콜 핸드북용 정량 임계값 세 가지

  • MTTRrollback: 롤백 결정부터 사다리 전체 녹색까지의 중앙값 분. 소규모 팀은 15분 이하를 목표로 합니다. 두 주 연속 목표를 넘기면 스냅샷 자동화나 compose 분산이 깨진 것입니다.
  • 주당 스플릿 브레인 검출: CLI가 보고하는 빌드와 Gateway 다이제스트가 불일치하는 자동 경고. 0이 아닌 주는 grep을 더하는 대신 단일 진실 근원 교정을 트리거해야 합니다.
  • 볼륨 드리프트 비율: 롤백 후 첫 프로브 실패 중 근본 원인이 빈 디렉터리 마운트 또는 UID 불일치인 비중. 10%를 넘으면 compose 바인드 경로를 필수 코드 리뷰에 넣으십시오.

이 수치는 합성 벤치마가 아니라 운영 관측성입니다. 나쁜 버전을 감에서 셀 수 있는 사건으로 바꿉니다. 무거운 Xcode 빌드와 Gateway를 한 호스트에 두면 디스크 워터마크와 로그 로테이션을 업그레이드 창에 묶지 않을 때 I/O 포화로 MTTR이 늘어납니다. 용량과 리스 프레이밍은 다중 지역 렌탈 가이드를 읽고, 과금 세부는 여기 범위 밖입니다.

노트북에서 떠다니는 태그를 쫓으며 수동 롤백하는 방식이 전용 원격 Mac과 다이제스트 잠금에 지는 이유

노트북은 상호작용에는 좋지만 수면, 클램셸, VPN 변동, OS 업데이트, 키체인 맥락이 Gateway 가동과 겹칩니다. 같은 상자에서 롤백하면 명령은 성공했는데 데몬이 다시 로드되지 않는 반쯤 된 상태가 자주 납니다. 권위 있는 Gateway를 상시 가동 전용 원격 Mac에 두고 문서화된 SSH 포워딩이나 비공개 인그레스로 받으면 버전 변경 표면과 개인 터미널 노이즈가 분리되어 많은 팀이 에이전트 Gateway를 프로덕션화합니다. 로컬 최신을 고집하더라도 진실 삼중주는 CI나 cron에 남기고 채팅 스크롤에는 남기지 않는 편이 안전합니다.

반복적인 docker compose restart나 맹목적인 npm reinstall에 비해 다이제스트 우선 롤백은 감사 가능하고 두 번째 머신에서 재현할 수 있어 보안과 사후 검토에서 실제로 요구되는 조건을 충족합니다. 7×24 감사 가능한 Gateway를 팀 변경 케이던스에 맞추려면 여섯 지역에서 유연 리스를 제공하는 MACCOME Mac mini(M4 / M4 Pro)에 올리는 편이 노트북 전원 정책과 싸우는 것보다 총소유비용에서 유리한 경우가 많습니다. 먼저 다중 지역 가이드를 읽고 위에 링크한 SSH 런북으로 토폴로지를 연결하십시오.

마무리: 마지막으로 알려진 양호 다이제스트는 셸 기록이 아니라 ROLLBACK.md에 적습니다

산출물에는 기본 다이제스트 참조, 허용되는 프리뷰 창, 금지 패턴(예: 프로덕션은 digest 없는 latest에 떠 있으면 안 됨), 사다리 출력 샘플, 롤백 담당자와 타임아웃을 나열하십시오. 두 번째 머신에서 재생할 수 없는 단계는 미완 문서입니다. GHCR 부트스트랩과 Control UI와 함께 읽을 때는 이미지 롤백과 18789 노출 정책을 한 티켓에 묶어 비상 다운그레이드 뒤 관리 UI를 실수로 공개하지 않도록 하십시오.

FAQ

이미지를 롤백한 뒤 Gateway 토큰을 다시 페어링해야 합니까?

데이터 볼륨이 온전하고 설정 계약이 맞으면 종종 필요 없습니다. 핸드셰이크나 이중 소스 경고가 남으면 페어링 글을 따르십시오. 프로덕션 전용 호스트를 계획 중이면 임대료와 지원 및 도움을 검토하십시오.

릴리스 채널 고정 글과 중복되나요?

그 글은 일상 전략 매트릭스를, 이 글은 사고 순서와 볼륨 점검을 담당합니다. 전략을 먼저, 사고를 다음으로 읽고 슬러그로 상호 링크하여 SEO 의도도 분리하십시오.

롤백 후에도 doctor가 실패하면 어떻게 합니까?

진실 삼중주와 읽기 전용 감사를 다시 하고 전용 doctor 글을 따르십시오. 리소스 한계를 의심하면 노트북과 원격 호스트 모두에서 RAM과 디스크 워터마크를 확보한 뒤 새 티켓을 열어 OOM을 버전 결함으로 잘못 분류하지 마십시오.