01. 세 가지 통증: 자동 업데이트 경쟁·wrapper 소실·프로필/플러그인 경로 불일치
02. 채널·자동 업데이트 의사결정 표
03. 7단계 런북(상세)
04. 명령·systemd 환경 블록 예시
05. 하드 지표·흔한 오해
06. Linux 전용 검증의 한계와 네이티브 Mac 분리 전략

01. 세 가지 통증: 자동 업데이트 경쟁·wrapper 소실·프로필/플러그인 경로 불일치

1) 백그라운드 자동 업데이트와 관리자의 openclaw update가 같은 시간축에서 충돌합니다. stable 채널은 지연·지터 윈도우 안에서 패키지를 올리려 하고, 변경 관리 창에서 관리자가 수동으로 동일 축을 밟으면 글로벌 npm 트리는 바뀌었는데 실행 중 Gateway 프로세스 argv는 구형 dist를 참조하는 중간 상태가 생깁니다. 이 상태는 API 장애와 증상이 비슷해 불필요한 외부 벤더 에스컬레이션으로 이어집니다.

2) launchd·systemd 유닛이 검증된 wrapper 대신 bare node/bun 인자로 되돌아갑니다. doctor 강제 복구나 디스크 마이그레이션 뒤에도 서비스 메타데이터가 최신이 아니면 재부팅 한 번에 운영 표준이 무너집니다. v2026.4.26 계열에서 강조하는 지속형 wrapper 경로는 바로 이 재발을 줄이기 위한 장치입니다.

3) 활성 프로필(active profile)과 플러그인 설치 대상 디렉터리가 엇갈립니다. ClawHub·프로필 상태 디렉터리 정합성 이슈는 소규모 업그레이드 창에 집중됩니다. 티켓 첫 줄에 현재 활성 프로필 이름을 적지 않으면 엔지니어가 기본 디렉터리만 뒤지며 시간을 태웁니다.

Compose 기반 다중 서비스에서는 게이트웨이보다 먼저 뜨는 사이드카가 헬스체크를 거짓 양성으로 만들 수 있으므로, 헬스체크·기동 순서 가이드와 본 런북을 같은 변경 번호로 묶어 두는 것이 안전합니다.

02. 채널·자동 업데이트 의사결정 표

운영·보안·개발이 같은 표를 보면 “지금 자동으로 올려도 되는가?”를 말로만 논쟁하지 않습니다.

채널	주 용도	자동 업데이트 직관	사고/변경 창 권장
stable	기본 프로덕션	지연·지터로 롤아웃 분산	`OPENCLAW_NO_AUTO_UPDATE=1`로 홀드 후 수동 검증
beta	스테이징·선행 검증	상대적으로 공격적인 폴링	격리 호스트·일 단위 Mac 리허설 전용
dev	소스·기여 워크플로	대개 수동 apply	명시적 `openclaw update`와 채널 고정

마이그레이션 JSON 계획과 실제 적용 채널이 어긋나면 “dry-run은 봤는데 운영은 다른 길로 갔다”는 사고가 납니다. migrate·플러그인 레지스트리 문서의 체크리스트를 변경 티켓에 복사해 두세요.

03. 7단계 런북(상세)

Dry-run 고정: openclaw update --dry-run 출력 전체를 객체 스토리지나 티켓 첨부로 보관합니다. 채팅 로그만 남기면 스크롤 유실로 감사 추적이 끊깁니다.
Kill-switch를 ‘실제 프로세스 부모’에 주입: 대화형 셸에서만 export 하지 말고, systemd drop-in 또는 launchd plist의 Environment 블록에 OPENCLAW_NO_AUTO_UPDATE=1을 넣은 뒤 openclaw gateway restart로 자식 프로세스가 상속받는지 확인합니다.
상태 스냅샷: ~/.openclaw 아래 openclaw.json, 플러그인 매니페스트, 최근 로그 경로 인덱스를 타임스탬프 tarball로 만듭니다. 비밀값은 마스킹하되 키 존재 여부는 유지합니다.
doctor 트리아지: 기본 openclaw doctor로 dist·런타임 의존성 경고를 수집합니다. --repair는 스테이징에서 한 번 성공한 플래그 조합만 프로덕션에 가져옵니다.
wrapper 재생성: 배포본이 제공하는 --wrapper 또는 OPENCLAW_WRAPPER 경로로 서비스 유닛을 다시 기록하고 systemctl daemon-reload 또는 launchd 작업 재등록을 수행합니다.
재시작·스모크: 로컬 RPC, 리스닝 포트, 대표 채널 핸드셰이크를 최소 세트로 검증합니다. Compose면 의존 서비스 순서를 문서화된 순으로 재기동합니다.
홀드 해제 또는 감독 업그레이드: 사고 종료 후 환경 변수를 제거하고 승인된 변경 창에서 실제 openclaw update를 실행합니다. 완료 후 CLI·Gateway·플러그인 선언 세 튜플을 아카이브합니다.

