OpenClaw 설치 튜토리얼·Docker 배포·리버스 프록시·프로덕션 보안·일반 오류·원격 Mac 워크플로를 한 흐름으로 정리했습니다. 명령·포트는 공식 Docker 문서 기준입니다. 홈 · 노트·가이드 · 도움말.
① 2026년 배경과 전형적 사용 시나리오
OpenClaw는 자체 호스팅 스택으로, 게이트웨이 WS(ws://127.0.0.1:18789)·컨트롤 UI·CLI·채널·도구 실행을 묶습니다. 전형 패턴: VPS 상시 게이트웨이(SSH/Tailscale); 원격 Mac(Xcode·macOS 스크립트·장시간 에이전트·배치). 본문은 개념보다 복붙 명령·포트·실패 징후 위주입니다.
② 환경·사전 점검 체크리스트
설치 전에 다음을 확인하세요.
- Node (CLI 경로) — README 기준 Node 24(권장) 또는 22.16+. npm install -g openclaw@latest 전 버전 일치.
- Docker + Compose v2 — 공식 문서: 이미지 빌드에 RAM 2GB 이상 권장(부족 시 exit 137 OOM).
- Git — 저장소 클론 후 ./scripts/docker/setup.sh 에 필요.
- DNS·TLS — UI를 공개할 호스트명·인증서(Let’s Encrypt 등).
- 방화벽 — VPS는 Security hardening for network exposure 및 Docker
DOCKER-USER안내를 upstream에서 확인.
③ 재현 가능한 설치: 전역 CLI vs Docker
권장 CLI 경로(README):
npm install -g openclaw@latest
openclaw onboard --install-daemon
openclaw gateway --port 18789 --verbose컨트롤 UI: http://127.0.0.1:18789/. 업데이트 후 openclaw doctor 권장.
Docker 경로(공식 Docker 문서 — 클론한 저장소 루트에서):
git clone https://github.com/openclaw/openclaw.git
cd openclaw
./scripts/docker/setup.sh로컬 빌드 생략·저사양 호스트:
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.sh게이트웨이 환경에서 샌드박스 부트스트랩: export OPENCLAW_SANDBOX=1 후 동일 스크립트(upstream 샌드박스 문서 참고).
CLI vs Docker 한눈에
| 항목 | 전역 CLI | Docker (scripts/docker/setup.sh) |
|---|---|---|
| 적합 | 로컬 빠른 루프, onboard 데몬 | 격리·재현 서버·호스트 오염 최소화 |
| 진입 명령 | openclaw onboard --install-daemon | ./scripts/docker/setup.sh (루트에서 실행) |
| 컨트롤 UI | http://127.0.0.1:18789/ | 포트 게시 후 동일 |
| 헬스 | curl -fsS http://127.0.0.1:18789/healthz | 동일·이미지 HEALTHCHECK는 /healthz |
| 설치 후 CLI | 호스트 openclaw … | docker compose run --rm openclaw-cli … |
④ 최소 프로덕션 보안: 리슨·토큰·샌드박스·아웃바운드
바인드. gateway.bind는 lan·loopback·tailnet 등 문서화된 값을 씁니다. Docker는 기본 OPENCLAW_GATEWAY_BIND=lan. Tailscale Serve/Funnel과 함께 쓸 때는 upstream 가이드대로 loopback을 맞춥니다.
토큰·UI. 토큰은 .env에 기록되며 루트급 비밀로 관리합니다.
DM. 인바운드 DM은 비신뢰 입력—pairing approve·openclaw doctor로 정책 확인.
샌드박스·아웃바운드. agents.defaults.sandbox.mode: "non-main" 등 upstream 샌드박스 문서 참고; 임의 출구 차단은 방화벽+도구 정책 병행.
⑤ Nginx·Caddy 리버스 프록시와 HTTPS
Tailscale·SSH 터널이 1급 패턴입니다. 범용 프록시는 TLS 종료 후 127.0.0.1:18789로 프록시합니다.
Caddy(예시)
claw.example.com {
reverse_proxy 127.0.0.1:18789
}Nginx — WS에 Upgrade·Connection; 경로는 docs.openclaw.ai/web.
점검: 443만 공개·레이트리밋·curl -fsS https://…/healthz.
⑥ 트러블슈팅 매트릭스
| 증상 | 가능 원인 | 실행·조치 |
|---|---|---|
| 18789 포트 사용 중 | 이전 게이트웨이·다른 서비스 | Linux: ss -tlnp | grep 18789; 포트 변경 또는 중복 compose 중지 |
| 컨트롤 UI 미인증 | 토큰 불일치·기기 페어링 | docker compose run --rm openclaw-cli dashboard --no-open; devices approve … |
| CLI에 ws://172.x·페어링 오류 | Docker에서 mode/bind 불일치 | config set gateway.mode local, config set gateway.bind lan 후 ws://127.0.0.1:18789 재확인 |
| 빌드 exit 137 | pnpm install·이미지 빌드 OOM | VM RAM ≥2GB 또는 OPENCLAW_IMAGE 사전 빌드 이미지 사용 |
| /home/node/.openclaw EACCES | 바인드 마운트 소유권 | sudo chown -R 1000:1000 … (컨테이너 uid 1000) |
| 샌드박스 컨테이너 없음 | 이미지 미빌드 | scripts/sandbox-setup.sh 또는 설정에 커스텀 샌드박스 이미지 |
| ready/헬스 실패 | 게이트웨이 미리슨 | curl -fsS http://127.0.0.1:18789/healthz 및 /readyz |
⑦ 업무 예시: 원격 Mac에서 빌드·스크립트·알림 E2E
임대·전용 Mac를 실행 섬으로 쓰고 SSH로 구동합니다. 첫 접속은 SSH·VNC 체크리스트 참고.
- Docker/Colima 또는 Node+CLI(③).
- openclaw onboard --install-daemon 또는 ./scripts/docker/setup.sh·설정·워크스페이스 영속 마운트.
- cron/launchd로 빌드; 산출물·종료 코드 로깅.
- 웹훅 알림(선택).
- 검증: ssh mac 'curl -fsS http://127.0.0.1:18789/healthz'; UI는 ssh -L 18789:127.0.0.1:18789 mac.
기대: 무인 배치·헬스 유지·18789 비공개(SSH 터널만).
⑧ FAQ·빠른 점검
게이트웨이 네이티브·에이전트만 샌드박스? 가능(upstream Sandboxing vs Docker 구분).
상태? OPENCLAW_CONFIG_DIR 등 바인드 마운트 백업.
무응답? docker compose ps / openclaw doctor → curl …/healthz.