2026년 OpenClaw: npm 글로벌 설치 vs Docker Compose — 팀에 맞는 배포 경로

OpenClaw는 2026년 기준 여러 진입점을 제공합니다: curl 설치 스크립트, npm 글로벌 패키지, 프로세스 격리를 원하는 팀을 위한 Docker Compose 스택입니다. 이 글은 Apple Silicon Mac, 특히 MacHTML 고객이 쓰는 클라우드 Mac mini 렌탈에서 npm 우선과 Docker 우선 워크플로를 비교해 보안 기준, 업그레이드 주기, 자동화 예산에 맞는 경로를 고르게 돕습니다.

두 경로가 공유하는 전제

패키징과 관계없이 OpenClaw는 2026년 많은 튜토리얼이 가리키는 CLI와 게이트웨이 데몬에 Node.js 22 이상을 기대합니다. AI 공급자 키(Anthropic, OpenAI, 로컬 Ollama 엔드포인트)와 모델 호출용 아웃바운드 HTTPS도 필요합니다. Apple Silicon에서는 Rosetta를 Node 워크로드에 켜지 않는 편이 좋고, 스로틀되는 x64 바이너리를 실수로 설치하지 않도록 합니다.

디스크는 생각보다 중요합니다: npm 캐시와 게이트웨이 로그에 여유 8GB 이상, Docker 베이스 레이어를 당기면 추가 4~6GB를 예상하세요. RAM은 가벼운 에이전트 루프에 2GB, 브라우저 자동화 스킬을 게이트웨이와 함께 돌리면 4GB 이상이 기준입니다. 로컬 임베딩을 메모리에 상시 올리거나 여러 공급자를 동시에 유지하면 더 필요합니다.

npm 글로벌: 장단점과 명령

npm 경로는 개발 노트북이나 렌탈 Mac mini에서 동작하는 CLI를 가장 빨리 얻는 방법입니다. nvm이나 공식 pkg로 Node를 설치한 뒤 다음을 실행합니다.

npm install -g openclaw@latest
openclaw onboard --install-daemon

강점은 즉시 업그레이드(npm update -g openclaw), which openclaw로의 단순한 디버깅, OAuth 연결 시 macOS 키체인 헬퍼에 대한 네이티브 접근입니다. 약점은 멀티테넌트 운영에서 드러납니다: 글로벌 설치는 소유권이 흐려지고, 머신 스냅샷 없이는 롤백이 어려우며, 엔지니어가 개인 사용자로 게이트웨이를 돌려 서비스 계정을 분리하지 않을 유혹이 생깁니다.

이 사이트의 HTML/CSS 자동화 글과 함께 쓸 때는 localhost 실험을 넘어서면 리버스 프록시와 터널 강화를 참고하세요.

Docker Compose: 장단점과 명령

Docker는 보안이나 컴플라이언스가 불변 인프라를 요구할 때 매력적입니다. 흔한 부트스트랩은 상위 저장소를 clone하고 CLI 컨테이너를 한 번 실행한 뒤 게이트웨이를 띄웁니다.

git clone https://github.com/openclaw/openclaw.git
cd openclaw
docker compose run --rm openclaw-cli onboard
docker compose up -d openclaw-gateway

컨테이너는 이미지로 버전을 고정하고, 비밀용 볼륨을 분리하며, 호스트 네트워크 스택을 건드리지 않고 이그레스 프록시를 붙일 수 있습니다. 트레이드오프는 반복 루프가 느려질 수 있다는 점(코드 변경마다 재빌드)과 macOS에서 Docker Desktop이나 Colima를 건강히 유지하는 운영 부담입니다. 클라우드 Mac mini에서는 많은 팀이 compose 파일을 /opt/openclaw에 두고 systemd나 launchd plist로 스택을 한 번에 재시작합니다.

나란히 비교 표

차원	npm 글로벌	Docker Compose
첫 openclaw 명령까지	5분 미만	10~20분(이미지 pull)
업그레이드 마찰	낮음(npm 한 번)	중간(pull+재시작)
호스트 격리	최소	강함
스택 트레이스 디버깅	네이티브 lldb/node 쉬움	docker exec 필요
일회성 클라우드 Mac 적합성	스파이크에 탁월	상시 게이트웨이에 탁월

한 대 클라우드 Mac에 npm과 Docker 병치

고급 팀은 이중 설치를 두기도 합니다: 대화형 실험은 npm, Slack이나 Telegram 웹훅을 마주 본 프로덕션 성 게이트웨이는 Docker입니다. API 키가 섞이지 않도록 디렉터리와 환경 파일을 나눕니다. 렌탈 Mac mini에서는 온보딩 후 compose 프로젝트를 스냅샷하고, SSH로 합류하는 동료를 위해 재시작 순서를 문서화합니다.

