2026 Mac VPS에서 Docker로 OpenClaw: Gateway Token, CLI 컨테이너 네트워크와 페어링 교착 Runbook
노트북에서 쓰던 Compose를 무인 Mac VPS로 옮기면 token mismatch, 1008 pairing required, CLI가 127.0.0.1:18789에서 실패하는 로그가 흔합니다.openclaw-gateway와 openclaw-cli를 분리 컨테이너로 두는 팀을 위해 다섯 가지 근본 원인, 증상 표, 감사 가능한 다섯 단계 Runbook, 그리고 Compose 7×24·게이트웨이 ladder 글 링크를 정리했습니다.
목차
1. 대표 장애: 이중 토큰, 루프백, 페어링, bind, uid
공식 Docker 흐름은 사람이 스크립트와 같은 네트 이름 공간에서 온보딩을 누른다는 전제입니다. 무인 Mac VPS에서는 아래 다섯 묶음으로 수렴합니다.
- 환경 변수 조용한 덮어쓰기: 컨테이너 안
OPENCLAW_GATEWAY_TOKEN이gateway.auth.token을 덮어 UI와 실제 검증이 어긋납니다. - CLI 루프백: 기본
ws://127.0.0.1:18789는 게이트웨이가 아니라 CLI 컨테이너 자신입니다.ECONNREFUSED·1006이 잦습니다. - 페어링 교착:
gateway.bind=lan에서 대시보드와 CLI가 서로 승인을 기다리며 순서 문서가 없으면1008에서 맴돕니다. - bind와 브리지:
loopback은 컨테이너 간 목표와 충돌합니다.lan으로 바꿔도 CLI URL을 안 바꾸면 listen 로그만 남고 WS는 끝나지 않습니다. - uid 드리프트: 이미지는 보통 uid 1000. 호스트가 root로 경로를 만들면 영속화가 깨져 토큰 혼선이 커집니다.
무인 VPS에서는 로그가 곧 진실입니다.docker compose logs -f openclaw-gateway와 CLI 로그를 한 타임라인으로 읽고, digest 고정 시 변경 티켓에 digest와 토큰 앞 8자를 같이 적습니다. 대시보드를 외부에 내놓을 때는 게이트웨이 노출 하드닝 글을 함께 읽으세요.
2. 트리아지 표: 증상·원인·첫 명령
인시던트 템플릿에 붙여 넣을 표입니다. 정책 단계로 넘어갈 때 노출면 하드닝 글을 병행합니다.
| Symptom | Likely cause | First action |
|---|---|---|
| token mismatch | env vs json 불일치 | 저장소·마운트 grep, setup 전 hex 고정 |
| 127.0.0.1:18789 refused | CLI 네트워크 분리 | network_mode: service:openclaw-gateway 또는 GATEWAY_URL을 서비스명으로 |
| 1008 loop | 상호 승인 대기 | dashboard --no-open 후 devices approve, 로그 발췌 첨부 |
| 헬스 불안정 | 프로세스만 프로브 | 실제 리스너에서 /healthz·/readyz |
| 쓰기 되돌아감 | 마운트·권한 | VPS 디스크 bind 확인, 데이터 dir chown -R 1000:1000 |
OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32)를 export하고 동일 문자열을 .env와 gateway·CLI 서비스에 쓰며 온보딩에서도 그 값만 붙입니다. 인시던트 중 두 번째 토큰을 스크립트에 맡기지 마세요.
「양쪽 grep」은 저장소 검색에 더해 docker compose exec로 각 컨테이너의 openclaw.json과 compose env를 맞춰 봅니다. 시크릿 매니저는 런타임에 풀린 값을 확인합니다.1008에서 대시보드와 CLI의 pending 표시가 비대칭이면 GATEWAY_URL이나 쿠키 분리를 의심합니다.
3. 다섯 단계 Runbook
- 비밀 동결: 티켓에 토큰 앞 8자와 digest 기록.
- 이중 소스:
compose up전 각 정의에서gateway.auth.token과OPENCLAW_GATEWAY_TOKEN대조. - 이름 공간: CLI는
network_mode: service:openclaw-gateway우선. 브리지면GATEWAY_URL=ws://openclaw-gateway:18789와 DNS 검증. - 페어링: 게이트웨이에서
dashboard --no-open, CLI에서devices approve, 순서를 티켓에 남김. - 프로브: 호스트에서
/healthz·/readyzcurl, plistSuccessfulExit에도 반영. 한도는 Compose 7×24 글 참고.
최소 Compose 스케치(프로덕션은 상류 템플릿과 병합):
network_mode를 못 쓰면 내부 URL을 명시하고 버려 컨테이너로 healthz를 wget/curl해 DNS 철자를 확인합니다. 디바이스 행 삭제는 로그를 남긴 뒤에만 합니다.
4. 인용용 사실: 포트, uid, 프로브
- 포트: 기본
18789. 헬스 스크립트는docker ps만이 아니라 실제 리스너를 때려야 합니다. - UID: node 사용자는 보통
1000. 호스트 bind를 맞추지 않으면 조용히 영속화가 깨집니다. - 프로브:
/healthz는 liveness,/readyz는 WS 준비에 가깝습니다. 순서·타임아웃을 Runbook에 적습니다. - 시간 동기: 큰 시차는 인증서·로그 상관을 흐립니다. NTP를 유지하세요.
- 업그레이드 창: 이미지 교체 시 다섯 단계 체크를 먼저.
docker ps통과가 인증된 CLI 세션과 같지 않습니다.
5. 읽기 순서: Compose 7×24와 게이트웨이 글
먼저 Compose 7×24, 이어서 게이트웨이 install/bind/auth Runbook을 읽습니다. 노트북의 ad-hoc docker run은 무인 VPS에서 토큰·페어링 결함을 가립니다. 장기 에이전트에 전용 Apple Silicon·고정 출구·예측 가능한 동시성이 필요하면 VPSMAC M4 Mac 클라우드가 운영 스토리를 한 권으로 묶기 쉽습니다. 자동화는 90초 API 가이드를 보세요.