2026 OpenClaw 프로덕션
Docker·상시 Gateway, 트러블슈팅과 롤백

약 16분 읽기 · MACCOME

플랫폼별 설치가 되어도 프로덕션은 24/7 Gateway·건전한 Docker 볼륨·상태를 지키는 업그레이드가 별문제입니다. 에이전트를 계약 가능한 서비스에 가깝게 만들려는 팀을 위해 사전 체크리스트, Docker vs npm 트레이드오프, 상시 Compose 패턴, 증상별 분류표, 토큰·로그·백업·롤백 순서를 정리합니다. Windows/macOS/Linux 설치 글과 함께 읽고, 안정적인 아웃바운드 호스트가 필요하면 원격 Mac 실행층도 참고하세요.

“돌아간다”에서 “당번”으로 갈 때 흔한 여섯 가지 함정

  1. 개발 노트북만 유일한 Gateway로 두기:절전·업데이트·GUI 대화상자로 세션이 끊기고 전용 노드보다 복구 비용이 커집니다.
  2. latest 무분별 추종:업스트림이 하룻밤에 포트·설정 스키마를 바꾸고 CI pull이 무공지 릴리스가 됩니다.
  3. 볼륨 UID 줄다리기:root와 컨테이너 사용자 소유권 불일치가 SQLite·I/O의 모호한 오류로 보입니다.
  4. 모델 벤더와 아웃바운드가 맞지 않음:기업 프록시·지역 제한은 403보다 타임아웃으로 나타나기 쉽습니다.
  5. Gateway 토큰을 평문으로 Git에:CI와 노트북 비밀 혼재는 퇴사·포크 리스크를 키웁니다.
  6. “재설치” 외 롤백 절차가 없음:RTO를 설명할 수 없고 복구도 재현하기 어렵습니다.

Windows/macOS/Linux 차이가 아직 흐리면 먼저 OpenClaw 설치·플랫폼 선택을 읽고 컨테이너 이야기로 돌아오세요.

사전 점검: Node·메모리·키·아웃바운드(15분)

커뮤니티 설치 도구와 Docker 이미지는 계속 변합니다. 아래는 수량감이며 고정한 릴리스 설명과 반드시 대조하세요.

  • 런타임: 2026년 기준 많은 문서는 Node 20 LTS 또는 22를 전제로 합니다. 이미지에 포함되는 경우가 많고 호스트는 Docker Engine·Compose 플러그인이 최신이면 충분할 수 있습니다.
  • 메모리: 가벼운 Gateway도 컨테이너 상한 2~4GB를 기준으로 하고 채널 병렬·로컬 모델이 있으면 여유를 더하세요.
  • 비밀: 벤더용과 Gateway 인증용 최소 권한 키를 분리하고 오케스트레이션 secret과 마운트 파일을 함께 순환합니다.
  • 아웃바운드: Gateway와 동일 경로에서 벤더 API를 프로브하고 기업 MITM·프록시를 검증합니다.
관점Docker Compose(프로덕션)로컬 npm/설치기(반복)
재현성높음: 이미지가 의존성 고정중간: 전역 Node/OS 드리프트
격리·다중 인스턴스쉬움: 네트워크·볼륨·리소스 한도어려움: 포트·설정 충돌
업그레이드 속도통제: 태그·digest 단계 배포빠름: upstream main 추적 용이
디버깅exec·소스 bind-mount브레이크포인트 직접
운영 비용pull·볼륨 백업·compose 위생호스트 오염·데몬 정합
bash
# 예시 흐름—서비스명은 고정한 릴리스 문서를 따름
git clone https://github.com/openclaw/openclaw.git && cd openclaw
# 제공되면: bash docker-setup.sh
# docker compose pull
# docker compose run --rm <cli-service> onboard
# docker compose up -d <gateway-service>
# docker compose ps
# curl -fsS http://127.0.0.1:<health-port>/health || echo "경로는 문서 참조"
warning

주의: 서비스명·환경 변수·헬스 경로는 릴리스마다 바뀝니다. 스니펫은 패턴으로만 보고 고정한 태그 공식 절차로 검증하세요.

