update vs migrate · plan / dry-run · JSON · Gateway 18789
v2026.4.26는 흩어진 설정의 정본을 OpenClaw로 끌어오는 작업을 감각이 아니라 계획·dry-run·JSONdiff로 고정하려는 방향의 릴리스다. openclaw migrate는 plan으로 건드릴 경로와 프로바이더 면을, dry-run으로 실제로 바뀔 키 후보를 먼저 노출하고, Claude Code·Desktop에 쌓인 프롬프트·MCP·Skill·자격 힌트를 충돌 검사와 함께 병합하는 흐름도 포함한다. 그런데 클라우드에서 빌린 Mac은 OPENCLAW_PLUGIN_DIR을 읽기 전용 상위 레이어에 두기 쉽고, 그때 증상은 종종 “어느 날 의존성 설치만 반쯤 실패한 것처럼” 보인다. 본고는 노드 이전·조직 합병·Claude 워크스페이스를 소스 오브 트루스로 쓰려는 운영자를 위해 (1) update만으로 충분한 경계 (2) migrate를 택해야 하는 경계 (3) 여덟 단계 현장 런북 (4) 변경 티켓에 붙일 네 문장 (5) SSH 밖의 VNC 검증 표를 정리하고, 공식 Docker·Compose, launchd 안정 운영, 자주 나는 오류 10가지 해결, 4.25 콜드 플러그인 레지스트리를 이 블로그 데이터에 실제로 등록된 파일명으로만 연결한다. 역사적 비교는 3.x 설정 이전 가이드를 함께 읽으면, “다섯 줄 체크리스트만 베끼던 시기”와 지금의 machine-readable 계획의 차이가 분명해진다.
패치 데이에 버전 숫자만 올리는 경우 openclaw update와 openclaw doctor로 대부분 정리된다. 문제는 노트북 두 대와 객체 저장소에 “각자 조금씩 다른 정본”이 공존할 때다. update는 한 계보의 최신화이고 migrate는 구조와 권위의 병합이다. 섞으면 Gateway 포트, 상대 경로, state 디렉터리 별칭이 블랙박스가 되어 plugins repair를 반복해도 원인이 남는다.
4.26의 Claude 측 일괄 가져오기는 채팅 붙여넣기와 다른 감사 계층을 요구한다. dry-run JSON에서 어떤 키가 추가이고 어떤 키가 canonical로 흡수되는지 검토자가 읽어야 하며, 자격 증명 힌트는 티켓에 날 것으로 올리지 않는다. 이미 Docker로 Gateway를 올리고 launchd로 재시동을 관리한다면, migrate 직후 compose 볼륨과 plist 환경이 서로 모순되지 않는지 교차 확인해야 한다.
레지스트리 관점의 혼합 증상은 4.25 글 톤으로 읽는 편이 안전하다. migrate 한 방으로 혼합 바이너리 문제가 사라진다는 보장은 없으므로, 검수 게이트를 분리해 야근 다음 날의 “반쯤 새 버전” 리스크를 줄인다. 단순 패치만 따르는 단일 호스트에서는 migrate를 의식적으로 돌리지 말고 로그 노이즈와 감사선만 흐리지 않도록 한다.
첫 분류가 빠른 팀이 운영도 빠르다. 혼합 Gateway는 4.25 repair 절차와 같이 읽는다.
| 현상 | 1순위 | 다음 | 피할 것 |
|---|---|---|---|
| 패키지만 오래됨 | update + doctor | 캐시·권한 | 전 트리 migrate |
| 새 호스트·경로 전부 변경 | migrate plan+JSON | secrets diff | 손복사 JSON을 정본화 |
| 정본이 Claude | 4.26 병합+dry-run | 티켓에 마스킹 | 이중 장부 영구화 |
| 읽기 전용 설치 | 쓰기 루트 설계 | plugins repair | chmod 777 의례 |
| 업그레이드 후 혼합 Gateway | 바이너리·레지스트리 정합 | 4.25 | 재시작만 |
각 단계는 변경 티켓 제목에 붙일 수 있다. Gateway를 소유한 대화형 사용자와 같은 VNC 세션을 열어두고 브라우저·시스템 동의를 SSH 로그가 아니라 화면에서 닫는다. 18789는 로컬 루프인지 역프록시인지 미리 고정하고 dry-run JSON의 리스너 기술과 맞춘다.
원격 Mac에서 운영자가 자주 놓치는 것은 “같은 포트 번호가 문서·환경·역프록시 세 군데에서 각각 다르게 적힌 상태”다. migrate JSON이 listener 바인딩을 보여 줄 때, 열 가지 해결 글의 분류표와 함께 읽으면 401 난사·WS 끊김 같은 2차 증상을 빨리 거른다. 백업 단계에서 스냅샷을 안 남기면 롤백이 아니라 복구 공학이 되므로, 클라우드 벤더의 볼륨 스냅샷도 변경 창에 명시하라.
지문:openclaw --version, 전체 doctor, 채널, 컨테이너 여부.
백업:claw backup+가능하면 데이터 볼륨 스냅샷.
Plan:plan 하위 명령으로 경로·플러그인·secrets 면을 나열.
Dry-run·JSON:추가·canonical 변경·인간 선택 항목을 구분.
Claude 병합 검토:마스킹 후 OpenClaw 정본과 대조, 위키에 승자 기록.
쓰기 루트·OPENCLAW_PLUGIN_DIR:설치 실체 확정→plugins repair·doctor.
Gateway:18789 헬스·WS, 10 해결 분기.
CR 고정:dry-run 대비 apply, 롤백, Docker/launchd 의존 명시.
openclaw --version && openclaw doctor claw backup openclaw migrate <plan|dry-run 문서 기준> openclaw plugins repair openclaw status
OPENCLAW_PLUGIN_DIR 문제는 쓰기성 클래스로 분류한다.공유 호스트에서는 절전·디스플레이 정책이 plist 기대와 어긋나기 쉽다. VNC 세션을 켠 채로 검수하는 이유는 이 다이어그램을 “추측”이 아니라 화면 증거로 남기기 위해서다.
18789 콘솔을 브라우저 개발자 도구와 함께 보면서 WebSocket 프레임이 주기적으로 끊기지 않는지 확인하라. 작은 끊김이 크론·heartbeat·외부 웹훅과 겹칠 때 오류 십 해결에 적힌 silence 클래스 증상으로 변형된다.
| 항목 | VNC에서 | 합격 |
|---|---|---|
| 루프백·역프록시 | 개발자 도구·WS | 401 연쇄 없음·WS 안정 |
| 시스템 권한 | 동의 대화상자 | 동일 사용자로 종료 |
| 절전 | 장기 작업 정책 | launchd와 일치 |
| 플러그인 UI | GUI 목록 | plugins list와 일치 |
볼륨, 루프백, 컨테이너 vs 베어 메탈.
읽기 →트리 변경 후 환경·상주 정합.
읽기 →repair 주기·혼합 Gateway.
읽기 →단일 호스트면 update. 이전·대량 가져오기면 plan/dry-run.
쓰기 가능 볼륨 확정 후 plugins repair. 4.25와 연계.
CLI·JSON만 해당. 절05 UI·동의는 VNC.
4.26 대형 병합, 4.25 상시 repair·버전 정합.
migrate는 tarball을 옮긴 기분이 아니라 차이가 증명되는 작업으로 바꾼다. 그러나 읽기 전용 레이어·절전·SSH와 GUI 사용자 불일치 같은 환경 부채를 남기면 실패는 다시 “누군가 확인을 안 눌렀다”는 형태로 돌아온다. 자체 금속 서버는 자본·전력·야간 패치를 감수하는 계약이다. 팀이 지키고 싶은 것이 병합 감사 경계라면 SSH와 검토 가능한 GUI를 함께 가진 Apple Silicon 임대 Mac에 운영 기반을 두는 편이 현실적이다.
본고 8단계를 한 세션에서 실행하려면 VNCMac에서 노드를 고르고 구매 페이지와 홈 사양을 대조하라. OpenClaw 다국어 글을 폴더처럼 엮어 읽으면 upgrade·migrate·정기 건강의 경계가 동시에 정리된다.