OpenClaw 설치 가이드: 나만의 AI 개인 비서 만들기

WhatsApp, Telegram, Discord 등 일상에서 쓰는 메신저로 AI 비서와 대화할 수 있다면 어떨까요? OpenClaw은 바로 그것을 가능하게 하는 오픈소스 프로젝트입니다.

이 글에서는 OpenClaw을 처음부터 설치하고, 실제로 메신저에서 AI 비서와 대화하는 것까지 단계별로 안내합니다.

AI Assistant Photo by Google DeepMind on Unsplash

OpenClaw이란?

OpenClaw은 개인용 AI 비서 게이트웨이입니다. 핵심 아이디어는 간단합니다:

메신저 (WhatsApp/Telegram/Discord/iMessage)
        │
        ▼
  ┌─────────────────────┐
  │     Gateway         │  ← 하나의 프로세스가 모든 채널 관리
  │  (openclaw gateway) │
  └─────────┬───────────┘
            │
            ▼
      AI Agent (Pi)    ← Claude, GPT 등 AI 모델 연결

주요 특징:

📱 WhatsApp — WhatsApp Web 프로토콜 (Baileys)
✈️ Telegram — Bot API (grammY)
🎮 Discord — Bot API (discord.js)
💬 iMessage — macOS 전용 (imsg CLI)
🧩 Mattermost — 플러그인 지원
🔐 보안 — DM 페어링 기본, 허용 목록 관리
🧠 멀티 에이전트 — 여러 AI 에이전트 동시 운용

공식 문서: docs.openclaw.ai GitHub: github.com/openclaw/openclaw

사전 준비

시스템 요구사항

항목	요구사항
OS	macOS, Linux, Windows (WSL2)
Node.js	22 이상
pnpm	소스 빌드 시에만 필요

Node.js 설치

아직 Node.js가 없다면:

# macOS (Homebrew)
brew install node

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# Windows
# WSL2 설치 후 Ubuntu에서 위 명령 실행

버전 확인:

node -v   # v22.x.x 이상이면 OK
npm -v

Step 1: OpenClaw 설치

방법 A: 원클릭 설치 (추천)

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

Windows (PowerShell):

iwr -useb https://openclaw.ai/install.ps1 | iex

이 스크립트가 npm으로 전역 설치 후 온보딩 위자드를 실행합니다.

방법 B: npm 수동 설치

npm install -g openclaw@latest

pnpm 사용자:

pnpm add -g openclaw@latest
pnpm approve-builds -g   # 빌드 스크립트 승인
pnpm add -g openclaw@latest   # 재실행으로 postinstall 완료

방법 C: 소스에서 빌드 (개발자용)

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build   # UI 빌드 (첫 실행 시 자동으로 의존성 설치)
pnpm build

설치 확인:

openclaw --version

Step 2: 온보딩 위자드 실행

온보딩 위자드가 모든 설정을 안내합니다:

openclaw onboard --install-daemon

위자드에서 설정할 것들:

모드 선택 — Local (내 컴퓨터) vs Remote (원격 서버)
AI 모델/인증 — Anthropic API 키, OpenAI, Claude Code 등
게이트웨이 설정 — 포트, 바인딩, 인증 토큰
채널 설정 — WhatsApp, Telegram, Discord 등
데몬 설치 — 백그라운드 서비스 (launchd/systemd)
스킬 설치 — 추가 기능들

QuickStart vs Advanced

QuickStart — 기본값으로 빠르게 시작 (초보자 추천)
Advanced — 모든 옵션을 세밀하게 조정

AI 모델 인증 (중요!)

Step 3: Gateway 시작

온보딩에서 데몬을 설치했다면 이미 실행 중입니다:

# 상태 확인
openclaw gateway status

# 수동 실행 (포그라운드)
openclaw gateway --port 18789 --verbose

Dashboard (Control UI) 열기

게이트웨이가 실행 중이면 브라우저에서:

http://127.0.0.1:18789/

또는:

openclaw dashboard

이 Control UI에서 채팅, 설정, 세션 관리, 크론 작업 등을 모두 할 수 있습니다.

Step 4: 채널 연결

WhatsApp 연결

openclaw channels login

터미널에 QR 코드가 표시됨
보조 폰의 WhatsApp → 설정 → 연결된 기기 → 기기 연결
QR 코드 스캔
연결 완료!

⚠️ 추천: 별도의 전화번호(서브폰)를 사용하세요. 개인 번호를 연결하면 모든 메시지가 AI 입력이 됩니다.

