맥에서 OpenClaw 설치 및 설정 가이드: 나만의 AI 어시스턴트 셀프호스팅하기

클라우드 AI 서비스는 편리하지만 데이터가 외부 서버를 거칩니다. 민감한 업무 대화를 AI에게 맡기고 싶은데, 데이터 유출이 걱정되는 상황. 내 Mac에서 직접 AI 어시스턴트를 돌릴 수 있다면? OpenClaw은 바로 그 문제를 해결합니다.

이 글에서는 오픈소스 셀프호스팅 AI 어시스턴트 OpenClaw을 macOS에 설치하고 설정하는 방법을 단계별로 안내합니다. WhatsApp, Telegram, Slack 등 다양한 메시징 채널과 연동하고, Voice Wake로 “Hey Molty” 한 마디면 대화를 시작할 수 있습니다.

OpenClaw이란?

OpenClaw ↗은 로컬에서 실행되는 오픈소스 AI 어시스턴트/에이전트 프로젝트입니다. MIT 라이선스로 공개되어 있으며, GitHub 스타 18만 개 이상을 기록하고 있습니다.

탄생 배경

OpenClaw은 오스트리아 개발자 Peter Steinberger(PSPDFKit 창업자)가 2025년 11월에 시작한 주말 프로젝트에서 출발했습니다. 처음에는 “WhatsApp Relay”라는 이름으로, WhatsApp 메시지를 AI에게 전달하는 단순한 릴레이였지만, 커뮤니티의 폭발적인 관심을 받으며 본격적인 AI 에이전트 플랫폼으로 성장했습니다.

이름도 여러 차례 바뀌었습니다. WhatsApp Relay → Clawd → Clawdbot → Moltbot → OpenClaw. Anthropic의 상표권 우려(Claude와 발음이 유사)로 이름을 변경해야 했고, “Moltbot”은 랍스터가 탈피(molt)하는 것에서 착안했지만 3일 만에 다시 변경되었습니다. 최종적으로 오픈소스 + 랍스터의 집게발(claw)을 결합한 “OpenClaw”으로 확정되었습니다.

이름 변경 과정에서 흥미로운 에피소드도 있었습니다. X(Twitter) 핸들이 10초 만에 핸들 스나이퍼에게 탈취되었고, 가짜 $CLAWD 암호화폐가 시가총액 $1,600만까지 올랐다가 폭락하는 사건이 벌어지기도 했습니다.

핵심 기능

프라이버시를 최우선으로 설계되었습니다. 모든 데이터는 로컬에 저장되고, AI API 호출만 외부로 나갑니다.

시스템 요구사항

설치 전에 내 Mac이 조건을 충족하는지 확인합니다.

Node.js가 설치되어 있지 않다면 Node.js 공식 사이트 ↗에서 LTS 버전을 다운로드하거나, brew install node로 설치할 수 있습니다.

Node.js 버전을 확인합니다.

node --version
# v22.x.x 이상이어야 합니다

설치 방법

OpenClaw은 네 가지 방법으로 설치할 수 있습니다. 상황에 맞는 방법을 선택하세요.

방법 1: 인스톨러 스크립트 (권장)

가장 간단한 방법입니다. 한 줄로 설치가 완료됩니다.

curl -fsSL https://openclaw.ai/install.sh | bash

스크립트가 Node.js 버전 확인, 패키지 설치, Gateway 데몬 등록까지 자동으로 처리합니다.

방법 2: npm 글로벌 설치

Node.js 환경이 이미 갖춰져 있다면 npm으로 직접 설치할 수 있습니다.

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

onboard 명령은 대화형 설정 마법사를 실행하고, --install-daemon 옵션으로 macOS launchd 서비스를 등록합니다.

방법 3: Homebrew

Homebrew로도 설치할 수 있습니다. GUI 앱(메뉴바 포함)과 CLI 전용 중 선택 가능합니다.

GUI 앱 설치 (메뉴바 앱, Voice Wake, Gateway 상태 확인 포함):

brew install --cask openclaw

CLI 전용 설치:

brew install openclaw-cli