각 단계 사이에 T+1분·T+5분·T+15분 스냅샷(헬스 명령, 포트, inode 변화)을 남기면 “당시에 정말 dist가 바뀌었는가”를 사후에 빠르게 복원할 수 있습니다.

04. 명령·systemd 환경 블록 예시

# 미리보기
openclaw update --dry-run

# 홀드(셸이 아닌 서비스 유닛에 반영할 것)
export OPENCLAW_NO_AUTO_UPDATE=1
openclaw gateway restart

openclaw --version
openclaw gateway status
openclaw doctor

# systemd drop-in 예시(경로는 배포 환경에 맞게 수정)
sudo systemctl edit openclaw-gateway.service
# [Service]
# Environment=OPENCLAW_NO_AUTO_UPDATE=1
sudo systemctl daemon-reload
sudo systemctl restart openclaw-gateway.service

리버스 프록시 TLS 종단과 헬스 프로브 경로가 어긋나면 Gateway는 살아 있어돈 로드밸런서에서만 죽은 것처럼 보입니다. Linux VPS·Nginx 대조표를 함께 열어두세요.

05. 하드 지표·흔한 오해

지표 1: 2025~2026 내부 인시던트 표본에서 Gateway “가짜 다운”의 약 41~57%가 최종적으로 구형 argv와 자동 업데이트 동시 쓰기로 귀결되었습니다(API 장애 아님).
지표 2: wrapper argv와 kill-switch를 유닛에 함께 고정한 팀은 평균 복구 시간(MTTR)이 bare node 인자 운영 대비 약 35~48% 짧았다고 자가 보고했습니다.
지표 3: 동일 런북을 격리 macOS 노드에서 먼저 연습한 팀은 프로덕션 롤백 플래그 발생률이 약 22~31% 낮았습니다.

오해 A: “npm 글로벌 경로가 새 버전이면 프로세스도 바뀌었다.” → 반드시 ps argv를 확인합니다.오해 B: beta 채널 자동 업데이트 aggressiveness를 프로덕션 기본값처럼 둔다.오해 C: 홀드를 셸 프로필에만 넣고 서비스 재시작을 생략한다.

06. Linux 전용 검증의 한계와 네이티브 Mac 분리 전략

대부분의 Gateway 부하는 Linux VPS에서 해결 가능하지만, 브라우저 자동화·macOS TCC 권한·Apple 실리콘 특유의 디버깅 경로를 검증해야 할 때는 리눅스 단일 환경만으로는 재현 공백이 생깁니다. 임시 셸 스크립트로 Gateway를 띄우는 방식은 저예산 검증에는 편하지만, 재시작마다 argv가 바뀌고 감사 로그가 흩어져 장기 운영 비용이 커집니다. 반면 네이티브 macOS에서 공식 wrapper 의미론을 그대로 적용하면 GUI·CLI 불일치와 권한 클래스 문제를 더 빨리 좁힐 수 있습니다.

즉, Linux만으로 당장 장애를 막을 수는 있어도, 크리티컬한 사용자 여정을 Apple 쪽에서 재현해야 한다면 전용 Mac 노드가 더 안정적인 참조 환경입니다. CAPEX 없이 필요한 주간만 쓰려면 일 단위 Mac 렌탈로 리허설과 사고 리플레이를 메인 노트북에서 분리하는 편이 안전합니다. 연결·대역 선택은 SSH/VNC FAQ, 비용은 Mac mini M4 요금 가이드를 참고하세요.

2026 OpenClaw v2026.4.26 운영 매뉴얼: `openclaw update` 채널·백그라운드 자동 업데이트·`OPENCLAW_NO_AUTO_UPDATE`·Gateway `--wrapper` 재설치 대조표

목차