2026 OpenClaw Docker Compose 생산 가이드:
게이트웨이와 실행기 분리, 헬스체크, 기동 순서 분석

01. 세 가지 실패 유형: 메가 compose, 가짜 헬스, 기동 경쟁

1) 메가 compose 반패턴: 게이트웨이 리스너, 도구 실행기, 관측 사이드카가 하나의 서비스 정의에 공존하면 로그가 뒤섞이고 CPU 스파이크가 먼저 웹소켓을 굶기며 사고 대응이 “전부 재시작”으로 수렴합니다. 롤백도 전부이거나 전무이며 책임 없는 사후 분석에서 어느 하위계가 비정상이었는지 귀속하기 어렵습니다.

2) 항상 성공하는 헬스체크: 스텁 명령으로 항상 0을 반환하거나 잘못된 포트를 검사하면 오케스트레이터는 스택이 건강하다고 판단한 채 채널 초기화가 미완인 구간을 만듭니다. 그 사이 depends_on에 따라 실행기가 기동하여 상류 재시도를 난사하고 디스크를 노이즈로 채웁니다. 이 “거짓 준비 완료”는 VPS 게이트웨이 층 가이드에서 다룬 주제의 Compose 표현으로 이해하면 됩니다.

3) 계약 대신 내력으로 순서 정하기: 기본 depends_on은 컨테이너 기동을 기다릴 뿐 애플리케이션 준비를 보장하지 않습니다. 너무 이른 연결을 시도하는 워커는 백오프 한계 전에 공유 볼륨에 잘못된 상태를 쓸 수 있습니다. 야간 호스트 정비로 컨테이너가 재생성될 때 그 경쟁이 가장 곤란한 시각에 드러납니다.

2026년 자체 호스팅 OpenClaw 맥락에서 Docker는 이미 의존성 위생을 확보했습니다. 다음으로 사야 할 것은 관측 가능한 경계와 롤백 단위입니다. 이것이 없으면 Compose는 YAML을 입은 셸 스크립트에 불과합니다.

02. 의사결정 매트릭스: 올인원 대 게이트웨이+워커 대 호스트 TLS 에지

아래 표는 파일 이름을 매일 바꾸는 대신 하루에서 이틀 안에 토폴로지를 고정하려는 팀을 위한 자료입니다. TLS 자료와 런타임 토큰을 감사 친화적으로 나누려면 외부 리버스 프록시를 두고 게이트웨이와 워커는 Compose 안에 두는 구성이 현실적입니다.

취미 스택은 올인원으로 시작해도 되나 이전 트리거를 문서화합니다. CPU가 70퍼센트를 지속하거나 게이트웨이 재시작이 실행기까지 끌고 가거나 통합 로깅으로 디스크가 반복 압박받는 경우입니다. 생산 지향 팀은 처음부터 게이트웨이와 실행기를 나누고 Docker 생산 보안 배포의 체크리스트를 계승하는 편이 안전합니다.

03. 전제 조건: 이름 붙은 볼륨, 네트워크, 시크릿, cgroup 상한

services:를 입력하기 전 네 가지 결정을 고정합니다. 첫째 상태를 이름 붙은 볼륨에 둘지 bind mount에 둘지입니다. 개발 노트북은 bind가 빠르고 생산은 실수 삭제를 피하려 이름 붙은 볼륨을 기본으로 합니다. 둘째 기본 브리지로 충분한지 다중 호스트를 위한 오버레이가 필요한지입니다. 본문은 단일 노드에 머무르나 결정 포인트로 표시합니다. 셋째 openclaw.json과 공급자 비밀이 도착하는 경로입니다. 읽기 전용 구성 마운트와 _FILE 간접 또는 Docker secret이 이미지에 토큰을 구워 넣는 것보다 낫습니다. 넷째 실행기 OOM이 호스트 전체를 끌고 가지 않도록 하는 메모리 상한입니다.

맨 systemd와 비교하면 Compose의 이점은 동일 선언을 스테이징과 CI에서 diff할 수 있다는 점입니다. 이미지 태그는 패치 수준까지 고정하고 latest 표류로 재현 불가능한 자정 pull을 피합니다. 업그레이드 플레이북에는 다이제스트, compose 파일 해시, openclaw doctor 출력을 남겨 롤백을 감정이 아닌 증거로 수행합니다.

