이런 분께： Docker Compose로 Gateway와 CLI·에이전트 관련 컨테이너를 동시에 돌리는데, 로그상 Gateway는 떠 있는 것처럼 보이나 하위 세션·도구 호출에서 gateway closed (1008): pairing required가 나오거나 RPC는 healthy인데 페어링에서 막히는 경우입니다. 결론：「이미지를 다시 깔면 된다」류의 고립 문제가 아니라, 대개 바인드 면·토큰·신뢰 프록시 대역(trustedProxies)·컨테이너 간 URL의 조합입니다. 본문은 증상 매트릭스·Compose 조각·6단계 Runbook·KPI 세 가지를 제공합니다. 역할 분담：《공식 docker-setup.sh + GHCR》《페어링과 토큰》《Docker 네트워크 분기》와 병렬로 읽습니다.
OpenClaw Gateway는 장시간 연결과 라우팅을 담당합니다. CLI나「하위 세션·서브에이전트」류 도구가 WebSocket/HTTP로 Gateway에 말할 때, 프로세스가 살아 있는 것만으로는 부족하고, Gateway 관점에서 호출자의 네트워크 신원이 신뢰 가능해야 하며 페어링 상태도 유효해야 합니다. Docker는 서비스마다 네트워크 네임스페이스를 분리합니다. CLI 컨테이너 안에 http://127.0.0.1:18789를 쓰면 요청은해당 컨테이너 자신으로만 향하고, 호스트나 다른 서비스에는 닿지 않습니다.
http://openclaw-gateway:18789처럼 Compose DNS 이름을 써야 합니다.172.16.0.0/12, 10.0.0.0/8, 사용자 정의 네트워크 CIDR)을 신뢰 집합에 넣어 클라이언트 신원을 올바르게 평가해야 합니다.《3플랫폼 설치 총람》과 달리 Compose에서 중요한 것은「어떤 OS냐」가 아니라어느 네트워크가 어느 컨테이너에서 신뢰되느냐입니다.
재현할 때는로그 지문 세 줄을 나란히 보관하세요. Gateway 기동 줄, 서브에이전트 스택, docker inspect의 attachable 네트워크 Subnet입니다. 많은 1008은 이 셋을 비교하면「신뢰 대역이 선언되지 않음」으로 수렴하며, 모델이나 채널 자체 문제가 아닙니다.
| 증상 스냅샷 | 우선 확인(오름차순) | 흔한 근본 원인 |
|---|---|---|
| 컨테이너 A가 127.0.0.1:18789에 닿지 않음 | 먼저 서비스 이름 URL로 바꾸고 publish 포트·리스닝 주소 확인 | localhost 의미 오류 |
| RPC healthy인데 sessions_spawn이 1008 | 페어링 목록 → trustedProxies → bind 삼원소 | 서브에이전트 경로가 외부·미페어로 처리됨 |
| 로그에 trusted proxy / pairing 문구 | compose 네트워크 CIDR과 gateway.auth 설정 정렬 | 대역이 신뢰 집합에 없음 |
| 버전 업그레이드 직후에만 | 구·신 기본 bind/auth와 마이그레이션한 .openclaw 볼륨 비교 | 기본값 강화 또는 페어링 무효 |
안내： 공식 docker-setup.sh 경로를 쓰더라도 서비스 이름과 볼륨을 본문의 네트워크 계약 관점에서 다시 확인하세요. 자세한 내용은 《GHCR·Control UI Runbook》을 참고합니다.
| gateway.bind(개념) | 적합 | Compose에서의 마찰 |
|---|---|---|
| loopback | 단일 all-in-one 컨테이너 또는 호스트만 접근 | 다른 서비스 컨테이너는 로컬 루프백으로 직접 쓸 수 없음 |
| lan / 사용자 지정 Listen | 멀티 서비스, 컨테이너 간 RPC 필요 | 토큰·인증과 노출 축소가 함께 필요 |
| trusted reverse proxy | 앞에 Nginx/Caddy | 《리버스 프록시 체크리스트》와 하류 출처를 맞춤 |
trustedProxies 작성 관점(예시 CIDR 포함)아래 표는교육용 예시입니다. 실제 subnet은 docker network inspect로 확인하고 무작정 복사하지 마세요.
| 네트워크 유형 | 흔한 CIDR 예 | 해야 할 일 |
|---|---|---|
| Docker 기본 bridge | 172.17.0.0/16(환경 의존) | Gateway가 보는 소스 IP가 해당 대역에 들어가는지 대조 |
| Compose 사용자 정의 네트워크 | 예 172.18.0.0/16～172.30.x.x | 서브넷 전체를 trustedProxies에(단일 컨테이너 IP가 아님) |
| overlay / swarm | 오케스트레이터가 할당 | 역시「서브넷」을 대상으로, pod IP 목록은 피해 변동을 줄임 |
OPENCLAW_GATEWAY_URL=http://openclaw-gateway:18789(이름은 compose 서비스명에 맞춤).OPENCLAW_GATEWAY_TOKEN을 양쪽에서 일치. 파일 토큰이면 마운트가 UID에서 읽히는지 확인합니다.openclaw gateway status → openclaw doctor → 서브에이전트 동작 재현 후 로그에서 1008 / pairing 검색.# 예시 조각(서비스 이름·환경은 플레이스홀더 — 운영 전 교체)
services:
openclaw-gateway:
environment:
- OPENCLAW_CONFIG_DIR=/config
- OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
volumes:
- ./config:/config
networks: [oc-net]
openclaw-cli:
environment:
- OPENCLAW_CONFIG_DIR=/config
- OPENCLAW_GATEWAY_URL=http://openclaw-gateway:18789
- OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
volumes:
- ./config:/config
networks: [oc-net]
networks:
oc-net: { driver: bridge }
gateway.auth.token 지문 또는 env 해시 비교, 불일치 시 배포 차단.위 KPI는 엔지니어링 관측 제안이며 상위 프로젝트 SLA를 의미하지 않습니다.
「이미지를 띄울 수 있다」만으로는 부족합니다. 서브에이전트와 세션 도구는안정적인 Gateway·예측 가능한 네트워크 신원·일관된 설정 볼륨을 요구합니다. 노트북에서 단일 컨테이너 docker run을 반복하는 것과, 전용 원격 Mac에서 고정 Compose·영구 볼륨으로 장기 작업을 돌리는 것은 장애 면이 전혀 다릅니다. 후자는 무인·예약 잡 시나리오에 가깝습니다.
순함수형 VPS나 공유 데스크톱은 데모에는 쓸 수 있어도일관된 디스크·네트워크 기준선이 자주 부족합니다. Gateway·리버스 프록시·자동화를 같은 신뢰 구역에 두고 빠르게 확장하려면, 월·분기 단위로 묶인 다지역 Apple Silicon 클라우드가 수동 임시 Docker 호스트를 쌓는 것보다 나을 때가 많습니다. MACCOME은 물리 격리와 여섯 지역 선택으로「상시 Gateway」와「빌드/서명기」를 층으로 나누기 쉽습니다. 우선 공개 요금과 고객센터를 확인한 뒤 본 Runbook으로 환경 변수를 묶으세요.
도입 순서는 단일 Compose 프로젝트에서 6단계 루프를 먼저 완주하고, 그다음 Gateway와 다른 워크로드를 별 원격 노드로 나눌지 결정하는 것이 좋습니다.
자주 묻는 질문
코드 1008이 나오면 바로 bind를 LAN으로 바꿔야 하나요?
먼저 표 1로 분기합니다. 많은 경우 서비스 이름 URL 또는 trustedProxies 문제이며, 리스닝 면을 무분별하게 넓히는 일이 아닙니다. 노출을 넓히면 토큰과 방화벽을 함께 맞추세요. 페어링은 페어링·토큰 대조표를 참고합니다.
호스트에서 127.0.0.1:18789로 curl 하면 컨테이너 내부 탐색을 대신할 수 있나요?
호스트 관점의 헬스에는 쓸 수 있지만, 컨테이너에서 Gateway 서비스 이름으로의 연결 검증을 대체하지는 못합니다. 네트워크 네임스페이스가 다릅니다. 도움: 클라우드 Mac 지원·고객센터.
《Docker 네트워크 분기》와 중복되나요?
네트워크 분기는 compose 네임스페이스와 CLI 연결을 다룹니다. 《Docker 공식 원클릭》은 이미지 경로에 치우칩니다. 본 글은서브에이전트 페어링과 trustedProxies를 잇습니다. 이어서 MCP·Skills 검증을 읽을 수 있습니다.