GUI 앱은 macOS 15 Sequoia 이상이 필요합니다. macOS 14 Sonoma에서는 CLI 전용 설치를 사용하세요.

방법 4: 소스 빌드

최신 개발 버전을 사용하거나 코드를 수정하고 싶다면 소스에서 빌드합니다.

# Xcode CLI Tools 설치 (없는 경우)
xcode-select --install

# 소스 클론 및 빌드
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build
pnpm build

# 온보딩 + 데몬 설치
pnpm openclaw onboard --install-daemon

소스 빌드는 TypeScript 모노레포(pnpm workspaces) 구조이므로 pnpm이 필요합니다.

설치 확인

어떤 방법으로 설치했든 다음 명령으로 정상 설치를 확인합니다.

# 버전 확인
openclaw --version

# 설정 진단
openclaw doctor

# Gateway 상태 확인
openclaw status

openclaw doctor는 Node.js 버전, 설정 파일, API 키, Gateway 연결 등을 종합적으로 진단해 줍니다. 문제가 있다면 해결 방법도 함께 안내합니다.

초기 설정

온보딩 마법사

설치 후 처음 실행하면 대화형 온보딩 마법사가 시작됩니다. 이미 onboard를 실행했다면 이 과정은 건너뛸 수 있습니다.

openclaw onboard

온보딩 과정에서 설정하는 항목:

1. AI 모델 선택 — Anthropic Claude(추천), OpenAI ChatGPT, Grok, Ollama 등
2. API 키 입력 — 선택한 모델의 API 키 (예: sk-ant-...)
3. 메시징 채널 연동 — WhatsApp, Telegram, Slack 등 원하는 채널
4. Gateway 데몬 등록 — 백그라운드 서비스 자동 시작 설정

API 키 설정

AI 모델을 사용하려면 API 키가 필요합니다. API 키는 ~/.openclaw/.env 파일에 저장됩니다.

# Anthropic Claude 사용 시
ANTHROPIC_API_KEY=sk-ant-your-key-here

# OpenAI 사용 시
OPENAI_API_KEY=sk-your-key-here

온보딩 마법사에서 입력했다면 자동으로 저장됩니다. 나중에 변경하려면 직접 편집하거나 CLI 명령을 사용합니다.

openclaw config set anthropicApiKey sk-ant-your-key-here

웹 대시보드

설정이 완료되면 웹 대시보드를 열어 봅니다.

openclaw dashboard

브라우저에서 http://127.0.0.1:18789이 열리며, 채팅, 설정, 로그를 웹 UI에서 관리할 수 있습니다.

설정 파일 구조

OpenClaw의 모든 설정은 ~/.openclaw/ 디렉토리에 저장됩니다.

디렉토리 구조

~/.openclaw/
├── openclaw.json    # 메인 설정 파일 (JSON5)
├── .env             # API 키
└── workspace/       # 워크스페이스 데이터

메인 설정 파일

openclaw.json은 JSON5 형식으로 주석과 trailing comma를 지원합니다. 핫 리로드가 지원되어 파일을 수정하면 즉시 반영됩니다.

주요 설정 섹션

설정 변경 방법

설정을 변경하는 방법은 다섯 가지입니다.

# 1. 대화형 마법사
openclaw configure

# 2. CLI 명령
openclaw config get gateway.port
openclaw config set gateway.port 18790

# 3. 웹 UI
openclaw dashboard  # Config 탭에서 변경

# 4. 직접 편집 (핫 리로드)
vim ~/.openclaw/openclaw.json

환경 변수

설정 파일 내에서 ${VAR_NAME} 문법으로 환경 변수를 참조할 수 있습니다. 홈 디렉토리나 상태 디렉토리 경로도 환경 변수로 변경 가능합니다.

메뉴바 앱과 Voice Wake

Homebrew로 GUI 앱(brew install --cask openclaw)을 설치했다면 macOS 전용 기능을 활용할 수 있습니다.

메뉴바 앱

메뉴바에 랍스터 아이콘이 나타납니다. 아이콘 상태로 현재 동작을 확인할 수 있습니다.

메뉴바 앱에서 할 수 있는 작업:

