1. 문제 분해: 저장소 복사 ≠ 런타임 복사
(1) 상태 디렉터리와 워크스페이스: 팀은 스킬·프롬프트·커밋된 openclaw.json을 저장소에 두지만 세션·채널 바인딩·게이트웨이 캐시는 사용자 프로필 아래에 남는다. Git만 옮기면 CLI 명령은 돌아가도 목적지에는 유령 세션이나 빈 채널 상태가 생긴다. (2) 시크릿과 OAuth 리프레시 토큰 분산: Slack·Discord·기업 메신저는 평문 설정과 암호화된 런타임 저장소 양쪽에 둘 수 있다. 한 층만 백업하면 재인증이 필요하고, 이전 게이트웨이를 멈추지 않으면 두 엔드포인트가 같은 봇 세션을 두고 경쟁한다. (3) launchd와 대화형 셸: launchd는 .zshrc 내보내기를 물려받지 않는다. API 키를 터미널 프로필에만 두고 plist가 비어 있으면 “수동 전경은 되고 예약 데몬은 변수를 못 본다” 패턴이 난다. (4) 원격 Mac 사용자 경계: 화면 공유나 SSH에 쓰는 계정과 게이트웨이 실행 계정이 같아야 한다. root와 로그인 사용자를 섞으면 파일 소유권과 키체인 접근이 갈라져 디버깅 시간이 폭발한다.
2. 매트릭스: 2026 콜드 이전 번들에 무엇이 들어가나
| 대상 | 경로·의미 | 번들 포함? |
|---|---|---|
| 사용자 상태 트리 | ~/.openclaw(릴리스마다 하위 이름은 상위 문서 기준) |
예: 채널 바인딩, 캐시, 로컬 비밀 |
| 워크스페이스·프로젝트 | 스크립트, 스킬, 버전 관리된 openclaw.json |
예: 상태와 같은 스냅샷 시각을 공유해야 스키마 어긋남이 없다 |
| launchd 작업 | ~/Library/LaunchAgents/ 게이트웨이 plist |
예: 런타임 사용자, 작업 디렉터리, 환경 키 이름 |
| Docker 볼륨 | Compose의 이름 볼륨 또는 바인드 마운트 | 조건부: Docker 프로덕션 레이아웃과 맞출 때만 스냅샷 |
| macOS 키체인 항목 | 일부 채널이 리프레시 토큰을 키체인에 둔다 | 주의: 규정상 임의 덤프보다 벤더 재인증 흐름을 선호 |
3. 다섯 단계: 동결 → 묶기 → 검증 → 콜드 스타트 → 재페어
1단계 — 쓰기 동결: 게이트웨이·launchd·Compose를 멈춰 SQLite 락이 백업 중 변하지 않게 한다. cron·CI 웹훅도 잠시 끄고 docker ps로 깨끗함을 남긴다.
2단계 — 스냅샷 짝짓기: ~/.openclaw·워크스페이스·락파일을 동시에. Docker면 볼륨·다이제스트 타임스탬프를 맞추고 경로 대소문자·캐시 재생성 여부를 기록한다.
3단계 — 검증·정리: 체크섬 후 호스트명·절대 경로·LAN URL·IP 리터럴을 고치고 MTU·VPN·DNS를 재검토한다.
4단계 — 콜드 스타트: 루프백으로 openclaw doctor 후 채널. CPU·메모리 기준선을 찍는다.
5단계 — 재페어: 옛 봇 완전 종료 후 OAuth·웹훅. 가능하면 시크릿 로테이션과 채널별 스크립트 검증.
숫자·임계값(인용 가능)
① 스냅샷 삼중주: ~/.openclaw + 워크스페이스 + plist(또는 compose·볼륨 목록). 하나라도 빠지면 불완전 이전이다.
② 환경: launchd plist의 내보내기는 셸에서 의존하는 것과 명시적으로 일치해야 한다 — 최소 API 키·프록시·시간대 관련 변수.
③ 채널 전환: 옛 봇 중지와 새 봇 활성 사이에 냉각 구간을 둔다 — 벤더가 침묵하면 분 단위 그레이 롤아웃으로 가정한다.
④ 원격 Mac: SSH 사용자 = 게이트웨이 사용자 — 대화형 화면 공유와 무인 launchd 사이에 UID를 섞지 않는다.
⑤ 롤백: 쓰기 가능한 사본을 지우기 전에 이전 호스트의 읽기 전용 아카이브를 최소 한 릴리스 주기는 보관한다.
4. 파라미터: “프로세스는 살아 있다”는데 채널만 조용할 때
이전 직후 가장 헷갈리는 패턴은 프로세스 목록과 헬스 프로브는 통과하는데 인바운드가 영원히 안 오는 경우다. 첫째, 바인드 주소: 127.0.0.1에서 LAN IP로 옮겼는데 리버스 프록시나 방화벽을 안 고치면 게이트웨이는 자기에게만 말하고 공개 URL은 옛 IP를 가리킨다. 둘째, 웹훅 URL: 클라우드 콘솔이 새 터널 호스트명·고정 이그레스를 가리켜야 한다 — Slack·플래시 콜백 갱신 빼먹기가 침묵 드롭의 대표 원인이다. 셋째, 시계와 TLS: 코로케이션 Mac의 NTP 크게 어긋나면 서명 요청이 깨지고, 기업 TLS 검사·교체 인증서도 조용히 실패한다. 넷째, tools.profile: 이전 호스트가 절대 경로의 바이너리만 허용했다면 새 PATH에서 도구 호출이 깨진다 — sessions·spawn 런북을 따라 허용 목록을 의도적으로 넓히거나 다시 쓴다.
그래도 원인을 모르겠으면 벤더 티켓 전에 네 가지를 모은다: plist는 삭제한 공개 스냅샷, 벤더가 호출하는 정확한 공개 URL, TLS 핸드셰이크가 도착하는지 보는 tcpdump·프록시 트레이스, 인바운드 이벤트 ID 한 사이클을 덮는 게이트웨이 로그 슬라이스. 채널마다 대시보드 필드와 설정 키를 매핑한 짧은 용어집을 유지하라.
5. 판단표: 노트북에 둘까, 원격 전용 Mac에 둘까
| 축 | 로컬 노트북 | 원격 전용 Mac |
|---|---|---|
| 가용성 | 뚜껑 닫힘·수면·이동 | 채널 부하에 더 깨끗한 24/7 경계 |
| 권한·디버깅 | GUI로 빠르게 | 헤드리스 규율 — 블로킹 프롬프트 회피 |
| 네트워크 | 가정용 IP 변동 | 안정 이그레스·터널 도메인이 웹훅에 유리 |
| 비용 | 숨은 감가 | 투명한 임대가 SLA 지향 팀에 맞는다 |
6. FAQ: 이전 때 자주 듣는 다섯 가지
Q: 워크스페이스만 동기화하면? 순수 CLI 실험이면 되지만 채널이나 세션 연속성이 중요하면 강하게 비권장 — tarball 크기보다 시간을 더 태운다. Q: Docker에서 베어 메탈로? 스택 변경 + 이전으로 취급하고 목표 형태를 하나만 정해 문서화하라. Q: plist에 평문 API 키? 동작은 하지만 위생에 어긋난다 — plist가 가리키는 잠긴 env 파일이나 관리 비밀 백엔드를 선호하라. Q: 원격 Mac에 화면 공유가 항상 필요? 일상은 SSH, 최초 OAuth나 GUI 전용 도구만 VNC — 변경 티켓을 남긴다. Q: 옛 노트북을 바로 지울까? 한 영업 주기 병행 관측 후 파괴적 삭제.
Q: 같은 창에 업그레이드까지? 동일 버전 이전 후 별 티켓으로 업그레이드. Q: MDM Mac? plist·확장 허용 조율. Q: 다지역? 데이터 거주 검토.
7. 심화: 이전은 코드가 아니라 상태와 정체성을 함께 옮기는 일
핵심 질문은 상태 읽기·쓰기와 외부 정체성 매핑이다. openclaw.json과 프로필 디렉터리를 한 트랜잭션으로 옮기지 않으면 doctor만 초록이다.
launchd 덫: .zshrc만 채우고 plist를 비우면 401. plist만 과다하면 로그 경로 소유 때문에 로테이션이 멈춘다 — plist·셸·CI를 한 표로 검증하라.
재페어는 단일 엔드포인트 규칙이다 — 옛 인스턴스 완전 폐기 후 신규 승격, 벤더별 쿨다운·IP 정책이 다르다.
원격 Mac은 GUI OAuth와 무인 launchd를 분리하고, MACGPU류 노드로 게이트웨이 부하를 고정 토폴로지에 둔다.
관측: 구조화 로그 전송, 알림에 버전·스킬 저장소 SHA, “이전 직후” 태그를 소강까지 유지한다. 이전은 토큰·URL·인증서를 새 금속에 한 번 맞추는 신뢰 회복이다.
8. 마무리: 빨리 가려면 전 단계를 다 밟아야 한다
(1) 한계: 메이저 버전마다 상태 레이아웃이 바뀔 수 있으니 아카이브마다 OpenClaw 시맨틱 버전을 적고, 키체인 전체 복제가 금지된 규정이면 재인증 창을 예산에 넣어라. (2) 원격 Mac이 이기는 이유: 사용자·이그레스·하드웨어 클래스가 고정되어 “노트북을 서버로”의 꼬리 사고가 줄어든다. (3) MACGPU: 토폴로지를 고정하기 전에 임대 Apple 실리콘 노드에서 게이트웨이 호스팅을 리허설하려면 홈페이지 요금제와 도움말로 들어가라. 모든 이전을 다음 이전을 위한 리허설로 취급하면 런북이 시간이 지날수록 단단해진다.