OpenClaw은 TypeScript로 구축되어 Node.js 위에서 실행되므로 본질적으로 크로스 플랫폼 기능을 갖추고 있습니다. macOS, Linux, Windows 중 어떤 것을 사용하든, 로컬 데스크톱이든 클라우드 서버이든 해당하는 배포 방안이 있습니다. 본 문서에서는 각 플랫폼의 설치 방법과 클라우드 호스팅 옵션을 체계적으로 정리하여 가장 적합한 배포 경로를 찾을 수 있도록 돕습니다.
기술 기반
OpenClaw의 핵심인 Gateway(게이트웨이 서비스)는 TypeScript로 작성되어 Node.js 런타임에 의존합니다. 즉, Node.js를 실행할 수 있는 환경이라면 이론적으로 OpenClaw을 배포할 수 있습니다.
한 가지 특별히 주의할 점: Gateway를 실행하는 데 Bun을 사용하지 마세요. Bun은 대부분의 Node.js API와 호환되지만, WhatsApp과 Telegram 연결 처리 시 알려진 버그가 있어 메시지 송수신 이상이 발생합니다. 반드시 공식 Node.js 런타임을 사용하세요.
지원되는 클라이언트 플랫폼
핵심 Gateway 서비스 외에도 OpenClaw은 다양한 디바이스에서 관리하고 모니터링할 수 있는 멀티 플랫폼 컴패니언 앱(Companion App)을 제공합니다:
| 플랫폼 | 상태 | 설명 |
|---|---|---|
| macOS | 출시됨 | 메뉴 바 상주 도구, 빠른 상태 확인 및 서비스 관리 |
| iOS | 출시됨 | 모바일 관리, 언제 어디서나 메시지 및 설정 확인 |
| Android | 출시됨 | iOS와 동일, 알림 푸시 지원 |
| Windows | 개발 중 | 데스크톱 클라이언트, 곧 출시 예정 |
| Linux | 개발 중 | 데스크톱 클라이언트, 곧 출시 예정 |
명확히 해야 할 것은 컴패니언 앱은 Gateway를 관리하고 모니터링하기 위한 것이며, 메시지를 처리하는 핵심 서비스인 Gateway 자체는 별도로 배포하고 실행 상태를 유지해야 한다는 점입니다.
Gateway 설치 방법
OpenClaw은 네 가지 설치 방법을 제공하며, 간단한 것부터 유연한 것 순으로 나열합니다.
방법 1: 원클릭 설치 스크립트 (권장)
공식 인터랙티브 설치 마법사가 환경 감지, 의존성 설치, 기본 설정을 자동으로 완료합니다:
curl -fsSL https://openclaw.ai/install.sh | bash
대부분의 사용자에게 가장 권장하는 방법입니다. 스크립트가 Node.js 버전 확인, Gateway 설치, 초기화 설정을 안내합니다.
방법 2: npm 전역 설치
이미 Node.js 환경이 있다면 npm을 통해 직접 설치할 수 있습니다:
npm install -g openclaw@latest
설치 완료 후 터미널에서 openclaw 명령을 찾을 수 없다면 npm 전역 설치 경로가 시스템 PATH에 포함되어 있는지 확인해야 합니다:
npm prefix -g
출력된 경로의 bin 디렉토리를 PATH 환경 변수에 추가하면 됩니다.
방법 3: 소스 코드에서 빌드
커스터마이징이나 개발 참여가 필요한 사용자에게 적합합니다:
git clone https://github.com/openclaw-ai/openclaw.git
cd openclaw
pnpm install
pnpm build
pnpm 사용 시 빌드 스크립트를 승인하는 추가 단계가 필요합니다:
pnpm approve-builds -g
방법 4: Gateway 직접 설치
Gateway 핵심 컴포넌트만 필요하고 전체 도구 체인이 필요 없다면 Gateway 패키지를 개별적으로 설치할 수도 있습니다. 구체적인 패키지명과 방법은 공식 문서를 참조하세요.
설치 후 초기화
어떤 방법으로 설치하든 완료 후에는 다음 세 단계를 실행하는 것이 좋습니다:
# 1. 가이드 프로그램 실행, 초기 설정 완료 및 데몬 프로세스 설치
openclaw onboard --install-daemon
# 2. 환경 정상 여부 확인
openclaw doctor
# 3. 관리 패널 열기
openclaw dashboard
openclaw doctor는 Node.js 버전, 네트워크 연결, 설정 파일 등 핵심 항목을 검사하여 문제를 빠르게 찾는 데 도움을 줍니다.
각 운영체제별 배포 요점
macOS
macOS는 OpenClaw의 일급 시민 플랫폼입니다. Gateway 설치 후 LaunchAgent를 통해 부팅 시 자동 시작 및 백그라운드 실행을 구현할 수 있습니다. openclaw onboard --install-daemon이 해당 LaunchAgent 설정 파일을 자동으로 생성하므로 plist를 수동으로 작성할 필요가 없습니다.
Linux
Linux 서버는 프로덕션 환경 배포의 최적 선택입니다. systemd user services를 사용하여 Gateway 프로세스를 관리하고, 자동 재시작 및 로그 관리를 구현하는 것이 좋습니다. 마찬가지로 openclaw onboard --install-daemon이 systemd 서비스 파일을 자동으로 생성합니다.
서비스 생성 후 다음 명령으로 관리할 수 있습니다:
systemctl --user start openclaw
systemctl --user enable openclaw
systemctl --user status openclaw
Windows
Windows 사용자에게는 WSL2(Windows Subsystem for Linux 2)를 사용하여 Gateway를 실행하는 것을 권장합니다. WSL2는 완전한 Linux 커널 환경을 제공하여 네이티브 Windows에서 발생할 수 있는 호환성 문제를 방지합니다.
# WSL2에서 설치
wsl
curl -fsSL https://openclaw.ai/install.sh | bash
WSL2의 Gateway도 systemd로 관리할 수 있습니다(WSL2에서 systemd 지원을 활성화해야 함).
클라우드 호스팅 방안
Gateway를 24시간 안정적으로 운영하려면 클라우드에 배포하는 것이 더 나은 선택입니다. 커뮤니티에서 검증된 호스팅 방안은 다음과 같습니다:
| 방안 | 특징 | 적합한 시나리오 |
|---|---|---|
| VPS (Vultr, DigitalOcean 등) | 완전한 제어, 유연한 설정 | 운영 경험이 있는 사용자 |
| Fly.io | 컨테이너화 배포, 글로벌 노드 | 저지연을 추구하는 사용자 |
| Hetzner + Docker | 가성비 높은 유럽 데이터센터 | 예산에 민감한 사용자 |
| Google Cloud Compute Engine | 엔터프라이즈급 인프라 | 고가용성이 필요한 팀 |
| exe.dev | VM 제공 및 HTTPS 프록시 포함 | 빠른 온라인을 원하는 사용자 |
VPS가 가장 범용적인 방안입니다. 전체 서버를 제어할 수 있으며 필요에 따라 환경을 설정할 수 있습니다. 최소 1코어 2GB 메모리면 OpenClaw Gateway를 원활하게 실행할 수 있습니다.
배포 권장사항
다양한 시나리오에 따른 실용적인 권장사항:
- 개인 체험용: 로컬 macOS 또는 Linux 머신에서 원클릭 스크립트로 설치하면 몇 분 만에 체험 가능
- 장기 사용: VPS 또는 Fly.io를 선택하고, systemd나 컨테이너 오케스트레이션과 결합하여 서비스가 지속적으로 온라인 상태 유지
- 멀티 플랫폼 관리: Gateway 배포 후 휴대폰에 iOS/Android 컴패니언 앱을 설치하여 실행 상태를 수시로 확인
- Windows 사용자: 네이티브 Windows에서 직접 Gateway를 실행하지 말고, WSL2를 사용하면 많은 호환성 문제를 방지 가능
- Bun 사용 금지: 어떤 플랫폼에서든 Gateway 실행에는 Bun이 아닌 Node.js를 사용
OpenClaw의 크로스 플랫폼 특성을 활용하여 자신의 요구에 맞는 배포 방식을 유연하게 선택할 수 있습니다. 라즈베리 파이에서 클라우드 서버까지, 개인 노트북에서 엔터프라이즈 클러스터까지, 항상 적합한 방안이 있습니다.