설정 예시 (~/.openclaw/openclaw.json):

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+821012345678"]
    }
  }
}

Telegram 봇 연결

Telegram에서 @BotFather에게 /newbot 전송
봇 이름과 username 설정
발급받은 토큰을 설정에 입력

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123456:ABC-your-token-here",
      "dmPolicy": "pairing"
    }
  }
}

Discord 봇 연결

Discord Developer Portal → New Application
Bot → Add Bot → 토큰 복사
Privileged Gateway Intents에서 Message Content Intent 활성화
서버에 봇 초대

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN"
    }
  }
}

Step 5: DM 보안 (페어링)

OpenClaw은 기본적으로 모르는 사람의 DM을 차단합니다.

첫 DM을 보내면 페어링 코드가 발급되고, 이를 승인해야 합니다:

# 대기 중인 페어링 요청 확인
openclaw pairing list whatsapp

# 승인
openclaw pairing approve whatsapp <code>

또는 허용 목록으로 사전 설정:

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+821012345678"]
    }
  }
}

Step 6: 워크스페이스 설정

OpenClaw의 AI 비서는 워크스페이스에서 동작합니다:

~/.openclaw/workspace/
├── AGENTS.md       # 에이전트 행동 규칙
├── SOUL.md         # 성격과 말투
├── USER.md         # 사용자 정보
├── IDENTITY.md     # 에이전트 정체성
├── TOOLS.md        # 도구 설정
├── HEARTBEAT.md    # 주기적 작업 정의
└── memory/         # 기억 저장소
    └── 2026-02-03.md

이 파일들을 편집해서 AI 비서의 성격과 동작을 커스터마이즈할 수 있습니다.

Step 7: 동작 확인

# 전체 상태 확인
openclaw status

# 건강 체크
openclaw health

# 보안 감사
openclaw security audit --deep

# 테스트 메시지 보내기
openclaw message send --target +821012345678 --message "Hello from OpenClaw!"

설정 예시: 개인 비서 모드

완벽한 개인 비서 설정 예시:

{
  "logging": { "level": "info" },
  "agent": {
    "model": "anthropic/claude-opus-4-5",
    "workspace": "~/.openclaw/workspace",
    "thinkingDefault": "high",
    "timeoutSeconds": 1800,
    "heartbeat": { "every": "30m" }
  },
  "channels": {
    "whatsapp": {
      "allowFrom": ["+821012345678"],
      "groups": {
        "*": { "requireMention": true }
      }
    }
  },
  "session": {
    "scope": "per-sender",
    "resetTriggers": ["/new", "/reset"],
    "reset": {
      "mode": "daily",
      "atHour": 4,
      "idleMinutes": 10080
    }
  }
}

Heartbeat: 주기적 자동 작업

AI 비서가 주기적으로 (기본 30분) 자동 작업을 실행할 수 있습니다:

{
  "agent": {
    "heartbeat": { "every": "30m" }
  }
}

HEARTBEAT.md에 작업을 정의하면 자동으로 실행:

📧 이메일 확인
📅 캘린더 알림
🌤️ 날씨 체크
📈 주식/공시 모니터링

트러블슈팅

`openclaw` 명령어를 찾을 수 없을 때

# PATH 확인
echo "$PATH"
npm prefix -g

# ~/.zshrc에 추가
export PATH="$(npm prefix -g)/bin:$PATH"

WhatsApp 연결이 끊어질 때

# 재연결
openclaw channels login

# 인증 파일 위치
ls ~/.openclaw/credentials/whatsapp/

Gateway가 시작되지 않을 때

# 진단
openclaw doctor
openclaw status --all

다음 단계

OpenClaw 설치가 완료되면 더 많은 기능을 탐색해보세요:

🖥️ macOS 메뉴바 앱 — 음성 호출 지원
📱 iOS/Android 앱 — 카메라, 위치 연동
⏰ Cron 작업 — 정해진 시간에 자동 실행
🔧 스킬 시스템 — 기능 확장
🌐 원격 접속 — SSH 터널, Tailscale

마무리

OpenClaw은 AI 비서를 내 기기에서, 내가 쓰는 메신저로 운용할 수 있게 해주는 강력한 도구입니다. 오픈소스이기 때문에 원하는 대로 커스터마이즈할 수 있고, 프라이버시도 보장됩니다.

유용한 링크:

이 글이 도움이 되셨다면 공감 및 광고 클릭을 부탁드립니다 :)