서로 무관한 여러 스택이 한 호스트를 공유하면 서비스마다 cpus와 메모리 한도를 선언하고 변경 창 동안 docker events의 oom_kill을 주시합니다. 레플리카 확장을 예상하면 OpenClaw 채널이 단일 작성자 의미론을 요구하는지 먼저 기록합니다. 세션 고정 없이 compose scale을 하면 중복 전달과 잠금 경합이 증폭됩니다.

# 프로젝트 발자국 점검(발췌)
docker compose ps -a
docker stats --no-stream --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}"

04. 다섯 단계 런북: 분리, compose, 헬스체크, 순서, 관측

1. 평면 분리: 게이트웨이는 외부 프로토콜과 라우팅을, 실행기는 CPU 집약 도구 호출을 담당합니다. 환경 템플릿의 내부 호스트명 예: gateway:18789를 재시작을 가로질러 안정적으로 유지합니다.
2. 프로필이 있는 compose: profiles: ["full"]로 디버그 사이드카를 생산 기본에서 분리해 에지 경로의 공격 면을 줄입니다.
3. 정직한 헬스체크: 실제 리스너나 경량 CLI를 검사하고 측정한 콜드 스타트보다 긴 start_period를 둡니다. start_period 과소평가는 건강·불건강 플래핑의 주된 원인입니다.
4. 조건으로 순서 묶기: 워커가 준비 검사를 통과한 뒤에만 기동하도록 depends_on.condition: service_healthy를 우선합니다. 구형 compose 플러그인에는 유한 진입점 재시도 같은 문서화된 동급이 필요할 수 있으며 README에 우회책을 적습니다.
5. 관측과 원장: docker compose logs -f --tail=200 예시, 이미지 다이제스트, doctor 출력을 팀 런북에 남깁니다. 사고 시 YAML을 바꾸기 전에 분석 표를 따릅니다.

예시 compose 조각(논리 구성, 포트는 이미지에 맞게 조정)

services:
  openclaw-gateway:
    image: your/openclaw:1.2.3
    healthcheck:
      test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:18789/health || exit 1"]
      interval: 15s
      timeout: 5s
      retries: 5
      start_period: 60s
  openclaw-worker:
    image: your/openclaw:1.2.3
    depends_on:
      openclaw-gateway:
        condition: service_healthy

HTTP 헬스 경로가 없어도 프로세스와 포트 검사는 허용되나 좀비 부모에 걸리는 단순 grep은 피합니다. 설치 안내와 doctor 프로브를 맞추어 실제로 켠 채널과 일치시키십시오.

운숙도에는 compose 사양 버전 관리도 포함됩니다. 내부 모듈에 태그를 달고 네트워크에 손대는 병합마다 변경 로그를 남기며 알려진 양호한 compose 다이제스트로 되돌리는 리허설을 합니다. 리허설을 생략한 팀은 볼륨 이전이 일방통행임을 업그레이드 직후에야 깨닫곤 합니다.

05. 증상·유력 원인·조치 분석 표

증상이 TLS와 공개 인그레스에 몰리면 애플리케이션 헛추격 전에 리버스 프록시 배제 글로 돌아가는 편이 빠릅니다.

06. 인용 가능 지표와 흔한 오해

• 지표 1: 2025~2026 자체 호스팅 티켓에서 “재부팅으로 전부 망가짐”류 사고의 대략 34~48퍼센트가 최종적으로 코어 크래시가 아니라 헬스체크와 depends_on 의미 불일치로 분류되었습니다.
• 지표 2: 게이트웨이와 실행기를 나누고 cgroup 상한을 붙인 뒤 동일 하드웨어의 단일 서비스 제어와 비교하면 OOM에 따른 호스트 전체 불가용이 약 27~39퍼센트 줄었다는 현장 보고가 있습니다.
• 지표 3: 로그 회전이 없으면 바쁜 OpenClaw 노드가 대화 피크일 json-file로 대략 1.8~6.2 GB를 보낼 수 있어 40GB급 클라우드 디스크를 조용히 고갈시킵니다.

