2026 OpenClaw 이전 및 콜드스타트 런북: 디렉터리 복사부터 첫 게이트웨이 연결까지(systemd 대 launchd)
~/.openclaw와 워크스페이스 트리를 새 머신으로 복사하는 일은, 곧바로 “운영 중인 배포”와 같지 않습니다. 증상은 대개 실행 파일이 없거나, 잘못된 HOME 아래에서 데몬이 뜨거나, 페어링은 된 것처럼 보이지만 채널이 응답하지 않는 형태로 뭉칩니다. 이 글은 매체, 환경, 서비스, 그다음 채널 순으로 점검하는 흐름을 안내하고, 내부 런북에 붙일 수 있는 systemd와 launchd 비교, 복사해 쓸 수 있는 프로브가 들어간 콜드스타트 7단계, FAQ를 정리합니다. 다음 층은 VPSMAC의 설치 경로 글과 상태에서 doctor까지의 사다리 글을 이어 읽으면 됩니다.
이 글에서 다루는 내용
1. 고통 포인트: 복사한 트리만으로는 그대로 실행되지 않는다
노트북이나 오래된 VPS에서 새 호스트로 옮길 때, 디렉터리 목록이 같으면 동작도 같을 거라고 가정하는 팀이 많습니다. OpenClaw는 실제로 네 겹이 맞물려 있습니다. PATH에서 어떤 openclaw 바이너리가 이기는지, ~/.openclaw 아래의 온디스크 설정 트리, 워크스페이스를 기준으로 한 자산, 그리고 systemd나 launchd가 제공하는 감독자 컨텍스트입니다. 이 중 하나라도 빠지면 SSH 세션 안에서는 괜찮아 보이다가 연결이 끊기거나 재부팅 후 게이트웨이가 사라지는 식의 간헐 증상이 납니다.
운영 관점에서는 “파일은 있는데 프로세스가 말을 안 한다”는 상태가 가장 곤란합니다. 로그 경로가 쓰기 불가능하면 표준 에러가 비어 있고, launchd plist의 PATH가 비어 있으면 셸에서 보이던 node 경로가 사라집니다. 반대로 Linux의 systemd --user는 로그인 셸을 거치지 않으므로, 단위 파일에 명시하지 않은 변수는 아예 존재하지 않는 것과 같습니다. 따라서 이전 직후에는 채널이나 외부 API를 의심하기 전에, 로컬에서 재현 가능한 신호부터 고정하는 것이 비용 대비 효과가 큽니다.
- 머신마다 달라지는 CLI: 이전 호스트는 전역 npm을 썼는데 새 Mac 클라우드 이미지는 Homebrew 경로나 정적 설치 스크립트 레이아웃만 제공하는 경우가 많습니다. JSON만 복사한다고 바이너리가 설치되지는 않습니다. pnpm 워크스페이스와 전역 패키지가 섞이면 버전 문자열은 같아도 동적 로더 경로가 달라 “같은 버전인데 다른 바이너리”가 될 수 있습니다.
- 깨진 데몬 컨텍스트: Linux에서는
systemd --user단위가Environment=HOME=...를 명시하는 경우가 흔합니다. macOS의 LaunchAgent는 로그인 셸 rc를 물려받지 않으므로, nvm 스타일 접두어는 절대 경로나 얇은 래퍼 스크립트를 넣지 않으면 사라집니다. 잘못된WorkingDirectory는 로그와 자격 증명 조회가 엉뚱한 위치를 향하게 만들어 조용히 실패합니다. - 잘못된 트리아지 순서:
openclaw.json문법과 18789 포트를 확인하기 전에 채널 페어링부터 건드리면 시간만 낭비합니다. 로컬 프로브가 초록색이 되기 전에는 상위 메시징 표면을 만지지 않는 것이 원칙입니다. - rsync 이후 소유권: root로 복사한 뒤 애플리케이션 사용자에게 넘긴 트리는 읽기는 되어도 표준 에러 로그에는 쓸 수 없어, 원인 모를 멈춤처럼 보일 수 있습니다.
2. systemd 대 launchd 환경 매트릭스
아래 표는 변경 티켓 부록으로 붙이기 좋게 짧게 정리했습니다. “먼저 볼 것” 열은 채팅 제공자나 방화벽을 탓하기 전에 호스트에서 확인해야 할 첫 관문입니다.
목적지가 장기 Mac 클라우스 인스턴스라면, 먼저 launchd에 절대 경로와 로그 파일을 고정하고, 그다음 Docker 분할이 추가 볼륨과 uid 복잡도를 감당할 가치가 있는지 판단하는 편이 안전합니다. Linux에서 이미 다른 사용자 수준 데몬을 systemd --user로 돌리고 있다면, OpenClaw도 같은 슬라이스 제한에 맞춰 무거운 xcodebuild 이웃이 Gateway 응답을 굶기지 못하게 정렬하십시오.
| 차원 | Linux(systemd 사용자 단위) | macOS(LaunchAgent) | 이전 직후 첫 확인 |
|---|---|---|---|
| 환경 변수 | Environment= 줄 또는 drop-in | 셸 상속 없음; plist 또는 래퍼 필요 | HOME, PATH, API 키 주입 확인 |
| 작업 디렉터리 | WorkingDirectory= | WorkingDirectory 키 | 상대 경로 비밀과 맞는 워크스페이스 루트인지 |
| 로그 | journalctl --user -u ... | StandardOutPath / StandardErrorPath | 파일 소유권이 쓰기 가능한지 |
| 부팅 지속성 | enable --user | RunAtLoad와 올바른 부트스트랩 도메인 | SSH 자식 프로세스 없이 재부팅 테스트 |
| 권한 | uid·gid와 선택적 cgroup | 샌드박스와 툴체인에 따른 전체 디스크 접근 | 키체인과 개인정보 프롬프트는 별도 시나리오 |
3. 첫 성공적인 연결까지의 콜드스타트 7단계
이 단계들은 사람이 읽을 수 있는 신호를 앞에 두고, 외부 계정이 꼭 필요한 작업은 뒤로 미룹니다. 야간 전환 창에서는 단계별 예상 분을 메모해 두면, 인시던트 리드가 범위를 즉석에서 논쟁하지 않고 계속할지 롤백할지 선택할 수 있습니다.
- 버전과 매체 고정: 이전 호스트에서
openclaw --version, npm 대 pnpm 대 설치 스크립트 대 이미지 digest를 기록합니다. 트리를 복사하기 전에 새 호스트에서 설치 경로 글을 보고 단일 진입점을 정해, 실수로 두 바이너리를 섞지 않게 합니다. - 디렉터리 동기화:
~/.openclaw와 워크스페이스에rsync -aH또는 동등한 방법을 쓰고, 대용량 캐시는 팀 제외 규칙을 따릅니다. 전송 직후 중요 파일의 mtime·크기를 비교해 부분 전송을 빨리 잡습니다. - 권한과 비밀 도달성:
ls -la ~/.openclaw를 실행합니다. Docker 흐름이면 설치 가이드의 Docker 절을 다시 보고 bind mount와 uid 매핑을 검증합니다. - 서비스 단위 작성: Linux는 환경 줄이 명시된
systemd --user단위를 씁니다. macOS는ProgramArguments에openclaw의 절대 경로를 넣은 LaunchAgent입니다. 릴리스마다 기본값이 바뀔 수 있으니 listen 주소와 포트를 명시하는 편이 좋습니다. - 로드와 콜드스타트:
systemctl --user daemon-reload && restart또는launchctl bootstrap뒤kickstart. 부모 프로세스가 SSH 세션이 아니라 systemd 또는 launchd인지 확인합니다. - 로컬 프로브:
lsof -i :18789, 최소한의 JSON 검증, 그다음 사다리 글에 따라openclaw doctor. 프로브가 빨간 동안에는 채널 토큰을 돌리지 않습니다. - 채널 스모크 테스트: Gateway 로그가 건강해 보일 때만 페어링을 고칩니다. 감사를 위해 명령 전사본을 변경 기록에 남깁니다.
빠른 명령 블록: which openclaw; openclaw --version; test -r ~/.openclaw/openclaw.json && echo ok; 팀 정책에 맞는 curl류 프로브로 바인딩 주소를 확인합니다. 기업 프록시 뒤에 있으면, 개인 SSH 계정이 아니라 서비스 사용자로 이그레스 검사를 실행해, 사람은 curl 되는데 데몬은 안 되는 거짓 음성을 피합니다.
4. 참고 불릿: 경로, 18789 포트, 감사 필드
이 절은 위키 부록에 가깝고, 번호가 매겨진 단계는 내러티브입니다. 둘을 같이 두면 사후 분석에서도 순서와 체크리스트 깊이를 동시에 확보할 수 있습니다.
- JSON의 단일 진실 공급원: 어떤 머신이 정본
openclaw.json을 소유하는지, 백업을 어떻게 뜨는지 문서화합니다. 이전 후에는 서비스를 켜기 전에 구·신 파일을 diff해 반쯤 쓴 병합을 막습니다. - 포트 경합: 한 Mac 클라우드 호스트에 여러 실험용 게이트웨이가 있으면 포트를 분리하거나 라벨을 멈춰야 합니다. 경합은 흔들리는 연결처럼 보이기 쉽습니다.
- 감사 최소치: 매체, semver, 단위 또는 plist 라벨, 컨테이너라면 이미지 digest, 첫 초록 doctor 요약, 채널 계정 id, 페어링 시각, 규제 환경이면 운영자 id.
- 롤백: 이전 호스트에 마지막으로 알려진 양호한 단위 파일과 패키지 또는 이미지 태그를 보관합니다. 분기별 드릴로 그 스냅샷 이후에 돌린 키 회전까지 RTO 안에 복구 가능한지 확인합니다.
- 상위 리스크: 설치와 감독자 층이 통과한 뒤에는 ClawHub Skill 공급망 주제를 2026년 4월 감사 체크리스트 글의 틀로 다룹니다.
- 타임존: 지역이 다른 로그를 상관시키기 전에 NTP와 표시 타임존을 맞춰 인과를 추론합니다.
5. 자주 묻는 질문
Q: 워크스페이스만 복사했고 ~/.openclaw는 안 옮겼습니다. Gateway가 뜰 수 있나요?
키와 로컬 상태가 빠집니다. 두 볼륨을 함께 이전하거나, 이전 호스트에서 읽기 전용보내기 체크리스트를 들고 비밀을 의도적으로 재구성하십시오.
Q: launchctl에는 loaded인데 18789에서 아무것도 안 들을 때는?StandardErrorPath, WorkingDirectory, plist의 PATH를 봅니다. 에러 파일이 비어 있으면 로그가 쓰기 불가능한 경로로 향했을 수 있습니다.
Q: Linux systemd 단위를 macOS에서 그대로 재사용할 수 있나요?
안 됩니다. LaunchAgent로 다시 쓰고 환경 변수와 로그 경로를 한 줄씩 재검증하십시오.
Q: 채널은 조용한데 18789는 로컬에서 응답합니다.
먼저 Gateway 로그를 읽고, 그다음 상위 네트워크와 허용 목록을 봅니다. 최근 편집으로 바인드 주소가 어긋난 경우를 배제하기 전에 전체 설정을 날리지 마십시오.
Q: 비교를 위해 구 인스턴스를 나란히 두고 싶습니다.
포트와 라벨을 분리하고, 실험 단위가 운영 JSON에 이중 쓰기를 하지 못하게 금지합니다.
6. 파일럿에서 프로덕션까지, 네이티브 Mac 클라우드에서
런북의 복잡도는 SSH 접근이 프로덕션과 얼마나 비슷한지에 비례합니다. 중첩 가상화는 PATH·볼륨·권한 서프라이즈를 키웁니다. 설치 가이드와 맞춘 launchd를 쓰는 전용 Mac 클라우드 호스트가, 감사 가능한 콜드스타트까지 가는 가장 짧은 길입니다. 네이티브 경로가 지루할 정도로 안정되기 전에는 첫 이전 창에 Docker 샌드박스를 끼우지 마십시오.
OpenClaw 게이트웨이를 장기 자산으로 보면 CI 러너와 같은 인프라 동료입니다. 디스크를 확보하고, 로그를 회전하고, 노드에 태그를 달고, 로그인 감사를 연결합니다. 팀원 모두가 같은 plist와 디렉터리 계약을 따르면, 다음 이전은 노트북마다 즉흥적으로 짜는 대신 알려진 플레이북을 반복하게 됩니다.