OpenClaw 완벽 가이드 - 로컬 AI 에이전트 설치부터 실전 활용까지

1. OpenClaw란?

OpenClaw는 GitHub 140k+ 스타로 단기간 급상승한 로컬 AI 에이전트 플랫폼이다. 개발자는 PSPDFKit 창업자이기도 한 Peter Steinberger(steipete)이며, 상징처럼 따라붙는 문구는 “The lobster way 🦞”다. 로컬 우선(Local First) 철학과 Agentic Workflow를 전면에 내세워, 단순히 채팅에 그치지 않고 실제 행동을 수행하는 에이전트 운영을 지향한다.

핵심은 로컬에서 동작하는 게이트웨이(컨트롤 플레인)다. 세션, 채널, 툴, 이벤트를 하나로 통합해 관리하고, 다양한 채널에서 들어오는 요청을 멀티 에이전트로 라우팅한다. 로컬 환경에서 안전하게 돌리면서도 확장 가능한 운영을 목표로 설계된 점이 특징이다. 프로젝트는 MIT 라이선스로 공개되어 있다.

공식 슬로건은 다음과 같다.

“Your own personal AI assistant. Any OS. Any Platform. The lobster way. 🦞”

2. 이름 변경의 역사: Clawdbot → Moltbot → OpenClaw

OpenClaw는 이름이 여러 번 바뀌었다.

Clawdbot: 초기 이름. Anthropic 상표권 침해 경고로 변경.
Moltbot: “가재가 탈피(Molt)하듯 성장한다”는 의미로 사용.
OpenClaw: 프로젝트의 개방성을 강조하며 2026.01.29부터 최종 확정.

이력 때문에 구버전 문서를 참고할 때는 이름과 링크가 뒤섞여 있을 수 있다.

3. 아키텍처 살펴보기

OpenClaw의 게이트웨이는 로컬에서 동작하는 컨트롤 플레인이다. 여러 채널에서 들어온 요청을 한 곳에서 수신하고, 에이전트/CLI/앱과 통신한다. 구조를 한눈에 보면 아래와 같다.

WhatsApp / Telegram / Slack / Discord / etc.
               │
               ▼
┌───────────────────────────────┐
│            Gateway            │
│       (control plane)         │
│     ws://127.0.0.1:18789      │
└──────────────┬────────────────┘
               │
               ├─ Pi agent (RPC)
               ├─ CLI (openclaw …)
               ├─ WebChat UI
               ├─ macOS app
               └─ iOS / Android nodes

4. 빠른 시작

4.1 설치 방법 (npm, curl, 소스)

요구사항: Node.js 22+

npm 설치

npm install -g openclaw@latest

원라인 설치 스크립트

curl -fsSL https://molt.bot/install.sh | bash

소스에서 설치

공식 GitHub 저장소:

https://github.com/openclaw/openclaw

소스 빌드 명령은 문서에 따라 달라질 수 있으므로 공식 문서를 참고하자.

4.2 온보딩 마법사

설치 후 온보딩 마법사를 실행한다.

openclaw onboard --install-daemon

4.3 첫 번째 명령어

예: Skills 목록 확인

openclaw skills list

5. 심화 가이드

5.1 Docker로 운영하기

OpenClaw는 Docker 기반 설치를 지원한다.

빠른 시작 스크립트

./docker-setup.sh

수동 구성 (공식 절차)

docker compose run --rm openclaw-cli onboard
docker compose up -d openclaw-gateway

docker-compose.yml 예시

실제 구성 형식은 버전과 문서에 따라 달라질 수 있다. 공식 문서를 기준으로 조정하자.

version: '3.8'
services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    restart: always
    volumes:
      - ./config:/root/.openclaw
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - OPENCLAW_API_KEY=sk-...
      - SANDBOX_MODE=rw
    ports:
      - "8080:8080"

환경 변수

OPENCLAW_API_KEY
OPENCLAW_DOCKER_APT_PACKAGES
OPENCLAW_EXTRA_MOUNTS
OPENCLAW_HOME_VOLUME

