2026 OpenClaw Docker Compose 연결·페어링: 1006과 1008, 단일 토큰, Unix 소켓·공유 네임스페이스

약 20분 소요 · MACCOME

대상: Docker Compose에서 Gateway와 openclaw CLI를별도 서비스로 둘 때, 로그상 Gateway가 정상인데 CLI만 gateway closed(WebSocket 1006/1008), pairing required, 또는 env와 설정 파일 간 토큰 이중 원천으로 어긋나는 팀입니다. 핵심: 게이트웨이 URL 의미(Compose 서비스명 기반 TCP 또는 공유 Unix 소켓)을 확정하고, OPENCLAW_GATEWAY_TOKEN과 gateway.auth.*를 단일 진실 원천으로 맞춘 다음, 필요할 때만 공유 네트워크 네임스페이스로 호출 면만 좁힙니다. 4월 글과의 역할 분담: 서브 에이전트 1008 + trustedProxies 글은 넓은 CIDR·허용 경로에 초점입니다. 여기서는 각 컨테이너가 Gateway를 어떻게 주소하고 같은 토큰을 읽는지입니다. 교차 참고: Docker 네트워크 진단, 페어링·토큰, 볼륨 권한.

Compose 분할 시 자주 등장하는「네트워크처럼 보이는」근본 원인 다섯

  1. 127.0.0.1 하드코딩: 루프백은 해당 컨테이너 자신만 가리킵니다. Compose DNS로 http://openclaw-gateway:18789처럼 서비스명을 붙입니다(이름 조정).
  2. 토큰 두 갈래: OPENCLAW_GATEWAY_TOKEN은 파일 설정을 덮을 수 있으며, 불일치 마운트는 401/1008 교차처럼 보입니다.
  3. Unix 소켓 공동 미마운트: Gateway가 gateway.sock을 만들면 두 쪽 모두 동일 호스트 경로·정렬 UID/GID가 필요합니다(볼륨 글 참고).
  4. 1006를 단순 불안정으로: 1006은 대개 비정상 종료(재시작·타임아웃·리버스 프록시 재시도)입니다. 페어링을 건드리기 전 Gateway 재시작을 먼저 보세요.
  5. loopback 동등이 필요한데 기본 브리지만: 문서상 localhost 의미면 network_mode: service:<gateway> 또는 끝까지 DNS 기반 TCP—한 변경 번호 안에 두 방식 혼합 금지.

이 다섯 항목이 초록이거나 명시적으로 면제될 때까지 릴리스 차단으로 두세요—이름 공간과 토큰 계약이 풀리기 전에는 이미지 태그를 갈아타도 드물게 고칩니다.

소켓이 끊기면 Gateway stderr·CLI stdout·docker events를 같은 타임 윈도우 밀리초로 맞추세요—“무작위” 다운타임 상당수는 재시작·과한 헬스 프로브입니다.

증상다음 확인(위→아래)보통 어디까지
1006·새 Gateway PID·OOM동일 순간 호스트/dmesg·재시작 한도·타임아웃전송 종료≠ 페어링 정책만의 문제
1008 + pairing required토큰 단일 원본 → 게이트웨이 URL → 디스크 페어링 상태이중 마운트 또는 읽기 불가 상태 디렉터리
Connection refused가 CLI 컨테이너에만프로브를 해당 컨테이너로 이동(호스트 curl은 참고만)루프백 착각·포트 미게시
Unix 소켓 ENOENT·거부ls -la 마운트; 부모 디렉터리 bind 일치 확인자식 경로 네임스페이스에 소켓 없음
warning

종료 코드만으로는 불충분: 1006과 1008은 라벨일 뿐—Gateway 로그·페어링 상태기·역프록시 재시도 예산과 동시에 해석해야 합니다. 안 그러면 bind만 넓히거나 무분별 재 onboarding으로 노출 면만 커집니다.

