1. 바이너리만 갈아끼우면 안 되는 이유
~/.moltbot·구 접두사가 남으면 ~/.openclaw와 이중 진실이 됩니다. doctor --fix는 채널 토큰 만료·리버스 프록시 경로는 고치지 않습니다. v2 인증은 클라이언트 빌드를 맞추지 않으면 “연결된 듯” 무응답이 납니다.
2. 마이그레이션 매트릭스
| 축 | 이전 | 목표 |
|---|---|---|
| 상태 루트 | ~/.moltbot 등 | ~/.openclaw + OPENCLAW_* |
| 데몬 | 오래된 바이너리 경로 | plist EnvironmentVariables 명시 |
| 인증 | v1 | v2 nonce 정렬 |
3. 다섯 단계 런북
- 상태·workspace·plist·버전 스냅샷.
doctor무 fix 저장.- 복사본에서
--fix시험 후 diff 검토. - 셸·CI·plist에서 구 접두사 grep 제거.
- 채널 탐침·최소 skill, 실패 시 Gateway 롤백 글 참조.
4. 인용 가능 임계
- 동일 drift가 3회 연속 채널을 막으면 마이너 업그레이드 중단 후 디렉터리 일괄 이전.
- 인증 오류가 시간당 20% 초과且 단일 빌드 → 해당 클라이언트 v2로.
- plist·대화형 셸의 비밀
OPENCLAW_*차이가 있으면 게이트 불합격.
5. 원격 Mac / launchd
| 증상 | 추정 | 조치 |
|---|---|---|
| 수동 OK·launchd NG | PATH/토큰 미주입 | plist에 명시 |
| 한 채널만 무음 | Webhook/서명 | 업그레이드 노트로 재페어링 |
| skill EACCES | 샌드박스 | 권한·노출면 글 |
6. FAQ
--fix가 workspace를? 포인터를 바꿀 수 있으니 스냅샷 필수.
Docker? 호스트와 컨테이너에 진실 원천을 하나만 두고, bind-mount와 호스트 직접 편집을 동시에 하지 마세요.
v1으로 잠시 롤백? 격리 랩과 폐기 일자가 있을 때만, 운영은 클라이언트 업데이트가 정답입니다.
~/.moltbot 즉시 삭제? 새 트리에 동등 비밀이 있고 채널 검증 후에. tarball은 최소 한 릴리스 주기 보관.
doctor는 녹색인데 채널 무음? Webhook 전달 로그·서명 헤더를 SaaS 쪽에서 추적하세요.
마이너 추적 주기? 설정·인증 변경이 언급될 때마다 짧은 스모크. 문서만 바뀌어도 채널 1개+skill 1개는 저렴한 보험입니다.
7. 사례·심층
Slack만 무음: plist 경로·셸 전용 토큰·서명 헤더 불일치가 겹친 사례. 스테이징 Mac에서 plist 키를 미러링한 뒤 운영에 적용하면 사용자 재전송을 줄입니다.
소규모 마이너 연속 업그레이드용이며, 대규모 2.0 이전에는 별도 마이그레이션 글을 먼저 끝내세요.
업그레이드 직후 바인드 주소·볼륨 마운트를 다시 확인하세요. 새 기본값이 공개면을 좁힐 수 있습니다.
토크나이저·프록시 타임아웃도 “무작위 무음”처럼 보이므로 OpenClaw와 함께 버전을 박제하세요.
티켓에 해결된 openclaw 바이너리 체크섬을 붙이고 롤백 시 패키지뿐 아니라 plist 실행 경로도 되돌립니다. 다사용자 호스트에서는 데몬 UserName과 키 보유 계정이 어긋나면 인증이 간헐적으로 실패합니다.
Homebrew와 npm 글로벌이 공존하면 PATH 승자를 하나로 정한 뒤 doctor를 실행하세요.
8. 변경 창 관측 세트
종료 코드, 채널 탐침 성공률, skill 콜드스타트 중앙값, 인증 실패/시를 함께 봅니다. 네 가지가 동시에 악화되면 루트 이전, 인증만 튀면 클라이언트 매트릭스입니다.
로그에 user-agent·기기 ID가 보이면 인증 실패를 빌드별로 묶으세요. 낡은 모바일 빌드가 대부분을 차지해 서버 퇴행으로 오진하기 쉽습니다.
| 신호 | 의미 | 다음 |
|---|---|---|
| 같은 키 누락 반복 | ~/.openclaw 수렴 미완 | 업그레이드 중단·이전 완료 |
| 대화 OK·데몬 NG | launchd 환경 드리프트 | plist vs 셸 env diff |
| 밤에만 실패 | cron/launchd vs 로그인 문맥 | 실행 사용자·키 가시성 정렬 |
8.1 CI·스테이징·latest 함정
CI가 매일 npm i -g openclaw@latest만 돌린다고 안전하지 않습니다. 러너 Node 메이저·기본 셸 PATH·산출물 메타에 해석된 semver/digest가 없는 경우가 많습니다. CI에서도 핀을 박고 절대 경로+체크섬을 기록하세요.
운영과 같은 Slack 워크스페이스에서 스테이징 Gateway를 돌리면 봇·채널을 분리하세요. 리허설 webhook 오배달이 운영 감사 로그를 오염시킵니다. 운영 plist를 복제해 비밀·리슨 포트만 바꾸고 동일 스모크를 통과시키세요.
버전 동결 주간에는 OPENCLAW_CONFIG_ROOT 이중 해석을 금지하고 plist 또는 systemd drop-in 하나로 모으며 diff -u를 티켓에 붙입니다.
openclaw를 호출하는 헬스 스크립트도 CLI 세대에 맞춰 갱신하세요. 오래된 종료 코드 해석이 정상 Gateway를 재시작 폭풍으로 만듭니다.
롤백 리허설은 전진과 같은 데이터로: 스냅샷 복원, 이전 digest 재설치, 채널 탐침 재생. doctor 출력 없는 롤백은 미완입니다.
스테이징 plist에만 EnvironmentVariables 블록이 늘었다면 스테이징을 “고치는” 게 아니라 운영으로 구조를 되돌려 드리프트를 없앱니다.
CI가 캐시된 다른 마이너를 집어 올리면 “운영 Gateway는 녹색, 야간 잡만 적색” 패턴이 납니다. 러너 AMI·이미지를 서버와 세트로 핀하세요.
9. 정리
비 Mac은 서비스 관리 층이 늘고 상태 계약을 얼리지 않으면 되돌림 비용이 커집니다. 원격 Apple Silicon Mac은 launchd 예시·창작 자동화 스택과 맞추기 쉬워 검증 비용을 줄입니다. MACGPU는 상주 검증용 원격 Mac을 낮은 마찰로 제공합니다. 스냅샷과 doctor 로그 없는 변경은 미완입니다.
인증 v2 직후 짧은 재연결이 작은 VPS CPU를 일시적으로 올립니다. 클라이언트 단계 롤아웃을 제한하거나 추종 기간만 호스트를 키우세요.
보안 리뷰는 doctor --fix가 ACL을 넓히지 않았는지 증거를 요구합니다. 민감 디렉터리 ls -le 전후를 변경 기록에 첨부하세요.
10. 설치 경로·Docker 운영 연결
npm 글로벌·Compose·pnpm 소스는 데이터 루트가 다릅니다. 어느 체인을 고치는지 먼저 고정하고 경로를 가로지르는 복사를 피하세요.
Compose가 이미지 digest를 고정했다면 그 digest도 계약의 일부입니다. 호스트 npm만 올려도 컨테이너에 박힌 CLI는 안 움직입니다.
~/.openclaw를 컨테이너에 bind하면서 호스트에서도 같은 트리를 편집하면 doctor --fix 경합이 납니다. 작성자를 직렬화하거나 스테이징 복사본을 끼우세요.
환경별 한 장짜리 업그레이드 카드: 바이너리 절대 경로, plist 라벨, 데이터 루트, 활성 채널 목록. 사고 때 첫 첨부는 이것입니다.
11. doctor 녹색 이후 주간 체크
0일: 실트래픽 후 doctor tarball을 다시 받아 업그레이드 전과 diff. 1일: 데몬 계정·관리자 계정 모두에서 채널 탐침. 2일: 가장 느린 skill을 콜드스타트+재시도로 두드려 샌드박스 차이를 먼저 봅니다.
3일: 인증 오류를 빌드별로 묶어 편향이 있으면 강제 업데이트 창을 잡습니다. 4일: 백업·스냅샷 복구가 현재 plist 라벨과 일치하는지 확인. 5일: 실행자·메트릭 담당이 짧게 회고하고 카드에 한 줄 개선을 남깁니다.
단계 사이에 최소 하룻밤 관측을 넣고, 마케팅 대형 캠페인·분기말 프리즈·온콜 휴가는 npm 공개일보다 우선해 일정에 넣으세요.
한 주가 깨끗하면 결과를 doctor tarball 옆에 아카이브하고, 플레이크는 담당·기한이 생길 때까지 열어둡니다. 체크리스트 실행자는 릴리스마다 로테이션하고 본문은 VCS로 관리해 성숙도 변화를 diff로 봅니다.
개인 셸 alias에만 의존한 스모크는 로테이션으로 드러나므로, 표준 스크립트 경로를 문서에 분명히 박제하세요.