OpenClaw는 AI agent가 Telegram이나 WhatsApp 같은 앱에 연결해 메시지 전송이나 작업 처리 등의 동작을 수행할 수 있게 해 주는 로컬 도구입니다. 절차를 이해하면 설정은 어렵지 않습니다. 이 가이드에서는 macOS, Linux, Windows에서의 설치 방법을 다룹니다.
OpenClaw 설정 옵션 한눈에 보기
필요에 맞는 설정 방식을 선택하세요. OpenClaw를 로컬에서 실행하면 모든 것이 내 컴퓨터 안에 유지되며, npm 같은 종속성을 설치하거나 자동화 스크립트를 사용해야 합니다. 설정 과정을 건너뛰고 싶다면 Kimi Claw 같은 완전 호스팅 플랫폼이 환경을 대신 관리해 주므로 바로 시작할 수 있습니다.
| macOS / Linux | Windows | |
|---|---|---|
| 로컬에서 실행 | 한 줄 Terminal 명령 | 한 줄 PowerShell 명령 |
| npm으로 설치 | npm으로 설치 | |
| Homebrew로 설치 | WSL2로 설치 | |
| 온라인에서 실행 | 클라우드 기반 솔루션(예: Kimi Claw) | 클라우드 기반 솔루션(예: Kimi Claw) |
macOS와 Linux에 OpenClaw 설치하기
macOS와 Linux는 같은 설치 프로그램과 명령을 사용합니다. 별도 표시가 없는 한 아래 안내는 두 시스템 모두에 적용됩니다.
아래는 빠른 설정 가이드입니다. 스크린샷이 포함된 전체 단계별 안내는 macOS에 OpenClaw 설치하기를 참고하세요.
방법 1: 한 줄 설치 스크립트 사용
1단계: Terminal에서 설치 스크립트 실행
공식 설치 스크립트를 실행해 OpenClaw를 설정하세요. 이 스크립트는 Node.js 22 이상이 설치되어 있는지 확인합니다. 없거나 버전이 오래된 경우 Node.js 24가 자동으로 설치됩니다. 이어서 OpenClaw CLI를 설치하고 온보딩 마법사를 시작합니다.
2단계: 온보딩 마법사 완료
온보딩 마법사의 안내에 따라 모델 제공업체 선택(예: Kimi API), API 키 입력, 채널 선택, 기본 설정 구성 등 agent 환경을 설정하세요.
3단계: 설치 확인
다음 명령을 실행해 OpenClaw 버전을 확인하세요.
4단계: gateway 확인 및 설정 완료
다음 명령을 실행해 OpenClaw gateway가 활성 상태인지 확인하세요.
설치 프로그램은 macOS에서는 LaunchAgent, Linux에서는 systemd 서비스도 등록하므로 OpenClaw가 백그라운드에서 계속 실행됩니다. 모든 설정이 끝나면 agent를 바로 사용할 수 있습니다. 필요에 따라 채팅을 시작하거나, 도구를 연결하거나, workflow를 구성하세요.
방법 2: Homebrew로 설치
1단계: Node.js 설치 또는 업그레이드
Terminal에서 다음 명령을 실행해 Homebrew로 Node.js를 설치하세요. 이미 Node.js가 설치되어 있다면, 대신 업그레이드 명령을 실행해 최신 버전을 사용 중인지 확인하세요.
2단계: OpenClaw CLI 설치
다음 명령을 실행해 OpenClaw CLI를 전역으로 설치하세요.
3단계: 온보딩 실행 및 daemon 설정
다음 명령을 실행해 온보딩 마법사를 시작하고 백그라운드 daemon을 등록하세요. 마법사의 안내에 따라 모델 제공업체 선택(예: Kimi API), API 키 입력, 메시징 채널 연결 등 agent 환경을 구성하세요. 설정이 완료되면 agent를 사용할 준비가 끝납니다. 필요에 따라 채팅을 시작하거나, 도구를 연결하거나, workflow를 구성할 수 있습니다.
방법 3: npm으로 설치
1단계: 런타임 버전 확인
다음 명령을 실행해 시스템에 Node.js 22.14 이상이 설치되어 있는지 확인하세요. 버전이 최신 상태라면 설치를 진행할 수 있습니다.
2단계: OpenClaw CLI 설치
다음 명령을 실행해 OpenClaw CLI를 전역으로 설치하세요.
3단계: 온보딩 실행 및 지속 실행 활성화
다음 명령을 실행해 온보딩 마법사를 시작하고 백그라운드 daemon을 등록하세요. 마법사의 안내에 따라 모델 제공업체 선택(예: Kimi API), API 키 입력, 메시징 채널 선택 등 agent 환경을 구성하세요. 설정이 완료되면 agent가 준비됩니다. 필요에 따라 agent와 상호작용을 시작하거나, 도구를 연결하거나, workflow를 만들 수 있습니다.
플랫폼 참고: OpenClaw는 Intel 및 Apple Silicon Mac을 모두 지원합니다. Gatekeeper 때문에 설치가 차단되면 시스템 설정의 개인정보 보호 및 보안에서 허용할 수 있습니다.
Windows에 OpenClaw 설치하기
Windows에서 OpenClaw를 설치하는 주요 방법은 세 가지입니다. 빠른 네이티브 설정을 위한 PowerShell 설치 프로그램, 완전한 Linux 환경을 위한 WSL2, 수동 설치를 위한 npm입니다.
아래는 빠른 설정 가이드입니다. 스크린샷이 포함된 전체 단계별 안내는 Windows에 OpenClaw 설치하기를 참고하세요.
방법 1: PowerShell 설치 프로그램 사용(네이티브 Windows)
1단계: PowerShell에서 설치 스크립트 실행
PowerShell을 관리자 권한으로 열고 공식 한 줄 스크립트를 실행해 OpenClaw를 설치하세요.
2단계: 온보딩 마법사 완료
온보딩 단계의 안내에 따라 모델 제공업체 선택(예: Kimi API), API 키 입력, 메시징 채널 선택 등 agent 환경을 구성하세요.
3단계: 설치 확인
다음 명령을 실행해 OpenClaw가 올바르게 설치되었고 gateway가 활성 상태인지 확인하세요.
4단계: agent 사용 시작
설정이 완료되면 agent가 준비됩니다. 필요에 따라 agent와 상호작용을 시작하거나, 도구를 연결하거나, workflow를 구성할 수 있습니다.
방법 2: WSL2로 설치
1단계: Linux 환경 설정
PowerShell을 관리자 권한으로 열고 다음 명령을 실행해 WSL2를 활성화하고 초기화하세요.
2단계: Linux에서 설치 프로그램 실행
Linux 터미널을 열고 표준 설치 스크립트를 실행해 OpenClaw를 설치하세요.
3단계: 온보딩 마법사 완료
온보딩 단계의 안내에 따라 모델 제공업체 선택(예: Kimi API), API 키 입력, 메시징 채널 선택 등 agent 환경을 구성하세요.
설정이 완료되면 agent가 준비됩니다. 필요에 따라 agent와 상호작용을 시작하거나, 도구를 연결하거나, workflow를 구성할 수 있습니다.
방법 3: Windows에서 npm으로 설치
1단계: Node.js 버전 확인
다음 명령을 실행해 Node.js가 설치되어 있고 최신 상태인지 확인하세요.
2단계: OpenClaw CLI 설치
다음 명령을 실행해 OpenClaw CLI를 전역으로 설치하세요.
3단계: 온보딩 실행 및 지속 실행 활성화
다음 명령을 실행해 온보딩 마법사를 시작하고 백그라운드 daemon을 등록하세요.
온보딩 단계의 안내에 따라 모델 제공업체 선택(예: Kimi API), API 키 입력, 메시징 채널 선택 등 agent 환경을 구성하세요.
설정이 완료되면 agent가 준비됩니다. 필요에 따라 agent와 상호작용을 시작하거나, 도구를 연결하거나, workflow를 구성할 수 있습니다.
Kimi Claw로 OpenClaw 온라인 실행하기
위 방법을 사용하려면 터미널, 지원되는 Node.js 버전, 계속 켜져 있는 머신이 필요합니다. Kimi Claw는 완전 호스팅 옵션을 제공하므로, 로컬 환경을 설치하거나 유지관리하지 않고도 OpenClaw를 실행할 수 있습니다.
1단계: Kimi Claw 열기 및 인스턴스 생성
Kimi Claw 페이지로 이동해 Create를 클릭하면 시작됩니다.
2단계: 배포 확인
팝업 창에서 배포를 확인하세요. Kimi Claw가 gateway와 workspace를 포함한 OpenClaw 환경을 자동으로 설정하므로, 로컬 구성은 필요하지 않습니다.
3단계: workspace 사용 시작
배포가 완료되면 대시보드에서 workspace가 열립니다. 브라우저에서 바로 agent와 상호작용하고, skill을 설정하고, 예약 작업을 구성하며, 파일을 관리할 수 있습니다.
Kimi Claw 주요 기능
Cloud hosting: Kimi Claw가 클라우드에서 gateway를 실행하므로, 로컬 머신이 오프라인이어도 agent를 계속 사용할 수 있습니다.
자동 유지관리: 업데이트와 패치가 백그라운드에서 처리되며, 수동 설정이나 재시작이 필요하지 않습니다.
내장 기능: 작업 예약, 영구 저장소, 프롬프트 기반 동적 skill 로딩을 포함하며, 여러 기기에서 끊김 없이 접근할 수 있습니다.
OpenClaw 설치 시 흔한 오류 해결
OpenClaw 설치 문제는 대부분 PATH 설정, 누락된 의존성, 포트 충돌 같은 몇 가지 범주에 속합니다. 아래 섹션에서는 macOS, Windows, Linux에서 자주 발생하는 문제를 빠르게 찾아 해결하는 방법을 안내합니다.
설치 후 "openclaw: command not found"가 표시됨
OpenClaw가 시스템 PATH에 없습니다.
해결: npm 전역 bin 디렉터리를 PATH에 추가하세요.
그런 다음 셸을 다시 로드하거나(예: source ~/.zshrc) 터미널을 재시작하세요. Windows에서는 해당 경로를 환경 변수에 추가한 뒤 PowerShell을 재시작하세요.
macOS에서 Sharp 빌드 오류
일반적으로 전역으로 설치된 libvips가 Sharp 라이브러리와 충돌할 때 발생합니다.
해결: 이 환경 변수와 함께 설치 명령을 실행하세요.
node-gyp 오류가 표시되면 Xcode Command Line Tools를 설치하세요.
재부팅 후 OpenClaw가 시작되지 않음
온보딩 중 백그라운드 daemon이 설치되지 않았습니다.
해결: daemon 플래그를 사용해 온보딩을 다시 실행하세요.
그런 다음 서비스를 확인하세요.
Gateway가 응답하지 않거나 "0 tokens used"가 표시됨
gateway 프로세스가 중지되었거나 API 인증에 실패했을 수 있습니다.
해결: gateway를 재시작하세요.
상태 검사를 실행하세요.
디버깅 로그 확인:
또한 API 키가 유효한지 확인하세요.
포트 18789가 이미 사용 중
다른 프로세스가 OpenClaw gateway 포트를 사용하고 있습니다.
해결: 충돌하는 프로세스를 찾아 중지하세요.
그런 다음 gateway를 재시작하세요.
EACCES 권한 오류
일반적으로 npm 전역 디렉터리에 올바른 권한이 없다는 뜻입니다.
해결: 디렉터리 소유권을 업데이트하세요.
Windows에서는 PowerShell을 관리자 권한으로 실행하거나 사용자 지정 npm prefix를 설정하세요.
Docker 설정에서는 볼륨 권한을 수정하세요.
"spawn git ENOENT" 오류
Git이 설치되어 있지 않거나 PATH에서 사용할 수 없습니다.
해결: git-scm.com에서 Git을 설치하고 터미널을 재시작한 뒤 설치를 다시 시도하세요.
WSL2 systemd가 작동하지 않음
WSL 구성에서 systemd가 활성화되어 있지 않습니다.
해결:
/etc/wsl.conf를 편집하고 다음을 추가하세요.
그런 다음 WSL을 재시작하세요.
Linux 터미널을 다시 열고 확인하세요.
VPS에서 npm 설치 중 메모리 부족
메모리가 적은 VPS 인스턴스에서는 패키지 설치 중 실패할 수 있습니다.
해결: swap 파일을 생성하세요.
그런 다음 설치를 다시 실행하세요.
메시징 플랫폼 연결 시 "Access not configured" 표시
계정이 OpenClaw에서 승인되지 않았습니다.
해결: 페어링 코드를 사용해 계정을 승인하세요.
또한 bot 자격 증명(token, webhook, 권한)이 올바르게 구성되어 있는지 확인하세요.
결론
OpenClaw는 macOS, Linux, Windows 어디서나 간단하게 설치할 수 있습니다. 환경에 따라 한 줄 스크립트, PowerShell, WSL2, npm 중 원하는 방식을 사용할 수 있습니다. 온보딩 마법사가 모델 선택, API 구성, 메시징 채널 설정을 안내합니다. 로컬 환경을 직접 관리하고 싶지 않다면, Kimi Claw의 완전 호스팅 옵션으로 클라우드에서 OpenClaw를 바로 실행할 수 있습니다.
자주 묻는 질문
node --version을 실행해 버전이 최소 요구 사항을 충족하는지 확인하세요.npm install -g openclaw@latest를 실행하세요. 그러면 CLI가 최신 버전으로 업데이트됩니다. 한 줄 설치 프로그램을 다시 실행해도 기존 설치가 자동으로 업그레이드됩니다. OpenClaw는 127.0.0.1:18789의 Control UI를 통한 앱 내 업데이트도 지원합니다. 업데이트 후에는 새 버전을 불러오도록 openclaw gateway restart로 gateway를 재시작하세요.openclaw gateway status를 실행하세요. Windows에서는 systemd가 활성화된 WSL2가 가장 안정적인 상시 실행 환경을 제공합니다. 로컬 서비스를 직접 관리하고 싶지 않다면 Kimi Claw 같은 완전 호스팅 옵션으로 클라우드에서 OpenClaw를 계속 실행할 수 있습니다.