여섯 단계: 페어링을 축하하기 전에 도달 증명

  1. 토큰 유일 출구 선언: 설정 파일 또는 env 중 하나만 운용 단일 원천; docker compose config 결과와 CI grep으로 검증.
  2. URL 의미 동결: 전 구간 Compose DNS TCP 또는 전 구간 하나의 마운트된 Unix 소켓—환경마다 프로토콜 섞기 금지.
  3. .openclaw 상태 동일 마운트: 같은 쓰기 가능 트리; RO만 남아 있으면 “0단계에서 멈춤처럼” 보입니다—볼륨 체크리스트.
  4. Gateway 상태·doctor: openclaw gateway status 후 openclaw doctor; 호스트 데몬 로그와 컨테이너 로그 타임스탬프 정렬.
  5. localhost 동등이 진짜 필요할 때: network_mode: service:<gateway> 등을 리뷰 시트에 명시; trustedProxies와 방화벽 행 모순 없게.
  6. 종료 증거 묶음: 실패 이름 공간 성공 로그 + 게이트웨이 URL·토큰 짧은 해시 지문—“노트북 curl만 통함” 언급만으로 티켓 종료 불가.

바깥쪽 Nginx/Caddy가 있다면 Compose URL과 역방향 프록시의 Upgrade·유휴 타임아웃을 맞추지 않으면 간헐 1006이 인증 버그와 구분 불가합니다.

yaml
# 이름·볼륨은 교체 후 docker compose config
services:
  openclaw-gateway:
    environment:
      - OPENCLAW_CONFIG_DIR=/data/.openclaw
      - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
    volumes:
      - oc-data:/data/.openclaw
    networks: [oc-net]

  openclaw-cli:
    environment:
      - OPENCLAW_CONFIG_DIR=/data/.openclaw
      - OPENCLAW_GATEWAY_URL=http://openclaw-gateway:18789
      - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
    volumes:
      - oc-data:/data/.openclaw
    networks: [oc-net]
    depends_on:
      - openclaw-gateway

networks:
  oc-net:
    driver: bridge

volumes:
  oc-data:

변경 요청에 남길 엔지니어링 사실(벤더 SLA 아님)

  • 프로브는 실패한 네임스페이스에서만—그렇지 않으면 “노트북에선 녹색, CI에선 적색” 슈뢰딩거 Gateway가 됩니다.
  • 토큰 두 면(파일+env) 짧은 지문을 출하 전에 해시—눈으로 비교하지 말 것.
  • 페어링은 재시작 폭풍과 상관: 과한 liveness가 1006만 키웁니다—먼저 readiness.
  • 교차 컨테이너 디버깅 제0조: 깨진 이미지 안에서 돌리지 않은 명령은 잡담이지 RCA가 아닙니다.

일회용 노트북 컨테이너가 OpenClaw 프로덕션 체인에 잘 못 타는 이유

데모 단일 호스트로는 빠르지만, 비밀 로테와 자동화에는 예측 가능한 재시작·디스크 기준선·감사 친화형 페이링 이력이 필요합니다. 여섯 리전에 덮여 있는 전용 원격 Mac에 Gateway를 두면 월/분기 임대 회계와 CI 비밀 cadence가 잘 맞습니다. 공개 Mac mini 대여 요금을 먼저 보고 본 Runbook의 env를 대응하세요.

정리: 히어로보다 계약 우선

OpenClaw Compose 장애 대부분은 네임스페이스 + 토큰 + 상태 디렉터리가 세 개의 문서로 갈린 채입니다. 컨테이너 안에서 재현 가능한 핸드셰이크 증명이 나올 때까지 “이미지 교체”나 “TLS 끄기”는 보류입니다. 계약이 잡힌 뒤 GHCR과 Control UI, 단단한 역방향 프록시로 이어지게 하세요.

FAQ

trustedProxies 4월 글과 중복인가요?

그 Playbook은 큰 CIDR과 서브 트래픽입니다. 여기선 URL·소켓·네임스페이스·단일 원천 토큰—둘 다 읽으세요.

호스트 curl이 성공하면 CI도 됩니까?

아니요. 실패한 동일 컨테이너 이미지에서 프로브를 다시 실행해야 합니다.