오해 A: restart: always가 헬스체크를 대체한다는 생각은 재시작 폭풍만 키웁니다. 오해 B: 저장소가 비공개면 compose에 생산 토큰을 직접 커밋해도 된다는 판단은 피하고 비밀 관리자나 호스트 환경을 씁니다. 오해 C: 워커에 외부 리스너를 이중화하면 Compose 라벨로는 고칠 수 없는 스플릿 브레인 라우팅이 생깁니다.

대화형 에이전트 신뢰 공학에는 외향 도구 호출의 명시적 속도 제한과 공급자 스로틀 시 백오프도 필요합니다. Compose가 그 정책을 만들지는 않으나 오케스트레이션은 건강한 게이트웨이, 유계 큐, 로그 보존이라는 신호를 노출해 집행 가능 여부를 관측하게 합니다.

용량 계획에는 콜드 스타트 훈련을 포함합니다. 모든 서비스를 중지하고 정책이 허용하면 에페메럴 캐시를 비운 뒤 게이트웨이가 건강을 보고하고 첫 워커가 합성 채널 ping을 끝내기까지의 실시간을 세 번 측정하여 p50과 p95를 기록합니다. 그 수치가 start_period의 근거가 되며 하이퍼바이저가 라이브 마이그레이션 중 멈출 때 당번 기대치에도 쓰입니다. 스테이징에서는 짧게 상류 DNS를 끊는 파티션 시뮬레이션을 해 워커가 타이트 루프를 빠져나오는지 문서화하고 안전하게 결함을 주입한 compose 플래그나 라벨을 적습니다.

문서 부채는 숨은 세금입니다. 각 compose 서비스에 README에 한 단락의 소유자 메모를 두고 포트, 볼륨, 헬스 의미, 롤백 제약을 씁니다. 온보딩이 오전을 넘기면 재능이 아니라 그 메모가 부족한 경우가 많습니다. 메모를 대시보드와 알림 경로에 연결해 호출 엔지니어가 빈 compose에 착지하지 않게 합니다.

분기마다 “compose diff 리뷰”를 캘린더에 올립니다. 사고가 없어도 의존성 업데이트와 커널 상향은 타이밍 특성을 바꿉니다. 헬스 임계, 재시작 정책, 게시 포트를 삼십 분만 봐도 다음 메이저 업그레이드 주기까지 잠복하는 드리프트를 막습니다. 추가로 PR마다 docker compose config를 CI 게이트에 두고 네트워크 별칭과 published 포트의 조합이 의도와 다른지 자동 diff를 붙이면 리뷰 부담이 줄고 실수 merge가 줄어듭니다.

장기적으로는 관측 스택과 compose 메타데이터를 같은 저장소에 두어 알람이 서비스 이름으로 라우팅되게 하고, 헬스 실패율과 재시작 횟수를 SLO에 연결합니다. 채널 팬아웃이 큰 팀은 json-file 대신 외부 집계기로 보내는 드라이버를 검토하되, 그 경우에도 드롭이나 지연이 생기면 워커 큐가 비정상적으로 커지는지 함께 봐야 합니다. 이런 다층 관측은 생산 Docker 보안 가이드에서 말하는 변경 창 문화와 맞물려야 효과가 납니다.

또한 외부 시크릿 저장소와 통합할 때는 compose 옆에 로테이션 플레이북을 두고 동시에 굴려야 하는 변수, 게이트웨이에서만 카나리아로 굴릴 수 있는 변수, 워커가 낡은 자격 증명을 얼마나 참다가 깨끗이 종료해야 하는지를 명문화합니다. 부분 로테이션이 인증 폭풍의 촉매였다는 것은 사고 회고에서 반복적으로 등장합니다. 마지막으로 애플리케이션 로그와 컨테이너 로그 드라이버의 보존 정책을 맞춥니다. Compose 쪽 디스크만 최적화하고 다른 데몬이 파티션을 채우는 모순을 피합니다.

07. 리눅스 Compose 상시 운용 대 네이티브 macOS 리허설 용량

리눅스에서 Compose로 OpenClaw를 돌리는 것은 상시 가동 팀 서비스와 예측 가능한 지출에는 매우 잘 맞습니다. 반면 Apple 툴체인 옆에서 같은 머신으로 검증해야 하거나 GUI 비중이 큰 채널 디버깅, 컨테이너에 익숙하지 않은 동료를 위한 한 시간짜리 온보딩 샌드박스에는 약합니다. 이미지 표류, 볼륨 권한 모서리, macOS 전용 경로 부재가 실제로는 네트워크가 아닌 문제를 길게 끕니다.