Compose로 Gateway를 상시 가동하는 여섯 단계

  1. 버전 고정: compose에 이미지 태그나 digest를 명시하고 프로덕션 익명 드리프트를 금지합니다.
  2. 볼륨 분리: 설정·상태·로그를 나누고 클래스별 백업 RPO를 정합니다.
  3. 의존·재시작: restart: unless-stopped는 크래시 복구용이며 잘못된 설정은 고치지 않습니다. 헬스 체크를 추가합니다.
  4. 헬스 체크: 공식 HTTP/TCP 프로브를 쓰고 LB·watchdog 의미와 맞춥니다.
  5. 가시성: stdout 또는 파일 중 하나로 검색 가능한 로그를 남겨 알림에 연결합니다.
  6. 변경 관리: 포트·볼륨·환경 변수 변경은 diff와 롤백 태그를 남기고 구두 인프라로 두지 않습니다.
증상의심 순서권장 조치
Gateway 즉시 종료환경 변수 부족·엔트리포인트 변경compose 로그를 읽고 필수 키를 릴리스 노트와 대조
포트 사용 중오래된 프로세스·호스트 충돌ss -lntp로 소유자 특정 후 재매핑 또는 중지
모델 타임아웃아웃바운드·프록시·DNS·리전컨테이너 내부 curl로 확인·인증서/프록시 점검
SQLite / 락이중 라이터·UID 불일치주 라이터를 하나로 하고 볼륨 권한 수정

프로덕션 하드닝: 토큰·노출·백업·롤백 순서

Gateway 토큰은 시크릿 주입으로 넣고 이미지 레이어에 굽지 마세요. HTTP를 공개하면 앞단에서 TLS 종료·레이트 리밋을 두고 내부라도 횡이동을 가정합니다.

롤백 순서: ① 실행 digest·compose 리비전 기록 ② Gateway 중지 ③ 볼륨 스냅샷 복원 ④ 이전 태그로 docker compose up -d ⑤ 헬스·E2E 프로브 1회

운영 리뷰에 올릴 세 가지 수치

  1. 콜드 스타트~정상: compose up에서 프로브 성공까지 P95를 추적하고 튀면 CPU보다 pull·볼륨 I/O를 의심합니다.
  2. 오류 유형·지연: 4xx/5xx와 TCP 타임아웃을 분리해 레이트 리밋을 Gateway 다운으로 오인하지 않게 합니다.
  3. 복원 훈련: 분기마다 격리 호스트에 볼륨 복원 후 Gateway 기동—RTO를 숫자로 제시합니다.

상시 원격 Mac에 Gateway를 올릴지 판단

Xcode 빌드·시뮬레이터·서명 등 Apple 툴체인과 에이전트를 같이 쓰는 팀은 개인 노트북보다 과금 가능한 24/7 전용 Mac(베어메탈)로 Gateway를 옮기는 편이 안정적입니다. 데몬·로그는 SSH 기본, GUI 분석만 VNC로—SSH/VNC 가이드를 보세요.

노트북만으로는 프로덕션 Gateway가 되기 어려운 이유

절전 정책·들쭉날쭉한 OS 업데이트·다인 디버깅 시 포트 누설이 노트 운영의 약점입니다. digest 미고정 컨테이너는 호스트 드리프트를 재현성의 환상으로 가릴 뿐입니다.

지속 가능한 패턴은 전용 원격 Mac(또는 동급 베어메탈)에서 Compose로 런타임을 고정하는 실행면입니다. MACCOME 클라우드 Mac은 다리전 Apple Silicon과 명확한 대여 조건을 제공하며 OpenClaw를 iOS/macOS 자동화와 함께 둘 때 유용합니다. 지역은 멀티리전 가이드와 공개 요금으로 비교하고싱가포르·도쿄·서울·홍콩·미 동부·미 서부에서 주문할 수 있습니다.

연결·세션은 고객 센터를 참고하세요.

자주 묻는 질문

프로덕션은 Docker와 npm 중 무엇인가요?

재현성은 Compose, 깊은 디버깅은 로컬 npm. 단계 설계는 설치·플랫폼 선택부터.

Gateway가 죽었을 때 먼저?

포트·헬스 경로·컨테이너 아웃바운드·볼륨 권한. SSH/VNC·연결은 고객 센터.

원격 Mac 접속과의 조합은?

자동화는 SSH 우선, GUI는 필요 시 VNC—SSH/VNC 가이드.

리전과 요금 비교는?

멀티리전 의사결정표와 대여 요금.