• 원클릭으로 채팅 패널 또는 Canvas 열기
• Gateway 연결 상태 확인
• Voice Wake 켜기/끄기
• 설정 화면 바로가기

Voice Wake 설정

“Hey Molty”라고 말하면 OpenClaw이 활성화됩니다. 음성 처리는 로컬 디바이스에서 이루어지며, 클라우드로 전송되지 않습니다.

설정 방법:

1. OpenClaw.app → Settings → Voice Wake 탭
2. Voice Wake 토글 활성화
3. 기본 웨이크워드: “Hey Molty”

Push-to-Talk: 웨이크워드 대신 Cmd+Fn 키를 홀드하여 음성 입력을 시작할 수도 있습니다.

macOS 권한 설정

Voice Wake와 메뉴바 앱 기능을 사용하려면 macOS 시스템 권한이 필요합니다. 처음 실행 시 권한 요청 팝업이 나타납니다.

시스템 설정 → 개인정보 보호 및 보안에서 각 항목에 OpenClaw.app이 활성화되어 있는지 확인하세요.

Gateway 데몬 관리

OpenClaw의 Gateway는 백그라운드에서 실행되는 서버입니다. macOS launchd를 통해 로그인 시 자동으로 시작됩니다.

기본 관리 명령

# 상태 확인
openclaw status
openclaw gateway status

# 재시작
openclaw gateway restart

# 로그 확인
openclaw logs gateway

포그라운드 모드

디버깅이 필요할 때는 포그라운드 모드로 실행하여 실시간 로그를 확인할 수 있습니다.

openclaw gateway --port 18789

launchd 서비스 확인

Gateway 서비스는 ~/Library/LaunchAgents/com.openclaw.gateway.plist에 등록됩니다.

# launchd에서 서비스 상태 확인
launchctl list | grep openclaw

트러블슈팅

흔한 문제와 해결법

종합 진단

문제가 발생하면 가장 먼저 openclaw doctor를 실행하세요.

openclaw doctor

Node.js 버전, 설정 파일 유효성, API 키, Gateway 연결 상태를 종합 진단하고, 문제가 있으면 해결 방법을 안내해 줍니다.

포트 충돌 해결

기본 포트(18789)가 이미 사용 중이라면 다른 포트로 변경합니다.

# 포트 사용 중인 프로세스 확인
lsof -i :18789

# 포트 변경
openclaw config set gateway.port 18790
openclaw gateway restart

마무리

이 글에서 다룬 내용을 정리합니다.

1. OpenClaw 소개 — 오픈소스 셀프호스팅 AI 어시스턴트, MIT 라이선스
2. 설치 — 인스톨러 스크립트, npm, Homebrew, 소스 빌드 네 가지 방법
3. 초기 설정 — 온보딩 마법사로 AI 모델과 채널 연동
4. 설정 파일 — ~/.openclaw/openclaw.json (JSON5, 핫 리로드)
5. 메뉴바 앱 — 랍스터 아이콘, Voice Wake, Push-to-Talk
6. Gateway 관리 — launchd 데몬, 포그라운드 디버깅

OpenClaw은 거의 매일 새 릴리스가 나올 정도로 활발하게 개발되고 있습니다. 셀프호스팅 AI 어시스턴트에 관심이 있다면, 로컬에서 직접 실행해 보는 것을 추천합니다. 데이터는 내 Mac에 남기면서 Claude, ChatGPT 등 원하는 AI 모델을 자유롭게 연동할 수 있습니다.

참고 자료

공식 자료

• OpenClaw GitHub ↗
• OpenClaw 공식 문서 ↗
• 설치 가이드 ↗
• 설정 레퍼런스 ↗
• 릴리스 노트 ↗

참고 가이드

• Cult of Mac — OpenClaw 설치 가이드 ↗
• Snaplama — Voice Wake 설정 가이드 ↗
• EastonDev — OpenClaw 설정 가이드 ↗

관련 프로젝트

• NanoClaw ↗ — TypeScript 경량판 (~500줄), Apple Containers 기반 샌드박싱
• IronClaw ↗ — Rust 재구현, WASM 샌드박스
• OpenRouter 연동 가이드 ↗