설정/데이터 지속성

~/.openclaw/
~/.openclaw/workspace

샌드박싱

에이전트 격리를 위해 agents.defaults.sandbox 설정을 활용한다. 샌드박싱 범위와 정책은 보안 요구사항에 따라 조정하자.

5.2 모델 선택 가이드

OpenClaw는 여러 모델 공급자를 지원한다.

Anthropic Claude (Pro/Max 권장, Opus 4.5가 최고 결과)
OpenAI GPT-4, GPT-3.5
로컬 모델: Ollama, LM Studio
OpenAI 호환 엔드포인트

상용 모델은 비용/품질이 균형 좋고, 로컬 모델은 프라이버시와 비용 절감에 유리하다.

config.json 예시

실제 설정 포맷은 버전에 따라 변경될 수 있다. 공식 문서를 확인하자.

{
  "profile": {
    "name": "MyDevBot",
    "role": "Senior DevOps Engineer"
  },
  "llm": {
    "provider": "anthropic",
    "model": "claude-3-5-sonnet-20240620",
    "temperature": 0.0
  },
  "permissions": {
    "filesystem": ["/Users/username/Projects", "/tmp"],
    "network": ["allow_all"],
    "browser": {
      "headless": false,
      "user_data_dir": "./chrome-profile"
    }
  }
}

5.3 채널 연결

OpenClaw는 멀티채널 인박스를 제공한다. 지원 채널에는 WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, iMessage, BlueBubbles, Microsoft Teams, Matrix, Zalo, WebChat 등이 포함된다.

openclaw channels login whatsapp

QR 코드가 출력되며 스캔하면 연결된다.

openclaw channels login telegram

Discord

openclaw channels login discord

5.4 Skills 시스템

OpenClaw는 Skills 플랫폼을 제공하며, 번들/관리형/워크스페이스 스킬을 지원한다.

스킬 목록

openclaw skills list

스킬 활성화

openclaw skills enable skill-name

스킬 레지스트리

공식 레지스트리는 ClawdHub다.

스킬 정의 예시 (github.md)

아래는 개념 예시이며 실제 포맷은 문서에 맞게 조정해야 한다.

---
name: github_manager
description: GitHub 저장소의 이슈를 확인하고 관리합니다.
dependencies: ["gh"]
---

# GitHub Issue Skill

사용자가 "최근 이슈 보여줘"라고 요청하면 아래 절차를 수행하라.

1. 현재 디렉토리 확인
2. `gh issue list` 실행
3. 결과를 JSON으로 파싱하여 요약

## Commands
- list_issues: `gh issue list --limit 10 --json number,title,author`
- read_issue: `gh issue view {issue_number}`

사용 시나리오

User: "이번 주 OpenClaw 레포에 올라온 버그 리포트만 정리해줘."
Bot: (내부적으로 gh issue list 실행 → 텍스트 파싱 → 요약 리포트 생성) → 결과 출력

5.5 보안 설정

OpenClaw는 DM 페어링 정책과 샌드박스, 툴 정책을 제공한다.

DM 페어링 정책

dmPolicy="pairing" 설정을 사용한다.

페어링 승인

openclaw pairing approve <channel> <code>

툴 allow/deny 정책

필요한 툴만 허용하고 나머지는 차단하는 정책을 설정한다.

5.6 주의사항 및 보안 이슈

Prompt Injection 위험

외부 이메일이나 웹사이트 내용을 읽다가 악성 명령어를 실행할 위험이 있다.
신뢰할 수 없는 소스의 콘텐츠를 처리할 때 주의가 필요하다.

가상화폐 스캠 주의

리브랜딩 혼란을 틈타 구 트위터 핸들(@clawdbot)을 탈취하여 스캠 코인을 홍보하는 사례가 발생했다.
공식 채널 확인 필수: https://openclaw.ai, https://github.com/openclaw/openclaw

Cloudflare Workers 실험

최근 moltworker라는 이름으로 Cloudflare Workers 위에서 돌아가는 경량 버전도 실험 중인 것으로 알려져 있다.

