베어 메탈 macOS에 OpenClaw 게이트웨이를 상주시키면 Docker 스택처럼 한 겹으로 감싸진 실행 환경이 없습니다. 대신 launchd가 로그인 세션과 백그라운드 유닛의 경계를 나누고, 비대화형 SSH·CI에서의 환경 변수가 터미널에서 본 값과 달라지며, 로컬 TCP 18789와 게이트웨이 토큰이 업그레이드 직후 어긋나는 사례가 티켓으로 쌓입니다. 이 FAQ는 그 장애를 프로세스·환경·포트·자격 증명·리전 순으로 층을 나눠 점검하고, Compose 기반 배포와 비교할 때 무엇이 달라지는지 짧게 정리합니다.
1층: launchd(및 Linux 쪽 systemd --user)와 로그인 경계
macOS에서는 대부분 LaunchAgent가 사용자 로그인 이후에 뜨고, LaunchDaemon은 시스템 전역입니다. openclaw onboard --install-daemon류의 도구가 만든 plist가 어느 경로에 놓였는지 먼저 확인하세요. 콘솔에 찍히는 주체가 gui/501인지 user/501인지에 따라 Headless SSH만 있는 클라우드 Mac에서는 로그인 윈도가 없어 에이전트가 아예 기동하지 않는 패턴이 나옵니다. 해결 축은 (가) 자동 로그인·세션 유지 정책을 IT와 맞추거나, (나) 시스템/전용 서비스 계정과 맞는 Daemon plist로 옮기거나, (나) tmux/screen 안에서 상시 프로세스를 돌리는 운영 타협입니다.
같은 바이너리를 리눅스 점프박스에도 둔다면 systemd --user 유닛이 비슷한 역할을 합니다. 다만 여기서도 linger 여부와 로그아웃 뒤 세션 소멸을 launchd와 같은 축으로 생각해야 합니다.
2층: 환경 변수와 비대화형 셸
OPENCLAW_GATEWAY_TOKEN, 모델 베이스 URL, 프록시, NODE_OPTIONS 같은 값이 대화형 셸 프로필에만 있으면 Ansible·GitHub Actions self-hosted·cron이 전부 실패합니다. 운영 표준은 (1) plist나 systemd 유닛에 명시, (2) /etc/environment 또는 배포 파이프라인이 쓰는 dotenv를 버전 관리, (3) 배포 직후 launchctl print로 실제 주입 값을 캡처하는 것입니다. Apple Silicon에서 Rosetta가 섞이면 바이너리와 PATH가 미묘하게 갈라지니, 게이트웨이 호스트에는 단일 아키텍처 Node를 고정하는 편이 낫습니다.
3층: TCP 18789와 바인딩
게이트웨이가 127.0.0.1:18789에만 붙어 있으면 같은 머신의 리버스 프록시는 통과해도, 다른 호스트의 브라우저나 챗봇 웹훅은 영원히 닿지 않습니다. lsof -nP -iTCP:18789 -sTCP:LISTEN으로 리슨 주소를 확인하고, 앞단 TLS 종료기가 있다면 헬스 경로까지 포함해 end-to-end로 재현하세요. 방화벽이나 보안 그룹에서 18789를 막아 둔 경우도 흔하니, 내부 표준 포트표에 한 줄 넣어 두면 반복 질문이 줄어듭니다.
4층: 업그레이드 직후 “인증만” 깨지는 현상
npm install -g openclaw@latest 뒤에 클라이언트만 올리고 게이트웨이 쪽 토큰·설정 디렉터리를 그대로 두면, 문서에 적힌 기본 경로와 실제 런타임이 어긋나 401/403만 남는 경우가 있습니다. 롤백 절차에 “이전 npm 버전 + 이전 plist” 쌍을 적어 두고, 업그레이드 체크리스트에 토큰 재발급·클라이언트 재배포를 포함하세요. 인스턴스 스냅샷과 SSH 자격 증명 패턴은
vpszap 클라우드에서 OpenClaw 실행하기: 인스턴스, 스토리지, SSH/VNC 및 관측 가능성에서 먼저 맞춰 두면 장애 복구가 빨라집니다.
Docker Compose 루트와 무엇이 다른가
Compose는 이미지 다이제스트·볼륨·재시작 정책을 한 파일에 묶어 주지만, 베어 메탈은 호스트 OS 업그레이드와 수동 plist가 곧 배포 파이프라인입니다. 스택 전체를 컨테이너로 운영한다면 이미지 핀과 헬스체크를 2026년 OpenClaw Docker Compose 배포와 문제 해결: 이미지 다이제스트 고정, 볼륨 마운트, 게이트웨이 상태 점검 및 업무 워크플로 재현 튜토리얼에서 정리한 방식으로 맞추고, 본 글의 launchd·토큰 층은 “호스트에 직접 깔았을 때”에 적용하면 됩니다.
다지역 M4 클라우드 Mac: 근접 리전과 페일오버 사례
한국·일본·싱가포르·홍콩·미 동·서부 등 사용자 RTT가 가장 짧은 노드에 기본 게이트웨이를 두고, 장애 시에는 DNS나 SSH Host 별칭만 백업 리전으로 바꾸는 식의 페일오버를 문서에 적어 두세요. “이론상 가까운 도시”보다 실제 웹훅·모델 API까지 왕복 시간을 재는 편이 안전합니다. 시트 로테이션·병렬 큐까지 설계에 넣을 때는
2026년 국경을 넘는 팀의 클라우드 Mac 시트 로테이션·병렬 큐 설계 FAQ: 싱가포르·일본·한국·홍콩·미동·미서 여섯 지역 빠른 개통, Mac mini M4 16GB/256GB와 24GB/512GB, 1TB/2TB 확장 및 단기·중기 임대 변동 의사결정과 짝을 이루면 운영·FinOps가 같은 표로 논의하기 쉽습니다.
운영 체크리스트(복사해 런북에 붙이기)
- plist·유닛 파일 경로,
launchctl list에 보이는 레이블, 최근 exit 코드 - 비대화형 세션에서
printenv로 게이트웨이 관련 변수가 모두 보이는지 curl -fsS http://127.0.0.1:18789/…등 문서화된 헬스 경로- npm·게이트웨이·클라이언트 버전 triple과 토큰 발급 시각
- 주 리전 장애 시 DNS/SSH 별칭 전환 순서와 롤백 담당
vpszap 클라우드에서 베어 메탈 운영을 단순하게
위 체크리스트는 가상화 없이 한 대의 CPU·NVMe가 예측 가능할 때 가장 잘 맞습니다. vpszap은 물리 M4 Mac mini를 전용으로 제공하고, 약 5분 안에 SSH와 VNC를 함께 열어 주며, 일·주·월·분기 단위로 청구하고 장기 약정 없이 선택할 수 있습니다. 싱가포르·도쿄·서울 등 사용자에 가까운 리전을 고르면 Apple Silicon 성능을 별도 랙 인프라 없이도 게이트웨이에 바로 얹을 수 있습니다.
동일한 패턴을 가장 빨리 검증하고 싶다면 vpszap 클라우드 Mac mini에서 시작하는 것이 가장 직관적입니다.
