2026 OpenClaw 공식 Docker: `docker-setup.sh`, GHCR, Control UI(18789) Runbook

약 13분 분량 · MACCOME

대상: 공식 Docker 문서를 읽어도 로컬 빌드 타임아웃, GHCR pull 실패, 18789 포트 충돌, Skills를 막는 볼륨 권한 사이를 오가며 clone부터 Control UI까지 한 줄 순서가 없는 엔지니어.결과: docker-setup.sh와 선택적 OPENCLAW_IMAGE로 표준화하고, Docker 운영, Docker 네트워크, 볼륨·권한 글과 역할을 나눈다.구성: 여섯 가지 함정, 표, 6단계 Runbook, 분류표, 3 KPI, 마무리.

문서대로인데도 Docker 경로에서 깨지는 이유

공식 흐름은 Docker Engine·Compose·디스크·출구가 일관된다고 가정합니다. npm 글로벌 설치나 다른 compose checkout과 섞으면 “OpenClaw가 고장”처럼 보입니다. 2025–2026에 자주 나오는 여섯 가지:

  1. 소스 빌드와 GHCR pull을 분리하지 않음: 약한 CI 회선에서 docker build만 고집하고 OPENCLAW_IMAGE로 전환하지 않음.
  2. 18789에 남은 오래된 컨테이너: 이전 compose 시도를 멈추지 않아 새 docker-setup.sh가 Control UI를 바인딩하지 못함.
  3. 볼륨 UID/GID 불일치: 컨테이너 사용자와 호스트 ~/.openclaw 권한—Skills/상태 쓰기는 실패하는데 UI는 “무응답”처럼 보임.
  4. 페어링을 이미지 문제로 오해: WebSocket/token은 페어링/token 글—끝없는 compose pull이 아님.
  5. 사내 프록시가 npm은 허용하지만 ghcr.io는 차단: 미러 또는 호스트명 허용; 진단 유형은 npm 설치 Runbook과 같음.
  6. 여러 checkout이 env/볼륨 공유: 섞인 디렉터리에서 오래된 token이 남을 수 있음.

표 1: 로컬 빌드 vs OPENCLAW_IMAGE (GHCR)

변경 티켓에서 주 경로를 하나 고르고 다른 쪽 롤백을 문서화—말로 섞지 않기.

차원기본 소스 빌드OPENCLAW_IMAGE로 GHCR pull
적합커스텀 Dockerfile 수정, 빌드 캐시 디버깅, ghcr 출구 없음UI까지 가장 빠름, 대역폭 제한, 이미지는 캐시하고 repo는 얇은 CI
전제충분한 CPU/RAM; 레이어 캐시용 GB 여유ghcr.io 또는 내부 미러 도달; 맨 latest만이 아니라 태그 pin
위험빌드 타임아웃, 캐시 비대, CPU 경합인증/레이트, 태그 드리프트, 바이너리와 설정 불일치
롤백사전 빌드 이미지로 전환, 데이터 볼륨 경로는 동일이전 digest로 되돌리거나 소스 빌드로; compose 변경을 로그에 남김
info

참고: 업스트림 저장소는 변합니다. 아래는 repo 루트에 docker-setup.sh가 있는 checkout을 가정—fork가 다르면 커밋과 스크립트 경로를 기록하세요.

6단계 Runbook: clone에서 18789 Control UI까지

  1. Docker 사전 점검: docker version과 Compose v2; 레이어/볼륨용 디스크(운영 리소스 표와 맞춤).
  2. clone 후 repo 루트: docker-setup.sh 실행 가능 여부(필요 시 chmod +x).
  3. (선택) 사전 빌드 이미지: export OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:latest—운영에서는 digest나 안정 태그를 pin, 태그만 쫓지 않기.
  4. 스크립트 실행: ./docker-setup.sh; 로그에 pull/build와 compose up이 보이고 즉시 비영 종료가 아니어야 함.
  5. Control UI 열기: http://127.0.0.1:18789(리비전에서 포트가 바뀌면 그 빌드 따름); 연결 거부가 아니라 페이지 로드 확인.
  6. 최단 검증: UI 또는 CLI 헬스체크; 페어링은 앱 설정을 바꾸기 전에 페어링/token 트리를 따름.
bash
# GHCR 사전 빌드 우선 (태그는 정책에 맞게 교체)
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./docker-setup.sh

# 성공 후 Control UI 로드 (예: 포트 18789)
# open http://127.0.0.1:18789

표 2: 증상 → 확인(분류 순서)

위에서 아래로. 이미지·네트워크·볼륨을 동시에 바꾸지 않기.

증상먼저 확인함께 읽기
빌드 타임아웃 / OOMOPENCLAW_IMAGE로 전환; buildkit 병렬 제한; 캐시 정리Docker 운영(리소스)
pull 시 401/403/TLSghcr.io 프록시 허용; 내부 미러—npm 레지스트리만이 아님Npm 설치 Runbook(프록시)
address already in use :18789docker ps로 오래된 컨테이너; 오래된 compose 중지 또는 문서대로 포트 변경Docker 네트워크
볼륨 쓰기 permission denied호스트 UID/GID와 컨테이너 사용자; named vs bind볼륨/Skills 체크리스트
UI는 열리나 채널 무음모델/채널 층 먼저 제외; 그다음 token/WS 코드페어링/token

변경 티켓·대시보드용 3 KPI

  1. 이미지 정체성: 가능하면 레지스트리+태그+digest를 로그—“latest만 썼다”가 아님; 롤백은 digest로.
  2. Control UI 도달성: HTTP 200/페이지 제목/헬스체크를 “컨테이너 프로세스 존재”와 분리해 불리언화.
  3. 볼륨 계약: 호스트 ~/.openclaw(또는 팀 경로)를 compose 마운트에 매핑; 업그레이드 전후 크기·권한 스냅샷.

업스트림 릴리스 노트와 충돌하면 업스트림을 우선; 본 글은 엔지니어링 체크포인트입니다.

노트북 시험이 운영 Gateway로 잘 안 되는 이유

절전, 조각난 디스크, Docker Desktop 잔재는 전용 CPU, 안정 출구, 감사 가능한 볼륨, token 경계와 맞습니다. digest를 pin하지 않고 볼륨 계약·헬스체크 없는 임시 컨테이너는 실제 트래픽에서 먼저 무너집니다.

안정적인 Apple Silicon에서 Gateway를 장기 호스팅하는 팀은 이 최단 루프 이후 다지역·유연한 임대 기간의 MACCOME 클라우드 Mac이 유리합니다—공개 대여 요금과 고객센터를 Docker 운영·페어링 글과 함께 보세요.

파일럿: 전용 원격 호스트에서 여섯 단계를 모두 실행하고 digest와 볼륨 스냅샷을 기록한 뒤 월/분기 조건과 모니터링을 결정합니다.

FAQ

이 글과 Docker 운영, 무엇을 먼저?

처음으로 UI까지 가는 경로는 본 Runbook; 변경 창·롤백·모니터링은 운영. 요금: Mac mini 대여 요금.

OPENCLAW_IMAGE가 npm 글로벌 CLI와 충돌하나요?

충돌은 포트·환경·데이터 디렉터리에 모임; 호스트당 주 Gateway는 하나. 이전 순서: npm 설치 Runbook.

18789를 공개 인터넷에 노출해도 되나요?

앞에 리버스 프록시와 TLS—0.0.0.0에 맹목적으로 바인딩하지 말고 운영/리버프록시 글의 보안 절을 읽으세요. 도움: 클라우드 Mac 지원·고객센터.