Apple Silicon은 M2·M3·M4 계열에서 arm64가 맞춰져 예전 Intel 클라우드에서 Rosetta가 Node 애드온을 복잡하게 만든 상황과 다릅니다. 그 일관성이 낡은 배터리 MacBook을 돌려 쓰기보다 전용 MacHTML 노드를 택하는 이유 중 하나입니다: 열과 24/7 가동이 예측 가능하고 책상 아래 팬 소음도 없습니다.

노출 게이트웨이 보안 알림

npm이든 Docker든 인증 없이 게이트웨이를 0.0.0.0에 바인딩하지 마세요. 2026년 초 연구에서는 토큰 게이트나 egress 필터가 없는 에이전트 엔드포인트가 수만 개 발견되었습니다. nginx나 Caddy 앞단에서 TLS를 종료하고, 관리 API는 루프백이나 VPN으로만 제한하세요. 이런 통제는 패키지 선택이 아니라 운영 책임입니다.

문제 해결: doctor와 로그

온보딩이 실패하면 npm은 openclaw doctor, 컨테이너는 docker compose run --rm openclaw-cli doctor부터 시작하세요. Node 버전 불일치, 빠진 API 키, 막힌 아웃바운드 포트를 약 30초 안에 드러냅니다. 이슈를 열기 전에 이 stdout을 남기면 메인테이너와의 왕복이 절반으로 줄어듭니다.

로그 위치는 갈립니다: npm은 보통 ~/.openclaw/logs, Compose는 compose 파일 옆 ./data/logs 같은 볼륨에 매핑합니다. 바쁜 게이트웨이는 주간 로테이션을 하세요. 디버그를 켜 둔 채 방치하면 에이전트가 주당 200MB급 로그를 낼 수 있습니다. 모델 429가 반복되면 동시 스킬을 줄이거나 임베딩을 로컬에 캐시해 한도 아래로 맞춥니다.

또한 스킬이 프로젝트 디렉터리에 쓸 때 파일 권한을 확인하세요. Docker는 기본적으로 컨테이너 안 root로 돌아 바인드 마운트한 저장소에 root 소유 산출물을 남기기 쉽습니다. compose 오버라이드로 비 root 사용자를 추가하거나 온보딩 후 볼륨을 chown해 CI checkout을 깨끗이 유지하세요.

HTML/CSS 리팩터를 자동화하는 팀은 OpenClaw를 Playwright나 린터와 같은 저장소에서 연쇄시키는 경우가 많습니다. 그 레이아웃에서는 에이전트 작업 공간을 git 작업 트리와 같은 볼륨에 두어 npm이든 Docker든 git status 한 번으로 diff 리뷰가 되게 합니다. 원격 Mac으로 SSH 왕복 512ms 지연이 있어도, 에이전트가 작업 트리를 못 봐 깨진 셀렉터를 출하하는 것보다 낫습니다.

자주 묻는 질문

Docker면 호스트에 Node가 필요 없나요?

컨테이너 안에서는 여전히 Node 기반 OpenClaw 바이너리가 실행됩니다. 호스트에는 Docker 엔진과 이미지·볼륨용 디스크만 있으면 됩니다. 글로벌 npm 트리를 호스트를 더럽히지 않을 수 있습니다.

주간 릴리스 OpenClaw에서 어느 쪽이 더 빨리 업데이트되나요?

npm 글로벌은 보통 npm update 한 번으로 새 빌드를 가져옵니다. Docker는 이미지 pull과 Compose 재시작이 필요해 느리지만 머신 간 재현성이 높습니다.

curl 설치 스크립트와 Docker를 같은 호스트에 섞을 수 있나요?

가능하지만 설정 디렉터리와 포트를 분리하세요. curl 스크립트는 /usr/local에 바이너리를 두고 Compose는 별도 설정 볼륨을 마운트합니다. 둘 다 같은 게이트웨이 포트를 쓰면 충돌합니다. 프로덕션 트래픽용 주 런타임은 하나로 정하고 나머지는 스크래치 환경으로 취급하세요.

Mac mini를 렌탈하면 두 방식을 깨끗한 방에서 시험할 수 있습니다: 개발 노트북을 되찾는 것보다 빠르게 지우거나 재프로비저닝할 수 있고, 로컬이 절전 중일 때도 장시간 Docker 게이트웨이를 온라인으로 둘 수 있습니다. Apple Silicon은 여러 에이전트가 메시징 API를 폴링해도 Node 이벤트 루프를 민첩하게 유지하고, 많은 OpenClaw 플러그인이 가정하는 파일 경로와 Keychain을 갖춘 참조 플랫폼은 여전히 macOS입니다. HTML/CSS 자동화 스킬을 다듬는다면 이해관계자에게 Safari로 데모할 때 “컨테이너에선 재현되지 않았다”는 놀람을 줄일 수 있습니다.