# OpenClaw 배포 방법: 로컬 소스 설치와 Docker 중 무엇을 선택할까

> Canonical: https://vxi.me/ko/posts/openclaw-docker-vs-source-deployment/
> Locale: ko-kr
> Published: 2026-03-27
> Updated: 2026-03-27
> Markdown: https://vxi.me/ko/posts/openclaw-docker-vs-source-deployment.md

OpenClaw를 일단 실행해 보고 싶을 때 가장 쉽게 막히는 지점은 설치 명령 자체가 아니라 **처음부터 잘못된 설치 경로를 고르는 것**입니다.

처음 찾아보면 질문은 비슷합니다. 내 PC에 설치할지, 바로 cloud server에 올릴지, source 설치가 더 “정식”인지, Docker가 더 간단한지 고민하게 됩니다. 자료를 많이 볼수록 선택지가 늘어나 오히려 더 헷갈릴 수 있습니다.

공식 README와 Docker 문서를 다시 확인하면서 저는 이 문제를 “어떤 명령이 더 멋진가”가 아니라 **“지금 OpenClaw를 사용하려는가, 아니면 직접 운영과 개발까지 맡으려는가”**로 나눠 보게 됐습니다. 이 기준을 먼저 정하면 선택이 훨씬 쉬워집니다.

일반 사용자로서 오늘 바로 OpenClaw를 실행해 보고 싶은 정도라면 처음부터 source 설치를 선택할 이유가 크지 않습니다. 공식 README의 신규 사용자 흐름은 Node 24 또는 최소 Node 22.16+ 환경에서 CLI를 설치하고 onboarding을 진행하는 방식입니다.

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

이 흐름은 개발 환경 구축보다 “사용 시작”에 가깝습니다. CLI를 설치하고 onboarding을 따라 Gateway와 초기 설정을 마친 뒤 먼저 동작을 확인할 수 있습니다. 전체 프로젝트의 build 구조를 이해할 필요가 없습니다.

반대로 source 설치는 성격이 다릅니다. repository를 clone하고 `pnpm install`, `pnpm ui:build`, `pnpm build`를 거친 뒤 `pnpm openclaw onboard --install-daemon` 또는 `pnpm gateway:watch` 같은 개발 명령까지 직접 다루게 됩니다.

이 경로는 소스를 읽고, 동작을 수정하고, repository 변경에 맞춰 따라가고, 직접 debugging할 사람에게 더 적합합니다. source 설치가 더 “완전한 설치 방식”이라기보다 **개발자가 프로젝트 자체를 다루는 경로**라고 보는 편이 정확합니다.

일반 사용자 입장에서는 더 낮은 계층을 만지는 것이 항상 더 좋은 것은 아닙니다. Node version, dependency, UI build, upgrade compatibility까지 처음부터 관리해야 하기 때문입니다.

Docker도 “container니까 무조건 더 간단하다”고 생각하면 안 됩니다. OpenClaw 공식 Docker 문서에서도 Docker는 optional입니다. 로컬 PC에서 한 번 써 보는 것이 목적이라면 Docker Desktop 또는 Docker Engine, Compose v2, image build resource 같은 새로운 전제 조건이 추가됩니다. 공식 문서에서도 image build 때 충분한 memory가 없으면 `pnpm install`이 종료될 수 있다고 안내합니다.

그래서 자신의 PC에서는 CLI 방식이 가장 마찰이 적은 경우가 많습니다.

반면 Linux server에서 Gateway를 장기간 실행하려는 목적이라면 Docker가 자연스러워집니다. 이때 Docker는 설치 방법보다 **서비스 배포 방식**에 가깝습니다.

- runtime을 container 안에 분리
- 다른 host로 이전하기 쉬움
- 재생성 절차를 고정하기 쉬움
- server의 다른 서비스와 격리하기 쉬움

공식 Docker 흐름도 단순히 `docker run` 한 줄로 끝나는 구조가 아닙니다. repository root의 setup script가 image, onboarding, `.env`, Docker Compose 시작을 처리합니다.

```bash
./scripts/docker/setup.sh
```

로컬 build 대신 미리 빌드된 image를 사용할 수도 있습니다.

```bash
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.sh
```

이 구조만 봐도 Docker가 “OpenClaw를 처음 만지는 최소 설치”라기보다 **Gateway를 서비스로 배치하는 운영 경로**라는 것을 알 수 있습니다.

제가 목적별로 나눈다면 다음과 같습니다.

## 목적별 선택 가이드

### 내 PC에서 오늘 바로 사용하고 싶다

공식 CLI부터 시작합니다.

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

처음부터 source repository를 clone할 필요는 없습니다.

### cloud Linux server에서 상시 실행하고 싶다

Docker를 우선 검토합니다.

server에서는 container의 재생성 가능성과 환경 분리가 더 큰 장점이 됩니다. 물론 Docker가 운영을 없애 주는 것은 아닙니다.

- persistent data
- port
- health check
- image update
- Gateway 노출 범위
- firewall

이런 요소는 계속 관리해야 합니다.

공식 문서에 `healthz`, `readyz`, `lan`, `loopback` 같은 항목이 나오는 것도 Docker 경로가 운영자를 위한 배포 방식이라는 점을 보여줍니다.

### 코드를 읽고 수정하고 싶다

source 설치를 선택합니다.

이 경우 build 과정과 dependency까지 직접 관리하는 것이 목적에 맞습니다. 구현에 가까워지고 투명성이 높아지지만, 그만큼 개발 script와 의존성도 일상적인 유지보수 대상이 됩니다.

## 자주 하는 선택 실수

첫 번째는 source 설치를 “가장 정식인 설치”라고 생각하는 것입니다. 사용이 목적이라면 개발 환경까지 함께 들고 가면서 초기 비용만 늘릴 수 있습니다.

두 번째는 Docker를 “항상 더 쉬운 방법”이라고 생각하는 것입니다. 특히 로컬 PC에서는 container 환경 자체가 새로운 장벽이 될 수 있습니다.

세 번째는 Node version 같은 runtime requirement를 가볍게 보는 것입니다. 초기 전제가 맞지 않으면 이후 오류 대부분이 파생 문제로 이어집니다.

마지막은 server에서 한 번 실행됐다고 작업이 끝났다고 생각하는 것입니다. 장기 운영에서는 container 자체보다 **데이터와 설정을 어떻게 복구할 것인지**가 더 중요합니다.

OpenClaw를 server에 오래 둘 계획이라면 처음부터 backup과 recovery path도 같이 생각해 두는 편이 좋습니다. [Docker Volume을 GitHub에 자동 백업하기: 1Panel용 저비용 복구 구성](/ko/posts/docker-volume-backup-github-sync/)처럼 작은 복구 경로부터 만들어 두는 것도 방법입니다.

OpenClaw 문서를 보고 느낀 가장 단순한 결론은 이겁니다. 공식이 하나의 설치 방법만 제공하는 것이 아니라 **서로 다른 사용자에게 맞는 여러 경로를 제공한다**는 것입니다.

“먼저 사용해 보고 싶다”와 “직접 운영·개발까지 맡고 싶다”를 섞지 않으면 선택은 훨씬 쉬워집니다.

배포 관련 글을 더 보고 싶다면 [배포 주제 페이지](/ko/topics/deployment/)도 이어서 볼 수 있습니다.