OpenClaw이란?
OpenClaw은 오픈소스 셀프 호스팅 개인 AI 어시스턴트 플랫폼입니다. 자주 사용하는 메신저(WhatsApp, Telegram, Discord, Slack, iMessage 등)와 다양한 AI 모델을 연결해서, 익숙한 채팅 인터페이스에서 바로 AI와 대화할 수 있습니다. GitHub에서 이미 10만 개 이상의 스타를 획득했으며, 커뮤니티도 매우 활발합니다.
나만의 AI 어시스턴트를 갖고 싶지만 특정 플랫폼에 종속되고 싶지 않다면, OpenClaw은 현재 가장 추천할 만한 솔루션 중 하나입니다. 이 글에서는 설치부터 사용 가능한 상태까지의 전체 과정을 단계별로 안내합니다.
시스템 요구사항
시작하기 전에 다음 조건을 충족하는지 확인하세요:
- Node.js 22 이상: OpenClaw은 최신 Node.js 기능에 의존하므로, 22가 최소 버전입니다.
- 운영체제: macOS, Linux 또는 Windows (macOS나 Linux 권장)
- 네트워크 연결: 설치 과정에서 npm 저장소로부터 패키지를 다운로드해야 합니다.
현재 Node.js 버전을 확인하세요:
node -v
버전이 22 미만이라면 nvm을 사용해서 업그레이드하는 것을 권장합니다:
nvm install 22
nvm use 22
아직 nvm을 설치하지 않았다면 nvm 공식 저장소의 안내를 참고하세요. Windows 사용자는 nvm-windows를 이용할 수 있습니다.
npm으로 OpenClaw 설치하기
Node.js 환경이 준비되었다면, npm으로 OpenClaw을 전역 설치합니다:
npm install -g openclaw@latest
설치가 완료되면 정상적으로 설치되었는지 확인합니다:
openclaw --version
버전 번호가 정상적으로 출력되면 설치가 완료된 것입니다.
macOS 사용자는 Homebrew를 통해서도 설치할 수 있습니다:
brew install openclaw
초기 설정 마법사 실행
OpenClaw에는 첫 설정을 빠르게 완료할 수 있는 대화형 onboard 마법사가 내장되어 있습니다. 다음 명령어로 마법사를 시작하세요:
openclaw onboard
마법사는 다음 단계를 순서대로 안내합니다:
- AI 모델 공급자 선택: Anthropic Claude, OpenAI, Ollama(로컬 모델), Gemini, OpenRouter 등을 선택할 수 있습니다. API 키가 아직 없다면 Ollama를 선택하여 로컬에서 모델을 실행할 수 있습니다.
- API 키 설정: 선택한 공급자에 맞는 API 키를 입력합니다.
- 채팅 채널 선택: 연결하고 싶은 채팅 플랫폼(WhatsApp, Telegram 등)을 선택합니다. 처음 설치할 때는 이 단계를 건너뛰고 나중에 설정하는 것을 권장합니다.
- 설정 확인: 마법사가 설정 요약을 표시하고, 확인 후 설정 파일에 저장합니다.
모든 설정 정보는 ~/.config/openclaw/openclaw.json5 파일에 저장됩니다. 이 파일을 직접 편집하여 언제든지 설정을 변경할 수 있습니다.
Gateway 서비스 시작
설정이 완료되면 OpenClaw의 Gateway 서비스를 시작합니다:
openclaw up
Gateway는 기본적으로 18789 포트에서 실행됩니다. 브라우저에서 http://localhost:18789에 접속하여 서비스 상태를 확인할 수 있습니다.
백그라운드에서 서비스를 실행하려면:
openclaw up -d
Dashboard에서 테스트하기
OpenClaw에는 웹 Dashboard가 내장되어 있어, 브라우저에서 직접 AI와 대화하며 설정이 올바른지 테스트할 수 있습니다:
openclaw dashboard
이 명령을 실행하면 자동으로 브라우저가 열리고 Dashboard 화면으로 이동합니다. 대화창에 메시지를 입력해 보세요. 예를 들어 "안녕하세요, 자기소개를 해주세요"라고 입력했을 때 AI의 응답을 받으면, 전체 연결이 정상적으로 완료된 것입니다.
자주 발생하는 문제 해결
문제가 발생하면 OpenClaw에 내장된 진단 도구를 사용하세요:
openclaw doctor
이 명령은 환경 설정, 의존성 버전, API 연결 상태 등을 점검하고, 해결 방법을 안내합니다.
자주 발생하는 문제와 해결 방법:
command not found: openclaw: npm 전역 bin 디렉토리가 PATH에 포함되어 있는지 확인하세요.npm config get prefix로 경로를 확인하고 PATH에 추가하세요.- Node.js 버전이 너무 낮음:
nvm install 22 && nvm use 22로 업그레이드하세요. - API 연결 실패: API 키가 올바른지, 해당 API 엔드포인트에 네트워크 접속이 가능한지 확인하세요.
curl로 직접 테스트할 수 있습니다. - 포트 충돌: 18789 포트가 이미 사용 중이라면, 설정 파일에서
gateway.port값을 변경하세요.
다음 단계
설치가 완료된 후에는 다음과 같은 기능을 탐색해 볼 수 있습니다:
- 더 많은 채팅 플랫폼 연결 (WhatsApp, Telegram, Discord 등)
- 여러 AI 모델 공급자를 설정하고 전환하며 사용
- 커스텀 Skill을 만들어 어시스턴트의 기능 확장
- MCP Server를 설정하여 더 많은 도구 연동
자세한 정보는 OpenClaw을 방문하거나, OpenClaw 공식 문서를 참고하세요. 소스코드와 이슈 트래킹은 OpenClaw GitHub 저장소에서 확인하실 수 있습니다.