npm 설치·launchd·SecretRef 글을 읽은 뒤에도 「환경 재현성」이 부족하다면 OpenClaw 컨테이너화가 다음 단계입니다. 본문은 2026년 원격 Mac에서 OpenClaw를 장기 실행하려는 운영자·고급 사용자를 위해 베어메탈 설치와 컨테이너를 비교하고, 공식 이미지·Compose 볼륨·포트 18789, 컨테이너 내부 onboard 시 주의점, VNC 그래픽 세션에서 브라우저로 콘솔을 검증하는 이유를 정리합니다.
① Docker를 선택하는 시점: npm·설치 스크립트와의 비교
2026년 OpenClaw는 install.sh, npm i -g, OCI 이미지가 공존합니다. 컨테이너의 핵심 가치는 트렌디함이 아니라 디렉터리 이전·버전 고정·예측 가능한 롤백입니다. 설정과 상태를 이름 있는 볼륨이나 바인드 마운트에 두면 compose 파일과 백업만으로 호스트를 옮길 수 있습니다. 반면 전역 npm은 개인 개발기에서의 빠른 반복에 적합합니다.
임대 중인 원격 Mac에서는 여러 고객·프로젝트가 한 기기를 공유할 수 있으므로, Docker의 서로 다른 compose 프로젝트 이름으로 포트와 볼륨을 분리하면 「전역 npm 업그레이드가 고객 A를 깨뜨리는」 사고를 줄일 수 있습니다. Docker CLI가 익숙하지 않다면 Docker Desktop 또는 Colima 설치를 먼저 완료하십시오.
동일 Mac에서 npm 직접 설치와 컨테이너의 차이
npm 경로는 셸 프로필과 nvm 선택에 좌우됩니다. compose 경로는 YAML에 선언한 내용만이 사실이 되어 인수인계에 유리합니다. Docker Desktop을 쓰면 lsof로 보이는 리스닝 주체가 달라질 수 있으므로, 문서의 localhost가 어느 네임스페이스를 가리키는지 확인하십시오.
공식 이미지 예로 ghcr.io/openclaw/openclaw가 자주 인용됩니다. 다이제스트 고정 여부와 릴리스 노트 확인은 운영 정책에 따릅니다. 항상 공식 저장소의 최신 compose 예시와 대조하십시오.
② 컨테이너화 이후에도 남는 다섯 가지 이슈
- 데이터 볼륨과 권한: 컨테이너 내부 UID와 호스트 소유자가 다르면
~/.openclaw마운트가 읽기 전용이 될 수 있습니다. compose에서user를 명시하거나 소유권을 맞추십시오. - 포트와 루프백: 웹 콘솔·게이트웨이는 18789 등이 문서화되는 경우가 많습니다.
127.0.0.1에만 바인딩하면 SSH 터널과 VNC 내 브라우저에서 동작이 달라질 수 있습니다. - onboard와 TTY:
docker compose run --rm을 비대화형으로 실행하면 마법사가 멈출 수 있습니다. 최초에는 대화형으로 완료한 뒤 상시 서비스는 분리 모드로 전환합니다. - launchd와의 관계: 컨테이너 프로세스와 호스트 launchd가 동일 바이너리를 이중 기동하지 않도록 합니다. 일반적으로 호스트는 docker compose 기동만 담당하거나 재시작 정책에 맡깁니다. 자세한 내용은 launchd 체크리스트를 참고하십시오.
- SecretRef와 마운트: 비밀 파일을 컨테이너에 넣을 때도 권한과 감사가 중요합니다. SecretRef 감사 글을 따라 평문이 이미지 레이어에 남지 않도록 하십시오.
③ 결정표: 베어메탈·Docker·다중 프로젝트
| 항목 | npm / 스크립트 베어메탈 | Docker / Compose(본문) | 다중 compose 프로젝트 |
|---|---|---|---|
| 적합한 경우 | 로컬 개발·버전 시험 | 재현 가능한 배포·태그 고정 | 다중 고객·다중 저장소 분리 |
| 롤백 | 전역 Node 상태에 의존 | 이미지 태그·다이제스트 교체 | 프로젝트별 독립 롤백 |
| 운영 부담 | 단일 사용자에게는 낮음 | 중(볼륨·네트워크 이해) | 높음(포트·볼륨 명명 규칙) |
| launchd 조합 | 흔함 | 호스트는 compose, 컨테이너는 자체 복구 | 인스턴스별 디렉터리 분리 |
API 키·환경 분리는 다중 프로젝트 API 키·환경 체크리스트와 함께 읽으시기 바랍니다.
④ 절차: 이미지 pull부터 콘솔 검증까지
아래는 교육용 최소 골격입니다. 실제 필드 값은 OpenClaw 공식 저장소와 GHCR의 현재 태그에 맞추십시오.
디렉터리와 Docker 환경
원격 Mac에 ~/openclaw-docker 등을 만들고 docker compose version을 확인합니다. 볼륨은 지연 큰 네트워크 스토리지는 피합니다.
compose: 이미지·볼륨·포트
GHCR 예시:
services:
openclaw:
image: ghcr.io/openclaw/openclaw:latest
ports:
- "18789:18789"
volumes:
- openclaw_config:/root/.openclaw
- ./workspace:/workspace
restart: unless-stopped
volumes:
openclaw_config:
환경 변수·사용자 매핑·헬스 체크는 공식 템플릿을 따르십시오. API 키가 들어 있는 .env는 Git에 커밋하지 마십시오.
최초 onboard(대화형 권장)
docker compose run --rm openclaw openclaw onboard 등으로 마법사를 완료합니다. 브라우저가 필요하면 VNC 세션 안에서 열어 콜백 주소가 어긋나지 않게 합니다.
상시 서비스 기동
docker compose up -d 후 docker compose logs -f로 바인드 오류·권한·의존성 문제를 확인합니다. 이해하기 어려운 메시지는 자주 나는 오류와 점검 가이드를 참고하십시오.
VNC 브라우저로 콘솔 검증
Safari 또는 Chrome에서 http://127.0.0.1:18789에 접속합니다(포트는 문서 우선). 외부에서만 SSH할 경우 터널과 방화벽도 함께 확인합니다.
VNC 브라우저는 권한 대화상자·키체인 조작을 가시적으로 확인하고, localhost 의미를 문서와 일치시키기 쉽습니다.
⑤ 인용 메모와 점검 목록
openclaw_config는 Alpine 일회용 컨테이너로 tarball 백업을 만들기 쉽습니다(명령은 환경에 맞게 조정).- compose의 포트가 문서와 일치하고 충돌이 없음
- 볼륨이 쓰기 가능하며 백업 정책이 정해짐
- VNC 브라우저에서 콘솔 또는 헬스 엔드포인트 200 응답
- 비밀이 이미지 레이어에 없고 감사 요건 충족
⑥ FAQ 및 관련 글
호스트 자동 기동을 컨테이너 재시작 정책 외에 구성하려면 launchd 글을 참고하여 동일 프로세스 이중 기동을 피하십시오. 다중 환경 API 키는 다중 프로젝트 글, 비밀 관리는 SecretRef 글, 일반 오류는 오류 점검 글과 함께 읽으시기 바랍니다.
맺음말: 컨테이너는 재현성, 원격 Mac은 macOS 검증
노트북에서 Dockerfile만 작성해도 권한·볼륨·브라우저·방화벽은 Linux CI와 다를 수 있습니다. 여유 Mac이 없다면 VNC가 있는 원격 Mac을 임대하여 한 번에 통과 검증하는 편이 실전에 가깝습니다. 단기 평가용으로 기기를 구매하면 감가와 유지 비용이 부담되므로, 패키지로 격리 노드를 빌려 compose·볼륨 전략을 확정한 뒤 장기 투자를 결정하는 편이 시간을 절약합니다. VNCMac은 그래픽 원격 데스크톱과 연결 안내로 onboard와 브라우저 검증을 터미널만 사용할 때보다 빠르게 마칠 수 있도록 돕습니다.