6. 실전 사용기 (시뮬레이션)

⚠️ 아래 내용은 실제 실행 결과가 아닌 텍스트 시뮬레이션입니다. 환경에 따라 출력이 다를 수 있습니다.

6.1 설치부터 WhatsApp 연동까지

1) Node.js 22+를 설치하고 npm으로 OpenClaw를 설치한다.

npm install -g openclaw@latest

2) 온보딩 마법사를 실행한다.

openclaw onboard --install-daemon

3) WhatsApp 채널 로그인을 실행한다.

openclaw channels login whatsapp

4) QR 코드를 스캔해 WhatsApp과 연결된다.

6.2 Docker로 설치하는 시나리오

# Docker로 설치하는 시나리오
git clone https://github.com/openclaw/openclaw.git
cd openclaw
./docker-setup.sh

# 출력 예시 (시뮬레이션)
# Building openclaw:local...
# Running onboarding wizard...
# ? Select AI provider: Anthropic Claude
# ? Enter API key: sk-ant-...
# ? Install gateway daemon? Yes
# Gateway started at ws://127.0.0.1:18789
# Token: ocl_abc123...

6.3 흔한 오류와 해결 과정

오류 A: `node: command not found`

원인: Node.js 22+가 설치되지 않았거나 PATH가 설정되지 않음.
해결: Node.js 22+ 설치 후 셸을 다시 로드한다.

node -v

오류 B: WhatsApp 로그인 후 메시지 수신 실패

원인: DM 페어링 정책이 켜져 있어 승인이 필요함.
해결: 페어링 승인 명령 실행.

openclaw pairing approve whatsapp <code>

오류 C: API Key 인증 실패

원인: OPENCLAW_API_KEY 환경변수가 설정되지 않았거나 잘못된 키
해결: .env 파일 또는 환경변수 확인

export OPENCLAW_API_KEY="sk-ant-your-key-here"
openclaw doctor  # 진단 실행

7. 결론

OpenClaw는 로컬 우선 게이트웨이와 멀티채널/멀티에이전트 운영이 필요한 팀에 특히 적합하다. 보안·프라이버시 요구가 높거나 사내망에서 모델을 운영하려는 경우 큰 장점이 있다. 반면, 단순한 챗봇 하나만 필요하거나 운영 복잡성이 부담이라면 더 가벼운 솔루션이 맞을 수 있다.

8. TL;DR (핵심 요약)

GitHub Star 140k+로 단기간 급상승하며 개발자 커뮤니티 주목을 받았다.
로컬 우선(Local First)과 Agentic Workflow를 내세우는 오픈소스 에이전트 플랫폼이다.
Clawdbot → Moltbot → OpenClaw로 이름이 바뀌었으니 구버전 문서 참고 시 유의.
설치는 Node.js 22+에서 npm install -g openclaw@latest 또는 설치 스크립트로 시작한다.
Docker로도 운영 가능하며, docker compose 기반 온보딩 후 게이트웨이를 올린다.
WhatsApp/Telegram/Discord 등 다중 채널을 CLI로 연결하고 Skills로 확장한다.

9. 참고 링크

GitHub: https://github.com/openclaw/openclaw
공식 문서: https://docs.openclaw.ai
공식 사이트: https://openclaw.ai
Discord 커뮤니티: https://discord.gg/clawd
ClawdHub (Skills 레지스트리): https://clawdhub.com
DeepWiki: https://deepwiki.com/openclaw/openclaw

'AI' 카테고리의 다른 글

Nitter 셀프호스팅 완벽 가이드 - 프라이버시와 X 크롤링 (0)	2026.02.03
2026년 2월 메인 AI 모델 루머 정리 (OpenAI vs xAI vs Google vs Anthropic) (0)	2026.02.03
Supertonic 2 개발자 가이드 - 온디바이스 TTS 통합과 성능 최적화 (0)	2026.02.03
Supertonic 2 - 세상에서 가장 빠른 온디바이스 TTS (0)	2026.02.03
Figma Code Connect 가이드 (0)	2026.02.02