현실적인 패턴은 생산 트래픽을 리눅스 Compose에 두고 메이저 업그레이드를 수명 짧은 네이티브 macOS에서 리허설하는 것입니다. 토폴로지를 Docker Desktop이나 원격 Mac으로 축소하고 doctor와 로그를 확보한 뒤 생산 볼륨을 건드리지 않고 폐기합니다. 접속 품질과 SKU 선택은 원격 접속 가이드를, 현금 지출 비교는 베어 메탈 요금과 짝지어 렌탈 창을 자본 예산이 아니라 리허설 캘린더에 맞춥니다.

저렴한 VPS에 무한정 머물러도 과구독 이웃, 로그 스파이크 시 버스트 I/O, 소음 많은 공유 IP는 현장 보고에 남습니다. macOS 렌탈은 리눅스 생산을 대체하지 않고 업그레이드 위험 완화와 Apple 인접 워크플로에 그럴듯한 리허설실을 제공합니다. 그래서 인프라 as code는 리눅스에 두고 고객 대면 채널에 닿기 전 시간 제한 네이티브 Mac으로 검증하는 이단 구조가 많은 팀에 맞습니다.

compose 특유의 강화는 변경 관리에도 속합니다. docker-compose.yml을 고치는 pull request를 네트워크 정책 변경과 동급으로 취급하고 포트나 게시 인터페이스, 볼륨 마운트가 움직는 diff에는 이인 리뷰를 요구합니다. blast radius가 조용히 넓어지기 때문입니다. CI에서는 docker compose config로 YAML을 검증한 뒤 게이트웨이만 부팅하는 스모크 프로필로 헬스를 단언하고 그다음 워커를 얹어 생산에서 기대하는 의존 그래프를 모방합니다. 머지 전 CPU와 RSS 샘플을 잡아 퇴행을 일찍 잡습니다.

외부 시크릿 스토어를 붙일 때는 compose 옆에 로테이션 플레이북을 두고 동시 롤이 필요한 변수, 게이트웨이에서 먼저 카나리아로 굴릴 수 있는 변수, 워커가 낡은 자격 증명을 얼마나 참다가 깨끗이 종료해야 하는지를 적습니다. 부분 로테이션이 인증 폭풍의 촉매라는 점은 회고에서 반복됩니다. 마지막으로 애플리케이션 로그와 컨테이너 로그 드라이버의 보존 정책을 정렬합니다. Compose 쪽만 디스크를 최적화하고 다른 데몬이 파티션을 채우는 모순을 피합니다. 원격 Mac에서의 단기 검증은 원격 가이드의 대역폭·세션 제한을 미리 읽고 계획하는 것이 좋습니다.

생산 트래픽을 리눅스에 두더라도 스테이징에서 macOS 전용 경로를 완전히 무시하면 업그레이드 직전에만 터지는 클래스의 결함이 남습니다. 따라서 스테이징에 최소 한 대의 네이티브 Mac 슬롯을 배정해 동일한 doctor 시나리오를 주기적으로 돌리고, Compose 정의와 launchd 기반 노드의 차이를 표로 남기는 팀이 장기적으로 교체 비용이 낮습니다. 비용 측면에서는 베어 메탈 요금 페이지의 일 단위 옵션을 변경 창 길이와 맞추면 자본화 대비 현금 흐름을 예측하기 쉽습니다. 설치 경로가 여러 플랫폼에 걸친 경우 멀티플랫폼 설치 가이드의 검증 순서를 Compose 스모크 프로필에 그대로 옮기면 리뷰어가 의도를 빠르게 이해합니다.

정리하면 Compose는 의존성과 패키징을 정리해 주지만 “준비됨”의 의미와 경계, 관측, 롤백 단위는 팀이 명시해야 합니다. 본문의 매트릭스와 표, 다섯 단계, 지표는 그 명시를 위한 출발점이며 VPS 층 가이드와 Docker 생산 가이드, 설치 문서, Mac 렌탈 관련 페이지를 함께 읽을 때 운영 난이도가 실제로 내려갑니다.