2026 OpenClaw 온보딩: MacLogin 클라우드 Mac에서 launchd 데몬을 설치하고 게이트웨이·Control UI를 안정화하기
MacLogin에서 Apple Silicon을 빌리는 플랫폼 팀은 npm install -g openclaw 직후 자주 멈춥니다. CLI는 있는데 게이트웨이가 지속되지 않고, 노트북에서는 Control UI가 “없어 보이며”, openclaw doctor 경고가 남습니다. 2026년 5월 19일 런북은 openclaw onboard --install-daemon 실행 주체, 포그라운드와의 차이, 티켓에 남길 수치(Node 정확 버전, TCP 18789, 홍콩·일본·한국·싱가포르·미국 리전), SSH만 있을 때 Control UI를 여는 방법을 정리합니다. 자세 매트릭스, 9단계, 로컬 포트 전달, doctor 표를 포함합니다. 이후 npm ci 재현성, curl 헬스, 힙 상한을 이어가세요. pricing, help도 함께 열어두세요.
대상 독자, 첫날 실패, 임대 mini에서 onboard가 필요한 이유
홍콩·도쿄·서울·싱가포르·미국 MacLogin 인스턴스에 게이트웨이를 올려야 하는 시니어 엔지니어·DevEx 리드를 가정합니다. CI처럼 운영하고 슬라이드용 데모가 아닙니다.
- 포그라운드만: SSH 끊김과 SIGHUP에 취약합니다.
launchd는 세션 이후에도 유지되고 재시작 정책을 OS에 맡길 수 있습니다. - Control UI 착시: 브라우저는 로컬,
127.0.0.1은 mini입니다. - Node 드리프트:
node -v를 반드시 붙여 넣으세요. - doctor 미처리: 반쯤 설정된 공급자 키로 부하 시 RPC가 흔들립니다.
- 관측 없음: 합성 프로브 없이는 “기동=건강”으로 보입니다.
MacLogin의 이점은 예측 가능한 베어메탈 Apple Silicon과 일관된 macOS 동작입니다. 도쿄에서 검증한 launchd 템플릿을 싱가포르 지연 실험에 복제해도 x86 놀람이 적습니다.
설치 자세 매트릭스: 포그라운드, onboard 데몬, 수동 plist
| 자세 | 적합 시점 | SSH 후 생존 | 운영 부담 |
|---|---|---|---|
tmux 안 openclaw gateway --port 18789 | 30분 미만 스파이크 | 래퍼에 따라 | 높음 |
openclaw onboard --install-daemon | 팀 공유 게이트웨이 | 예 | 중간 |
| 수동 LaunchDaemon | 감사된 ProgramArguments만 | 예 | 초기 높음 |
| macOS 앱+CLI | GUI 온보딩과 버전 핀 병행 | 가변 | 중간 |
npm install -g가 5분에 가까워질 수 있음.전제: Node, 포트, 리전
| 검사 | 목표 | 명령 |
|---|---|---|
| Node | 최소 22.14, 허용 시 24.x | node -v && which node |
| npm prefix | 서비스 사용자 쓰기 가능 | npm prefix -g |
| 포트 | 18789 비어 있음 | lsof -nP -iTCP:18789 -sTCP:LISTEN |
| 리전 | HK/JP/KR/SG/US 명시 | pricing |
한 mini에서 실험이 충돌하면 사용자를 나누거나 별도 임대를 쓰세요—포트 경쟁은 Git 머지로 해결되지 않습니다.
9단계 플레이북
- 15분 변경 창을 고정하고 HK/JP/KR/SG/US 관련자에게 알립니다.
- Node 핀을 티켓 본문에 기록합니다.
- 전역 CLI를 정책에 맞게 설치합니다.
- onboard를 실행하고 로그를 첨부합니다.
- launchctl로 Label을 확인합니다.
- gateway status로 RPC를 기록합니다.
- Control UI를 터널/VNC로 엽니다.
- doctor를 비웁니다.
- curl 헬스 글을 연결합니다.
Teams orchestrating multiple agent CLIs should read Multica vs Devin 비교.
See also: OpenClaw AppleScript 연동.
18790 사용, 종료 후 터널 닫기.루프백 Control UI와 SSH
ssh -L 18790:127.0.0.1:18789 user@mini 후 노트북에서 http://127.0.0.1:18790/를 엽니다. 정책이 허용하면 VNC로 mini 브라우저를 사용하세요.
doctor·status·증상 표
| 증상 | 원인 후보 | 첫 조치 |
|---|---|---|
| 시작 직후 RPC 실패 | DNS보다 데몬이 빠름 | ThrottleInterval·순서 조정 |
| 키 부족 경고 | 온보딩 미완 | 승인된 시크릿 주입으로 재실행 |
| UI 멈춤 | 워크스페이스 권한 | 소유자·서비스 계정 정렬 |
| CPU 높음·트래픽 낮음 | 폴링/로그 폭주 | 통합 로그+힙 글 |
stderr가 비어도 미스터리면 5월 13일 stderr 글을 참고하세요.
FAQ
onboard가 CI를 대체하나요? 아니요—데몬 기반입니다.
JP plist를 US에 복사? ProgramArguments는 대개 가능하지만 리전 엔드포인트 환경변수는 수정, 키 통째 복사 금지.
계약 연장? 건강하면 유지하고 관측 보존 기간을 늘리세요.
npm ci 분쟁? 전용 글을 따르세요.
운영 관점의 Mac mini M4
launchd 재시작에서 열이 안정적이고 통합 메모리로 Node 힙과 캐시가 한 주소 공간에 머뭅니다. x86 VM 위 macOS보다 launchd·화면 공유 의미가 그대로라 SSH 터널 절차가 기존 macOS 서버 감사에 태우기 쉽습니다.
리전별 임대로 RTT를 낮추고 CAPEX를 피합니다. pricing으로 코어를 맞추고 help·VNC를 병기하세요.
사용자 가까이에서 OpenClaw 실행
HK/JP/KR/SG/US 노드에서 onboard를 한 번 끝내고 관측·힙 런북을 이식하세요.
