openclaw update · 백업 고정 · doctor · 롤백
이미 OpenClaw를 운영 중인 팀은 openclaw update를 실행할 수 있는지보다, 명령이 끝난 뒤 Gateway가 기동하지 않거나, 포트가 옛 프로세스에 잡혀 있거나, PATH가 낡은 바이너리를 가리키거나, 설정 마이그레이션이 도구 설정을 조용히 덮어쓰는지에서 더 자주 고통받습니다. 본문은 다섯 가지 반복 업그레이드 위험을 풀고, 공식 update·전역 npm·소스 빌드 비교표, 백업과 채널 정책을 담은 여섯 단계 Runbook, 업그레이드 후 doctor와 health 순서, 포트 충돌·이중 설치 증거표를 제시합니다. 멀티 플랫폼 설치와 데몬, 설치와 doctor 트러블슈팅, 런타임 트러블슈팅과 상호 링크해 업그레이드·관측·롤백을 한 페이지에 맞춥니다.
공식 가이드는 openclaw update 후 openclaw doctor를 권장하지만, 운영 스택에는 패키지 관리자 전환을 데몬이 따라가지 않거나, 옛 Gateway가 리스너를 놓지 않거나, 한 호스트에 CLI가 여러 갈래로 남는 문제가 겹칩니다.프로덕션 강화 체크리스트를 읽었다면 채널 허용 목록과 리스닝 면 축소가 업그레이드 순서와 강하게 엮인다는 것을 압니다. Gateway를 멈추지 않고 패키지만 바꾸면 18789가 낡은 PID에 붙은 채로 남는 증상이 흔합니다.
업그레이드를 고립된 CLI 이벤트로만 보면 버전 번호와 리스닝 면·신원 자료를 잇는 실이 끊깁니다. 지속 가능한 운영은 먼저 실패 모드를 문서화합니다: 프로세스 드리프트, 조용한 설정 이전, 채널 공급 리듬 충돌, 약한 롤백 증거, 불완전한 헬스 원격 측정. 아래 각 항목은 변경 티켓에 붙일 아티팩트에 대응하며, 「update를 쳤다」에서 「버전 문자열과 백업 경로로 어떤 실패도 설명한다」로 올라갑니다. 스테이징에서 동일 순서를 한 번 밟아 두면 본 창에서 판단이 빨라지고, doctor 경고 시 어디서 멈출지도 합의하기 쉽습니다.
프로세스와 패키지 버전 드리프트: 전역 npm은 새 빌드를 가리키는데 launchd나 systemd는 옛 작업 디렉터리에서 빌드한 바이너리를 올려 openclaw --version과 gateway status가 엇갈립니다.
설정 이전과 조용한 덮어쓰기: 메이저는 openclaw.json 의미를 바꿀 수 있고 doctor가 이전을 시도하지만, 병합 규칙이 GitOps 리뷰와 어긋나면 디스크만 바뀌고 PR은 없는 상태가 됩니다.
자동 업데이트 채널과 변경 창 충돌: 안정 채널 지연·지터는 전 함대 동시 폭발을 막기 위한 것이나 비즈니스 릴리스 창과 맞지 않으면 금요 밤 계획 없는 재시작이 납니다.채널 프로브와 함께 쓸 때는 콜백을 믿기 전에 Gateway가 실제로 재시작했는지 확인합니다.
롤백 증거 부족: 백업이나 버전 고정 기록이 없으면 알려진 양호 상태로 돌아가지 못하고 「최신을 다시 설치」만 반복합니다.상주 클라우드 배포와 겹치면 노드에 cron·외부 webhook이 있어 롤백 순서가 틀리면 중단 시간이 증폭됩니다.
관측 필드 누락: 「업그레이드 성공」 스크린샷만 남기고 gateway status --deep과 바인드 주소를 보관하지 않으면 사후에 노출 면이 보안 기준선에 맞았다고 증명하기 어렵습니다.
위 다섯 가지를 출격 전 체크리스트로 만든 뒤 다음 절에서 설치 경로를 비교하면 「업데이트할 수 있다」가 「감사하고 롤백할 수 있는 업데이트」로 승격됩니다. 개인 노트북의 절전·OS 유지보수 창도 데몬 상태를 잠깐씩 흔들고, 계약 SLA를 쓸 수 있는 클라우드 Mac 노드여야 업그레이드 창과 가용성을 인수 기준에 넣기 쉽습니다.
운영 리드는 각 호스트가 개발자 랩톱·공유 빌드 에이전트·전용 Gateway 중 무엇인지도 기록해야 합니다. 같은 CLI 버전도 launchd가 옛 WorkingDirectory를 가리키는 plist를 읽을 때와 systemd가 고정 컨테이너 이미지 안에서 돌 때 다르게 행동합니다. 티켓에 역할을 적어 두면 「내 머신에선 된다」가 「패치 화요일 뒤 수수께끼 운영 드리프트」로 번지는 것을 막습니다.
세 경로에 절대적인 우열은 없고 팀 규모, 감사용 커밋 고정 여부, Gateway 자동 재시작 허용 여부에 맞는지가 중요합니다. 공식 update 서브커맨드는 대부분의 팀에 맞고, 전역 패키지 관리자는 CI 이미지에, 소스 빌드는 패치를 내거나 dev 채널을 잠가야 하는 그룹에 맞습니다.
아래 매트릭스를 운영 핸드북에 적어 두면 책임 공백도 사라집니다: 빌드는 언제 이미지를 다시 짓는지, 플랫폼은 언제 systemd 유닛을 만지는지, 애플리케이션은 언제 doctor 출력을 규정 준수용으로 보관하는지. openclaw.json에 깨지는 필드가 들어온 릴리스에서 어떤 환경이 어떤 마이그레이션을 적용했는지 증명해야 할 때 이 명확함이 값어칩니다.
| 차원 | openclaw update | 전역 npm / brew | Git 소스 빌드 |
|---|---|---|---|
| 학습 곡선 | 낮음; 한 명령으로 가져오기·doctor·재시작 힌트 연쇄 | 중간; doctor와 Gateway 재시작을 직접 연결 | 높음; pnpm 빌드와 PATH 위생 |
| 버전 추적 | 중간; 릴리스 메타데이터 의존 | 강함; 패키지 semver 고정 | 강함; commit SHA 고정 |
| 롤백 경로 | 중간; 고정 릴리스와 백업 필요 | 강함; npm i -g openclaw@x | 강함; git checkout 후 재빌드 |
| 자동화 적합성 | 강함; runbook에 자연스러움 | 강함; 이미지 레이어에 자연스러움 | 약함; 긴 빌드와 캐시 복잡도 |
| 데몬과의 상호작용 | 명시적 stop 후 start 순서 필요 | 동일 | 이중 경로 설치 위험 최대 |
지속 가능한 업그레이드는 실패를 버전 번호와 백업 경로로 설명할 수 있는지에 달려 있으며, Gateway가 가끔 뜨는지와는 무관합니다.
이미 install-daemon 안내를 따른다면 본 절 결론을 핸드북에 옮겨 「문서는 brew, 실제는 npm, cron은 세 번째 경로」 삼체 문제를 피하세요.
다음 여섯 단계는 온콜 플레이북에서 한 줄씩 체크할 수 있게 썼습니다. 설치 방식과 무관하게 순서만 맞추면 신입도 한 시간 안에 연습할 수 있습니다.런타임 삼분할과 함께 쓸 때는 업그레이드 후 gateway status 일부를 남겨 채널 문제와 모델 층 문제를 분리하세요.
창을 고정하기 전에 아웃바운드 webhook이나 공유 API 키에 의존하는 하류 담당자에게 알리세요. Gateway 업그레이드와 같은 밤에 자격 증명을 돌리면 피해 반경이 커집니다. 외부 비밀 저장소를 쓴다면 Gateway를 멈추기 전 가용성을 확인하세요. 그렇지 않으면 doctor는 통과하지만 런타임 호출은 실패하는 반쯤 설정된 상태로 부팅할 수 있습니다.
변경 창 고정: 티켓에 목표 semver와 허용 중단 분을 기록합니다. 대규모 모델 키 로테이션과 같은 밤에 묶지 않습니다.
설정·신원 경로 백업: 공식 백업 명령을 쓰거나 최소한 ~/.openclaw 아래 설정·신원 관련 디렉터리를 아카이브하고 체크섬을 검증합니다.
Gateway 정상 종료: openclaw gateway stop 후 리스너가 비었는지 확인하고 업데이터를 실행합니다. 반쯤 업그레이드된 상태로 포트를 붙잡지 않습니다.
업데이트 적용·채널 기록: openclaw update를 쓰면 출력의 버전과 채널 메타데이터를 티켓 색인 필드에 붙입니다.
doctor 후 health 순서: 이전 힌트와 경고를 수집합니다. 예상 밖 필드가 바뀌면 자동 재시작을 멈추고 수동 diff를 봅니다.
채널 프로브·최소 메시지: 허용된 환경에서 프로브를 보내거나 channels status를 호출해 콜백이 여전히 스택에 닿는지 확인합니다.
openclaw gateway stop openclaw update openclaw doctor openclaw gateway start openclaw health openclaw gateway status --deep
안내: update 내장 재시작이 수동 스크립트와 경쟁하면 잠시 이중 리스너가 보일 수 있습니다. 멈춤·설치·시작을 직렬화하고 병렬화하지 마세요.
커뮤니티에서는 「업그레이드 후에도 포트가 바쁘다」 「CLI는 새 버전인데 프로세스는 옛 빌드」가 자주 나옵니다. 설정을 의심하기 전에 바인드 주소·프로세스 바이너리 경로·패키지 위치에 대한 단일 진실로 수렴해야 합니다.설치와 doctor 체크리스트와 함께 읽을 때 아래 목록을 티켓 부록으로 붙이세요.
lsof 또는 동등 출력과 which openclaw를 함께 문서화하면 좀비 프로세스와 잘못 연결된 서비스 유닛을 가르는 데 충분한 신호가 됩니다. 공유 호스트에서는 Gateway가 도는 실효 사용자 ID도 잡으세요. 한 계정의 프로필 스크립트는 다른 계정에 적용되지 않습니다.
포트 사용 중: lsof -i :18789 등으로 옛 PID가 보이는 증거. 먼저 gateway stop, 실패할 때만 절차에 따라 안전 종료 후 잔여 확인.
이중 설치 경로: which openclaw와 npm root -g 접두사가 다름. PATH 정규화·불필요한 글로벌 제거·별칭 고정.
데몬 유닛 미갱신: plist나 unit이 옛 WorkingDirectory를 참조. 데몬 재설치 또는 문서의 강제 설치 단계 후 kickstart.
설정 검증 실패: doctor가 필드 이전 충돌을 보고. 백업에서 복원·단계 업그레이드·JSON 수동 병합 후 doctor 재실행.
헬스 가짜 초록: health는 통과하지만 채널에 콜백 없음. 런타임 트러블슈팅 글을 따르고 일찍 종료하지 않음.
롤백 후에도 이상: 환경 변수나 셸 시작 스크립트가 옛 NODE_PATH를 주입. 로그인 세션과 CI 이미지 레이어 캐시 정리.
주의: 공유 노드에서 동료 프로필에 남은 임시 export 경로는 개인 실험을 전 함대 사고로 바꿉니다. 풀에는 Unix 사용자를 나누거나 컨테이너 경계를 쓰세요.
아래 세 가지는 OpenClaw를 굴리는 많은 소규모 팀이 관찰하는 구간을 요약한 것으로, 프로젝트 전 검토용이며 벤더 보장이 아닙니다. 자체 티켓 측정으로 바꾸세요.
임계값은 담당자와 짝을 이룰 때 가장 잘 작동합니다: 창 동안 프로브 대시보드를 볼 사람, P95 예산을 넘기는 중단을 승인할 사람, 백업 보존 정책을 규정과 맞출 사람. 이름이 없으면 숫자는 장식이 됩니다.
| 팀 규모 | 변경 빈도 | 위험 감수 | 더 안정적인 기본 선택 |
|---|---|---|---|
| 개인 | 애드혹 | 높음 | 공식 update와 수동 정지·기동, zip 백업 유지 |
| 소규모 팀 | 주간 | 중간 | npm semver 고정, 변경 티켓, doctor 출력 보관 |
| 플랫폼 | 일간 | 낮음 | 이미지 빌드, 카나리 노드, 자동 프로브 |
| 외주 협업 | 불규칙 | 중간 | 읽기 전용 runbook과 전용 노드, HOME 공유 금지 |
개인 기기의 절전·디스크 여유·OS 패치는 데몬을 끊임없이 방해합니다. CLI 규율이 완벽해도 노트북에서 감사 가능한 업그레이드 SLA를 만들기 어렵고, 계약할 수 있는 클라우드 Mac Mini 노드여야 프로세스 가동 시간·인그레스·유지보수 창을 약정에 적을 수 있습니다.
흔한 오해: health 통과를 채널과 모델까지 건강한 증거로 봄—health는 부분 집합만 덮고 전체 수락은 여전히 런타임 트리아지 순서를 따릅니다.
롤백에 유리하고 Gateway 수명 주기를 관측할 수 있는 OpenClaw 업그레이드가 필요하고, 노트북 절전이 에이전트를 끊지 않도록 노드를 온라인으로 두고 싶다면—특히 프로덕션 자동화와 iOS 관련 빌드 환경이 걸릴 때—VpsMesh Mac Mini 클라우드 임대가 종종 더 적합합니다: 예측 가능한 과금, 선택 가능한 리전, 감사 가능한 전용 하드웨어로 업그레이드 논의를 실제 가용성 데이터 위에 올립니다.