2026년 OpenClaw 설치 방식은 다양합니다: 원클릭 스크립트, npm 전역 설치, Docker, 소스 코드 컴파일이 병존하지만, 백신 차단, 포트 충돌, 메모리 부족, API Key 설정 오류 등의 문제로 인해 많은 엔지니어가 첫 단계에서 막히게 됩니다. 본 문서는 운영 체제별 대조 설치 단계, 고빈도 오류 수정 명령어를 제공하며, 사이트 내 systemd/Docker/보안 강화 문서와의 경계를 설명하여 완전한 학습 경로를 형성하도록 돕습니다.
OpenClaw은 2026년 재단 체제 전환 후 설치 방식이 더욱 다양해졌습니다. 다음은 4가지 주요 방식의 비교표로, 올바른 경로를 빠르게 선택하는 데 도움이 됩니다:
| 방식 | 적용 시나리오 | 장점 | 단점 |
|---|---|---|---|
| 원클릭 스크립트 | Windows 사용자, 초보자 빠른 시작 | 명령줄 경험 불필요, 환경 자동 구성 | 폐쇄형 바이너리, 감사 불가; 백신 차단 당하기 쉬움 |
| npm 전역 | Node.js에 익숙한 개발자 | 투명성, 감사 가능, 업그레이드 용이 | daemon/systemd 수동 구성 필요 |
| Docker | 프로덕션 환경, 격리 필요 | 환경 격리, 롤백 용이, CI 통합 가능 | Docker 기초 지식 필요; 데스크톱 자동화 제한적 |
| 소스 코드 컴파일 | 기여자, 심층 커스터마이징 | 완전 제어, 소스 코드 수정 가능 | 소요 시간 길음, 의존성 복잡, 프로덕션 비추천 |
최초 설치하며 빠르게 실행하려는 엔지니어에게는 npm 전역 설치를 권장합니다(투명성이 높고 문제 해결이 용이함). Windows 사용자가 권한/환경 문제를 겪는 경우 임시로 원클릭 스크립트를 사용할 수 있으나, 프로덕션 환경에서는 npm 또는 Docker로 마이그레이션하는 것을 권장합니다.
Windows는 OpenClaw 설치 오류가 가장 빈번하게 발생하는 플랫폼으로, 주로 백신 소프트웨어 오탐 및 경로 내 한글/공백 때문입니다. 다음은 검증된 6단계 프로세스입니다:
백신 소프트웨어 완전 종료: 360, 텐센트 PC 매니저, 휘루이(火绒), Windows Defender 실시간 보호를 포함합니다. OpenClaw은 시스템 하위 수준 권한을 호출해야 하므로 위험 프로그램으로 오인되기 쉽습니다.
압축 해제 경로 규범화: WinRAR/7-Zip을 사용하여 순수 영문, 공백 없음, 특수 기호 없는 경로(예: D:\OpenClaw)에 압축 해제합니다. 한글, 공백, ! @ # 등의 문자를 엄격히 금지합니다.
초기화 시작: 빨간색 랍스터 아이콘을 더블 클릭하고 「Gateway 온라인」 프롬프트를 기다립니다. 최초 로딩에는 1~3분이 소요되며, 이후 시작은 더 빨라집니다.
Gateway가 계속 오프라인인 경우: 백신이 종료되었는지 확인 → 「서비스 재시작」 클릭 → 소프트웨어 재시작. 그래도 오프라인일 경우 %LOCALAPPDATA%\OpenClaw\Logs의 최신 로그를 확인하십시오.
openclaw doctor 실행: 내장 터미널 또는 PowerShell을 열고 openclaw doctor를 실행하여 구성 완전성, 포트 점유 여부, API Key 유효성을 확인합니다.
API Key 구성: 설정 인터페이스에서 최소 하나의 모델 API Key(OPENAI_API_KEY 또는 ANTHROPIC_API_KEY)를 입력하지 않으면 Gateway 시작 후 즉시 종료됩니다.
주의: 원클릭 스크립트(.exe)는 폐쇄형 바이너리입니다. 2026년 3월 공신부 통보 이후, 더 나은 보안 통제성을 위해 npm 또는 Docker 설치 방식으로 마이그레이션할 것을 권장합니다. 후속 조치를 위해 사이트 내 OpenClaw Gateway 보안 강화 문서를 참고하십시오.
macOS와 Linux의 설치는 Windows보다 투명하지만, TCC(Transparency, Consent, and Control) 및 방화벽 규칙이 일반적인 병목 지점입니다:
# macOS: brew를 사용한 설치 (권장) brew install openclaw # 최초 실행, onboard 마법사 완료 openclaw onboard # Gateway 상태 확인 openclaw status # Gateway가 준비되지 않은 경우, 로그 확인 openclaw logs --follow # Linux (Ubuntu/Debian): npm 전역 설치 sudo npm install -g openclaw # systemd 서비스 구성 (프로덕션 환경) openclaw onboard --platform linux sudo systemctl enable openclaw-gateway sudo systemctl start openclaw-gateway
macOS에서 「연락처/파일 접근 불가」 등의 권한 팝업이 발생하면, 「시스템 설정 → 개인정보 보호 및 보안」에서 OpenClaw을 수동으로 허용해야 합니다. Linux에서 Docker를 사용하는 경우, Compose 및 볼륨 영속성 구성을 위해 사이트 내 OpenClaw Docker 프로덕션 배포 문서를 참고하십시오.
다음은 2026년 1분기 통계 기준 OpenClaw 최고 빈도 6가지 오류 및 수정 방안입니다:
| 오류 | 발생률 | 근본 원인 | 수정 명령어/조치 |
|---|---|---|---|
| Gateway Exited(1) | 60% | .env 파일 누락 또는 API Key 무효 | ~/.openclaw/.env 확인, KEY에 불필요한 공백 없는지 확인 |
| 포트 18789 충돌 | 20% | Node.js 프로젝트 또는 Nginx 점유 | lsof -i :18789로 프로세스 확인, docker-compose.yml 매핑 변경 |
| 메모리 부족 OOM | 15% | 1C1G 최저가 서버 | free -h로 확인, swap 추가: sudo fallocate -l 4G /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile |
| API 429 Too Many Requests | 10% | 요청 빈도 초과 | modelRouting 계층 라우팅 구성 또는 할당량 증액 신청 |
| Anthropic Key 정책 변경 | 신규 발생 | 2026.4부터 결제 수단 바인딩 필수 | Anthropic 콘솔에서 신용카드 바인딩 또는 타 모델 제공업체 사용 |
| Docker 이미지 풀 타임아웃 | 중국 내 빈번 | 국내 미러 가속 없음 | /etc/docker/daemon.json에 국내 미러 가속기 구성 |
팁: 드문 오류가 발생하면 먼저 openclaw doctor와 openclaw logs --follow를 실행하십시오. 80%의 문제는 로그에서 명확한 근본 원인을 찾을 수 있습니다. 나머지 20%는 사이트 내 OpenClaw Gateway not ready 트러블슈팅 매뉴얼을 참고하십시오.
lsof -i :18789와 lsof -i :3000을 실행하여 포트 가용성을 확인하거나, 구성에서 명시적으로 대체 포트를 지정하십시오..env에 여러 모델 제공업체(예: OpenAI, 국내 모델)를 fallback으로 구성하여 단일 장애점을 피하는 것이 좋습니다.또한 대안 방식의 한계를 이해하는 것이 중요합니다. 원클릭 스크립트는 폐쇄형 바이너리로 보안 감사가 불가능하며, 순수 Docker 방식은 macOS 데스크톱 자동화 기능에 제약이 있고, 직접 systemd 구성 시 초기 학습 곡선이 가파릅니다. 장기적인 관점에서 설치 투명성, 운영 비용 및 안정성을 종합적으로 고려할 때, 전문적인 관리 환경을 갖춘 대안을 선택하는 것이 더 효율적입니다.
NodeMini의 원격 Mac 클라우드 렌탈 + OpenClaw 자체 구축 Gateway는 이러한 대안 방식의 한계를 보완하는 최적의 솔루션입니다. 전용 macOS 환경의 툴체인 완전성을 확보하면서도 Linux VPS의 운영 관리 습관을 유지할 수 있습니다.
백신 소프트웨어 및 백그라운드 프로세스를 완전히 종료 → 격리 영역에 들어가 OpenClaw 관련 파일 복원 → 배포 패키지 다시 압축 해제 → 설치 프로그램 실행. 이후 더 나은 보안 통제성을 위해 npm 또는 Docker 설치 방식으로 마이그레이션할 것을 권장합니다.
순서대로 실행하십시오: openclaw status → openclaw doctor → openclaw logs --follow로 마지막 50줄 로그 확인. API Key 유효성, 모델 제공업체 접근 가능성, 메모리 충분성을 중점 확인하십시오. 상세 트러블슈팅 단계는 Gateway not ready 트러블슈팅 매뉴얼을 참고하십시오.
Gateway는 로컬 또는 Linux VPS에 배포하고, 원격 Mac은 SSH를 통해 실행 노드로 접속합니다. 일반적인 토폴로지: Gateway(Linux VPS) + 다수의 원격 Mac(독점 노드)이 SSH 터널을 통해 macOS 전용 작업을 실행합니다. 더 많은 아키텍처 세부사항은 도움말 센터의 「OpenClaw + 원격 Mac」 챕터를 확인하십시오.