Mac에서 OpenClaw(이전 명칭 Clawdbot/Moltbot) 설치 및 실행 방법
OpenClaw는 일상적으로 사용하는 메시징 앱과 AI 코딩 에이전트를 연결해 주는 오픈소스 셀프 호스팅 게이트웨이입니다. 탭, 앱, 인터페이스를 오갈 필요 없이 WhatsApp 또는 Telegram에서 메시지를 보내면 주머니 속에서 바로 AI 기반 응답을 받을 수 있습니다. MIT 라이선스가 적용되며, 사용자의 하드웨어에서 실행되고, 데이터에 대한 완전한 제어권을 유지할 수 있습니다.
이 튜토리얼에서는 사전 요구 사항부터 첫 번째 작동 채팅까지, macOS에서 OpenClaw를 설치하고 실행하는 데 필요한 모든 과정을 안내합니다.
필요한 것
시작하기 전에 다음 항목이 준비되어 있는지 확인하세요.
- macOS(최신 버전이면 모두 가능)
- Node.js 22 이상 — 이미 설치되어 있지 않은 경우 설치 스크립트가 이를 처리하지만, 확인해 두는 것이 좋습니다
- API 키 — OpenClaw 팀은 Anthropic을 권장합니다
- 약 5분의 시간
현재 Node 버전을 확인하려면 Terminal을 열고 다음을 실행하세요.
node --version
v22.x.x 이상이 표시되면 준비가 완료된 것입니다. 그렇지 않아도 걱정하지 마세요 — 설치 프로그램이 처리해 줍니다.
1단계: 설치 스크립트로 OpenClaw 설치(권장)
macOS에서 OpenClaw를 설치하는 가장 빠른 방법은 한 줄짜리 설치 스크립트입니다. 이 스크립트는 Node 감지, CLI 설치, 온보딩 마법사 실행을 모두 한 번에 처리합니다.
Terminal을 열고 다음을 실행하세요.
curl -fsSL https://openclaw.ai/install.sh | bash
이게 전부입니다. 스크립트가 CLI를 다운로드하고, npm을 통해 전역으로 설치한 뒤, 온보딩 마법사를 자동으로 시작합니다.
대안: npm으로 직접 설치
이미 Node 22+가 있고 수동으로 제어하는 것을 선호한다면 npm으로 OpenClaw를 설치할 수 있습니다.
npm install -g openclaw@latest
openclaw onboard --install-daemon
대안: pnpm으로 설치
pnpm을 선호하는 패키지 매니저로 사용한다면:
pnpm add -g openclaw@latest
pnpm approve-builds -g # openclaw, node-llama-cpp, sharp 등을 승인
openclaw onboard --install-daemon
참고: pnpm은 빌드 스크립트가 있는 패키지에 대해 명시적 승인이 필요합니다. 첫 설치 후 "Ignored build scripts" 경고가 표시되면 pnpm approve-builds -g를 실행하고 나열된 패키지를 선택하세요.
문제 해결: sharp 빌드 오류
libvips가 전역으로 설치되어 있고(macOS에서 Homebrew를 통해 흔함) 설치 중 sharp가 실패하는 경우, 사전 빌드된 바이너리를 강제로 사용하세요.
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest
sharp: Please add node-gyp to your dependencies 오류가 표시되면, 빌드 도구(Xcode Command Line Tools + npm install -g node-gyp)를 설치하거나 위의 환경 변수를 사용하세요.
2단계: 온보딩 마법사 실행
설치 스크립트가 자동으로 실행하지 않은 경우, 온보딩 마법사를 수동으로 시작하세요.
openclaw onboard --install-daemon
마법사는 인증, 게이트웨이 설정, 선택적 채널 연결 구성을 단계별로 안내합니다. 또한 OpenClaw를 백그라운드 서비스(데몬)로 설치하므로 Terminal을 닫은 후에도 Gateway가 계속 실행됩니다.
마법사가 구성하는 항목
- 인증 — 로컬 및 원격 클라이언트가 인증해야 하도록 Gateway용 토큰을 생성합니다
- Gateway 설정 — 포트, 바인드 주소, 서비스 설치
- 채널 연결 — WhatsApp, Telegram, Discord 등의 선택적 설정
3단계: Gateway가 실행 중인지 확인
온보딩이 완료되면 Gateway가 작동 중인지 확인하세요.
openclaw gateway status
Gateway가 실행 중이라는 확인 메시지가 표시됩니다. 디버깅이나 빠른 테스트를 위해 포그라운드에서 실행하려면 다음을 사용하세요.
openclaw gateway --port 18789
전체 상태 점검을 위해서는 다음을 실행하세요.
openclaw health
4단계: Control UI(대시보드) 열기
OpenClaw로 채팅을 시작하는 가장 빠른 방법은 브라우저 기반 Control UI를 사용하는 것입니다 — 채널 설정이 필요하지 않습니다.
다음을 실행하세요.
openclaw dashboard
그러면 대시보드 URL이 복사되고, 가능하면 브라우저가 열리며, 링크가 표시됩니다. 기본적으로 Control UI는 다음 위치에서 제공됩니다:
http://127.0.0.1:18789/
대시보드에서 인증을 요청하면 Gateway 구성의 토큰을 붙여넣으세요. 다음 명령으로 가져올 수 있습니다:
openclaw config get gateway.auth.token
보안 참고: Control UI는 관리자 화면입니다 — 채팅, 구성, 실행 승인에 대한 접근 권한을 제공합니다. 공개적으로 노출하지 마세요. localhost, Tailscale Serve 또는 SSH 터널만 사용하세요.
5단계: 채팅 채널 연결(선택 사항)
Control UI를 통해 채팅에 즉시 접근할 수 있지만, OpenClaw의 진정한 강점은 이미 사용하는 앱에서 AI 에이전트에게 메시지를 보내는 것입니다. 지원되는 채널에 대한 간단한 개요는 다음과 같습니다:
| 채널 | 설정 복잡도 | 참고 |
|---|---|---|
| Telegram | 가장 쉬움 | 간단한 bot token |
| 쉬움 | QR 페어링 필요; 디스크에 더 많은 상태 저장 | |
| Discord | 보통 | Bot API + Gateway |
| iMessage | 보통 | BlueBubbles macOS server를 통한 사용 권장 |
| IRC | 낮음 | 클래식 IRC; 채널 + DM |
| Slack | 보통 | Bolt SDK; workspace apps |
| Signal | 보통 | 개인정보 보호 중심; signal-cli 사용 |
여러 채널을 동시에 실행할 수 있습니다 — 원하는 만큼 구성하면 OpenClaw가 채팅별로 메시지를 라우팅합니다.
다음 게시물을 확인하세요: OpenClaw 튜토리얼: 로컬 AI 어시스턴트를 위해 Slack에 연결하기 - Milvus Blog
빠른 예시: WhatsApp 페어링
WhatsApp을 연결하려면 다음을 실행하세요:
openclaw channels login
QR 페어링 흐름을 따르면 WhatsApp에서 직접 AI 에이전트에게 메시지를 보낼 수 있습니다.
6단계: 테스트 메시지 보내기
채널을 구성한 후 CLI에서 테스트 메시지를 보내세요:
openclaw message send --target +15555550123 --message "Hello from OpenClaw"
전화번호를 본인의 번호로 바꾸세요. 모든 것이 올바르게 연결되어 있다면 메시징 앱에 메시지가 도착하는 것을 볼 수 있으며, OpenClaw의 AI 에이전트가 응답할 것입니다.
선택 사항: 소스에서 빌드
기여자 또는 로컬 체크아웃에서 실행하려는 사람을 위한 단계입니다:
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build
pnpm build
CLI를 전역으로 링크하세요:
pnpm link --global
그런 다음 온보딩을 실행하세요:
openclaw onboard --install-daemon
개발 중 hot-reload를 사용하려면 표준 gateway 명령 대신 pnpm gateway:watch를 사용하세요.
선택 사항: macOS 앱 온보딩
OpenClaw는 자체 온보딩 흐름이 있는 네이티브 macOS 앱(메뉴 막대)도 제공합니다. 앱을 사용하는 경우:
- 처음 실행할 때 macOS 보안 경고 승인
- "Find Local Networks" 권한 허용
- Local vs. Remote 선택 — 로컬 전용 Gateway의 경우 "This Mac"을 선택
- 권한 부여 — 사용 사례에 따라 앱이 Automation, Notifications, Accessibility 및 기타 TCC 권한을 요청할 수 있음
- CLI 설치(선택 사항) — 터미널 워크플로가 앱과 함께 작동하도록 앱이 npm을 통해 전역
openclawCLI를 설치할 수 있음 - 온보딩 세션에서 채팅 — 에이전트가 자신을 소개할 수 있도록 앱이 전용 채팅을 엽니다
OpenClaw 문서에서 권장하는 안정적인 워크플로: OpenClaw.app을 설치하고 실행한 뒤, 온보딩 체크리스트를 완료한 다음 openclaw channels login으로 채널을 연결하세요.
구성 기본 사항
OpenClaw는 구성을 ~/.openclaw/openclaw.json에 저장합니다. 기본적으로 발신자별 세션과 함께 RPC 모드에서 번들된 Pi binary를 사용하므로 구성이 필요하지 않습니다.
에이전트에게 메시지를 보낼 수 있는 사람을 제한하려면 allowFrom 규칙을 추가하세요:
{
"channels": {
"whatsapp": {
"allowFrom": ["+15555550123"],
"groups": {
"*": {
"requireMention": true
}
}
}
},
"messages": {
"groupChat": {
"mentionPatterns": ["@openclaw"]
}
}
}
macOS의 주요 파일 위치
| 경로 | 목적 |
|---|---|
~/.openclaw/openclaw.json | 기본 구성 파일 |
~/.openclaw/workspace/ | 스킬, 프롬프트, 메모리 |
~/.openclaw/credentials/ | 채널 자격 증명 |
~/.openclaw/agents/<agentId>/sessions/ | 에이전트 세션 데이터 |
/tmp/openclaw/ | 로그 |
유용한 환경 변수
| 변수 | 목적 |
|---|---|
OPENCLAW_HOME | 내부 경로 확인을 위한 홈 디렉터리 재정의 |
OPENCLAW_STATE_DIR | 상태 디렉터리 재정의 |
OPENCLAW_CONFIG_PATH | 구성 파일 경로 재정의 |
문제 해결: openclaw를 찾을 수 없음
설치 후 셸에서 openclaw 명령을 찾을 수 없다면, 문제는 거의 항상 PATH 항목 누락입니다.
빠른 진단:
node -v
npm -v
npm prefix -g
echo "$PATH"
npm prefix -g의 출력에 /bin을 더한 경로가 $PATH에 없다면, 셸 시작 파일(최신 macOS의 경우 ~/.zshrc)에 추가하세요.
export PATH="$(npm prefix -g)/bin:$PATH"
그런 다음 새 Terminal 창을 열거나 source ~/.zshrc를 실행하세요.
문제 해결: 대시보드의 "Unauthorized" / 1008 오류
Control UI에 unauthorized 오류가 표시되는 경우:
- Gateway에 연결할 수 있는지 확인하세요:
openclaw status - 토큰을 가져오세요:
openclaw config get gateway.auth.token - 대시보드 설정에서 토큰을 auth 필드에 붙여넣고 다시 연결하세요
새 토큰을 생성해야 하는 경우:
openclaw doctor --generate-gateway-token
이제 갖춘 것
이 튜토리얼을 완료하면 다음을 갖추게 됩니다.
- Mac에서 실행 중인 Gateway
- 안전한 액세스를 위해 구성된 인증
- 브라우저 기반 채팅을 위한 Control UI 액세스
- 선택 사항으로, 하나 이상의 연결된 메시징 채널(WhatsApp, Telegram, Discord 등)
이제부터는 다중 에이전트 라우팅, 워크스페이스 격리, 미디어 지원, 그리고 OpenClaw의 모든 기능을 살펴볼 수 있습니다.
리소스
계속 읽기
Why Context Engineering Is Becoming the Full Stack of AI Agents
Discover how context engineering unifies prompts, RAG, and tools to build smarter, production-ready AI agents powered by Milvus.
DeepSeek-VL2: Mixture-of-Experts Vision-Language Models for Advanced Multimodal Understanding
Explore DeepSeek-VL2, the open-source MoE vision-language model. Discover its architecture, efficient training pipeline, and top-tier performance.
Vector Databases vs. Hierarchical Databases
Use a vector database for AI-powered similarity search; use a hierarchical database for organizing data in parent-child relationships with efficient top-down access patterns.