새소식

300x250
AI/OpenClaw(구 Moltbotbot, Clawdbot)

OpenClaw (구 Moltbot, 구 Clawdbot) 리뷰(1) : OpenClaw설치 및 온보딩 가이드 - 개인 AI 비서 시작하기

  • -
728x90

안녕하세요! 갓대희 입니다.

오늘은 구 Clawdbot(클로드봇), 구 Moltbot, 현재 OpenClaw에 대해 간략히 알아보고 설치해보려 한다. 

2026년 1월 30일 업데이트: OpenClaw로 리브랜딩

이 프로젝트가 또 한 번 이름을 변경했습니다.
Clawdbot → Moltbot (1/27) → OpenClaw (1/29)

공식 웹사이트 https://openclaw.ai
GitHub github.com/openclaw/openclaw
공식 문서 https://docs.openclaw.ai
npm 패키지 npm install -g openclaw
⚠️ 기존 Moltbot 사용자: 아래 "기존 사용자 업데이트 가이드" 섹션을 참고하세요.

"같은 랍스터의 영혼, 새로운 껍데기. 이번엔 상표 검색도 완료했습니다." — Peter Steinberger
(출처: DEV Community)

 

"Siri가 약속했지만 이루지 못한 것"
2026년 초, AI 커뮤니티에서 가장 많이 회자되는 문장이다. 그리고 그 약속을 실현하고 있다고 평가받는 오픈소스 프로젝트가 있다.
바로 OpenClaw(구 Moltbot, 구 Clawdbot)이다.

예전 clawdbot(moltbot) 시절의 모습도 하나 박제.

 GitHub에서 174,000개 이상의 stars를 기록하며 폭발적인 성장을 보이고 있는 이 프로젝트는, AI가 단순히 "답변"하는 것을 넘어 실제로 "행동"하는 시대를 열고 있다는 평이다.


이번 글에서는 OpenClaw가 무엇인지 소개하고, 설치부터 첫 번째 자동화 명령 실행까지 단계별로 알아보자. 

( 조금 지루한 이론 내용이 앞에 있으니, 설치부터 하려면 후반부 부터 보시는걸 추천 드립니다. )

최신 정보는 공식 문서에서 확인하시기 바랍니다.
(참고: 이전 URL인 docs.molt.bot은 docs.openclaw.ai로 리다이렉트됩니다)
Clawdbot → Moltbot → OpenClaw (2026년 1월)

이 프로젝트는 한 달도 안 되는 기간에 세 번의 이름 변경을 거쳤다.

날짜 이름 변경 사유
2025년 말 Clawdbot 최초 출시
2026-01-27 Moltbot Anthropic 상표권 요청 ("Clawd" ≈ "Claude")
2026-01-29 OpenClaw 상표 검색 완료 후 안정적 리브랜딩

"같은 랍스터의 영혼, 새로운 껍데기. 이번엔 상표 검색도 완료했습니다."
— Peter Steinberger (@steipete)

⚠️ 주의: 사기 경고
리브랜딩 과정에서 기존 핸들(@clawdbot, @moltbot)이 악용되어 가짜 암호화폐가 발행되었습니다.
Peter Steinberger 공식 입장: "저를 코인 소유자로 표기하는 모든 프로젝트는 사기입니다."
핵심 요약
OpenClaw(구 Moltbot)은 로컬에서 실행되는 Personal AI Agent로, WhatsApp·Telegram·Slack·Discord 등 19개 채널을 통해 명령을 받고, 브라우저 제어·파일 관리·이메일 작성 등 실제 작업을 자율적으로 수행한다.
MIT 라이선스 오픈소스로, Claude/OpenAI 모델 및 Ollama 로컬 LLM과 연동되며, Node.js 22 이상 환경에서 실행된다.

설치 과정: Node.js 22+ 설치 → OpenClaw CLI 설치 → 온보딩 마법사 실행 → 게이트웨이 시작
개발자: Peter Steinberger (@steipete) — PSPDFKit(현 Nutrient) 창업자

목차

Part A: OpenClaw 소개

  1. 들어가며: AI 비서의 진화
  2. OpenClaw란 무엇인가?
  3. 왜 2026년은 Personal Agent의 해인가?
  4. 기존 AI 비서와의 차이점
  5. OpenClaw 아키텍처 개요
  6. 누가 OpenClaw를 사용해야 할까?
  7. OpenClaw와 대화하는 다양한 방법

Part B: 설치 가이드

  1. 사전 요구사항
  2. Step 1: Node.js 22+ 설치
  3. Step 2: OpenClaw CLI 설치
  4. Step 3: 온보딩 마법사 실행
  5. Step 4: API 키 설정
  6. Step 5: 게이트웨이 시작
  7. Step 6: 첫 번째 명령 실행
  8. 설정 파일 구조 이해하기
  9. 트러블슈팅

v2026.2.x 주요 업데이트 (2026년 2월 기준)

Agents 대시보드

에이전트, 도구, 스킬, 모델, 채널, 크론 작업을 웹 UI로 관리

새 모델 지원

Anthropic Opus 4.6, OpenAI Codex gpt-5.3-codex 추가

새 채널 추가

Google Chat, Twitch 플러그인 (총 19개 채널)

QMD 백엔드

워크스페이스 메모리 시스템 (opt-in)

보안 강화

인증 필수화 (auth: "none" 제거), 34개 보안 커밋

설정 검증 강화

잘못된 설정값 자동 거부, 설정 마이그레이션 개선

v2026.1.24 주요 기능: LINE 플러그인, OpenAI 호환 API, Browser refs=aria 스냅샷 개선, 메시지 Debounce

전체 변경사항: GitHub Releases

 

Part A: OpenClaw(구 Moltbot, 구 Clawdbot) 소개

1. 들어가며: AI 비서의 진화

2011년, 애플은 Siri를 공개하며 "음성으로 모든 것을 해결한다"는 비전을 제시했다.
2016년, 아마존 Alexa와 구글 Assistant가 등장했고, 우리는 "오케이 구글, 알람 맞춰줘"라고 말하기 시작했다.
하지만 10년이 넘도록 이들이 해결해주는 건 여전히 타이머 설정, 날씨 확인, 간단한 검색 수준에 머물러 있다.

기존 AI 비서의 한계
  • "이메일 보내줘" → 앱 열어주고 끝
  • "회의 일정 잡아줘" → 캘린더 앱으로 이동
  • "이 웹사이트에서 정보 찾아줘" → 검색 결과만 보여줌

사실상 "앱 런처" 역할에 그치고, 실제 작업 완료는 여전히 사용자의 몫이다.

2026년, 이 패러다임이 바뀌고 있다.
LLM의 발전과 함께 AI가 "생각"뿐 아니라 "행동"까지 할 수 있게 되었고, 그 최전선에 OpenClaw가 있다.

 

2. OpenClaw란 무엇인가?

공식 소개
"Your own personal AI assistant. Any OS. Any Platform. The lobster way."
(당신만의 개인 AI 비서. 어떤 운영체제(OS)든, 어떤 플랫폼이든. 로브스터(Lobster) 방식으로.)
(출처: OpenClaw GitHub)

OpenClaw는 로컬에서 실행되는 Personal AI Agent이다.

Anthropic의 Claude나 OpenAI 모델을 두뇌로 사용하면서, 여러분의 컴퓨터에서 실제 작업을 수행할 수 있다. 브라우저를 열고, 파일을 읽고, 터미널 명령을 실행하고, 이메일을 보내는 등의 작업을 자율적으로 처리한다.

개발자: Peter Steinberger
  • GitHub: @steipete
  • 경력: PSPDFKit(현 Nutrient) 창업자, macOS/iOS 개발 전문가
  • 기반: 오스트리아 비엔나
  • 시작 계기: 개인 AI 비서 "Molt"(우주 바닷가재 캐릭터)를 위해 개발

"I'm Molt — Claude with a 'w' and a lobster emoji. I run on Claude Opus 4.5, living in Peter's Mac Studio ('the Castle') in Vienna."
— molt.me

 

2.1 "Claude with hands" — 실제 작업을 수행하는 AI

커뮤니티에서는 OpenClaw를 "Claude with hands(손이 달린 Claude)"라고 부른다.

ChatGPT나 Claude.ai는 대화창에서 답변만 제공하지만, OpenClaw는 다음 행동들을 할 수 있다.

  • 쉘 명령 실행: "프로젝트 빌드하고 테스트 돌려줘"
  • 브라우저 제어: "내 로그인 세션으로 이 사이트에서 정보 수집해줘"
  • 이메일 작성/전송: "이 내용으로 팀에게 이메일 보내줘"
  • 캘린더 관리: "내일 오후 3시 회의 잡아줘"
  • 스마트홈 제어: "퇴근 모드 실행해줘"

 

2.2 핵심 특징 4가지

특징 설명
Local-First 모든 데이터와 실행이 내 컴퓨터에서 이루어진다. 민감한 정보가 외부 서버로 전송되지 않음 (LLM API 호출 제외)
Multi-Channel WhatsApp, Telegram, Slack, Discord, iMessage, Microsoft Teams 등 19개 채널에서 명령 가능. 어디서든 내 AI 비서에 접근
Skills 생태계 Notion, Spotify, Philips Hue, Gmail 등 다양한 Skills로 기능 확장. ClawHub에서 자동 검색/설치
Voice 지원 macOS/iOS/Android에서 Voice Wake 및 Talk Mode 지원. TTS 코어 통합 (Edge TTS 키리스 폴백), ElevenLabs 연동

 

2.3 Special Feature: Happycapy

Special Feature: Happycapy (Visual Agent)

OpenClaw의 형제 프로젝트인 Happycapy는 브라우저를 "Agent-Native Computer"로 변신시킨다.
터미널이 어렵다면, Happycapy.ai에서 설치 없이 바로 시작할 수 있다.
• CLI to GUI: 복잡한 명령어를 직관적인 UI로 변환
• Passive Productivity: 백그라운드에서 조용히 업무 처리
(Part 4에서 OpenClaw와 Happycapy의 연동 모델을 자세히 다룬다)

 

3. 왜 2026년은 Personal Agent의 해인가?

3.1 폭발적인 성장 지표

지표 수치 의미
GitHub Stars 174,000+ 2026년 1월 기준 (빠르게 성장 중)
GitHub Forks 28,400+ 활발한 커뮤니티 참여
Discord 멤버 8,900+ 활발한 커뮤니티 토론
지원 채널 19개 WhatsApp, Telegram, Slack, Discord, Teams 등

(출처: OpenClaw GitHub, 2026-01-27 확인)

3.2 커뮤니티 반응

"2026 is already the year of personal agents." (2026년은 이미 개인 에이전트(Personal Agents)의 해입니다.)
— Hacker News
"Essentially - you can automate almost anything you can do on the machine it sits on."
(본질적으로, 그 에이전트가 실행되는 컴퓨터(머신)에서 할 수 있는 거의 모든 작업을 자동화할 수 있습니다.)
— Reddit r/LocalLLaMA
"The self-hosted AI that Siri should have been."
(시리가 원래 갖췄어야 할 셀프 호스팅(Self-hosted) AI.)
— VelvetShark 블로그

MacStories의 리뷰에서는 OpenClaw를 "Personal AI 비서의 미래가 어떤 모습일지 보여주는 프로젝트"라고 평가했다.

 

4. 기존 AI 비서와의 차이점

4.1 Siri/Google Assistant vs OpenClaw

구분 Siri/Google Assistant OpenClaw
실행 위치 클라우드 (회사 서버) 로컬 (내 컴퓨터)
작업 수행 앱 실행 / 검색 결과 제공 실제 작업 완료
확장성 제한된 서드파티 통합 ClawHub Skills 생태계
데이터 프라이버시 회사 서버에 저장 로컬 저장 (LLM API 제외)
채널 전용 앱/디바이스 19개 메시징 플랫폼

 

4.2 ChatGPT/Claude vs OpenClaw

구분 ChatGPT/Claude.ai OpenClaw
역할 대화형 AI (답변 제공) AI Agent (작업 수행)
내 시스템 접근 불가능 파일, 브라우저, 터미널 접근
외부 서비스 연동 제한된 플러그인 ClawHub Skills 생태계
자율성 질문-응답 사이클 Cron, 웹훅, 자율 행동

 

5. OpenClaw 아키텍처 개요

OpenClaw의 아키텍처를 이해하면, 이 도구의 잠재력을 더 잘 파악할 수 있다.

┌─────────────────────────────────────────────────────────────┐
│                    External Channels (19개)                  │
│  WhatsApp │ Telegram │ Slack │ Discord │ iMessage │ Teams  │
│  Signal │ Google Chat │ Matrix │ Zalo │ BlueBubbles │ WebChat│
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                   Gateway (Local)                          │
│              ws://127.0.0.1:18789                            │
│         세션 관리, 채널 라우팅, 권한 제어                    │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                   Pi Agent Runtime                         │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐        │
│  │ Claude  │  │ OpenAI  │  │ Skills  │  │ Browser │        │
│  │  API    │  │  API    │  │ Engine  │  │ Control │        │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘        │
└─────────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                   Local Resources                          │
│      파일 시스템 │ 터미널 │ 브라우저 │ 스마트홈 ...         │
└─────────────────────────────────────────────────────────────┘

5.1 핵심 컴포넌트

  • Gateway: 로컬에서 실행되는 WebSocket 서버. 모든 채널의 메시지를 수신하고 라우팅
  • Pi Agent Runtime: LLM 연동, Skills 실행, 브라우저 제어 등 핵심 로직
  • Skills Engine: ClawHub에서 Skills를 검색하고 자동 설치
  • Browser Control: Chrome/Chromium을 CDP(Chrome DevTools Protocol)로 제어
  • Multi-Channel Bridge: 19개 메시징 플랫폼 통합

5.2 지원 플랫폼

필수 요구사항

OpenClaw 실행에는 Node.js 22 이상이 필요합니다.
(출처: 공식 GitHub README)

OS 지원 상태 비고
macOS 지원 네이티브 앱 + Voice Wake 지원
Linux 지원 CLI 기반
Windows 지원 (WSL2) WSL2 환경 권장
iOS/Android Talk Mode 지원 원격 접근 + ElevenLabs 음성 연동

 

6. 누가 OpenClaw를 사용해야 할까?

OpenClaw가 적합한 경우
  • 개발자: 코드 작업, 빌드, 테스트, PR 생성 자동화
  • 생산성 얼리어답터: 이메일, 캘린더, 노션 등 업무 자동화
  • 스마트홈 사용자: Philips Hue 등 IoT 기기 통합 제어
  • 프라이버시 중시자: 로컬 실행으로 데이터 통제
  • 커스터마이징 애호가: 자신만의 Skills 개발
OpenClaw가 적합하지 않은 경우
  • CLI 경험이 전혀 없는 사용자: 초기 설정에 터미널 사용 필요
  • LLM API 비용을 지불할 의사가 없는 경우: Claude/OpenAI API 필요
  • 단순 Q&A만 원하는 경우: ChatGPT/Claude.ai가 더 간편
  • 엔터프라이즈 멀티유저 환경: 현재는 Single-User 중심
보안 주의사항
  • 디렉토리 샌드박싱 미지원: 시스템 전체 파일에 접근 가능. 민감한 파일 접근에 주의
  • 격리 환경 권장: 보안 전문가들은 별도 계정, 별도 비밀번호 관리자 사용 권장
  • 인증 정보 노출 사례: Signal 등 메시징 앱 연동 시 인증 데이터 노출 사례 보고됨
⚠️ 2026년 1월 보안 취약점 발견 (Bitdefender)

보안 연구진이 수백 개의 OpenClaw 인스턴스가 인증 없이 인터넷에 노출된 것을 발견했다:

  • 노출된 정보: API 키, 대화 기록, 파일 교환 기록
  • 원인: 잘못 구성된 reverse proxy, localhost 신뢰 가정
  • 위험: 시스템 레벨 명령 실행, root 권한 탈취 가능성

권장사항: Gateway를 외부에 직접 노출하지 말 것. VPN 또는 Tailscale 사용 권장.
설치 후 openclaw security audit --deep 실행 필수.

(참고: Hacker News 토론, Bitdefender 보안 경고)

API 비용 주의 & Zero Cost 대안

OpenClaw는 자율적 에이전트로 토큰 소비량이 매우 높다. (2일간 $300 소비 사례 존재)
하지만 걱정할 필요 없다.

Native Ollama Integration (비용 $0)
OpenClaw는 Ollama를 통한 로컬 LLM 구동을 기본 지원한다.
Llama 3, Mistral 등 고성능 로컬 모델을 연결하면 추가 비용 없이 ("공짜로") 24/7 에이전트를 운영할 수 있다.

 

7. OpenClaw와 대화하는 다양한 방법

OpenClaw는 웹 채팅뿐 아니라 다양한 인터페이스를 통해 상호작용할 수 있다. 상황에 맞는 인터페이스를 선택하면 더욱 효율적으로 AI 비서를 활용할 수 있다.

7.1 인터페이스 방식 비교

인터페이스 실행 방법 특징 적합한 상황
TUI
(Terminal UI)		 openclaw tui 터미널에서 시각적 채팅 인터페이스 SSH 접속, 서버 환경
Web Dashboard openclaw dashboard 브라우저에서 채팅, 설정, 세션 관리 일상적 사용, 설정 변경
CLI
(명령줄)		 openclaw [command] 명령어 기반 직접 제어 스크립트, 자동화
메시징 채널 Part 2 참조 Telegram, Discord, Slack 등 23개 채널 모바일, 외출 중

(출처: OpenClaw 공식 문서)

7.2 TUI (Terminal User Interface)

TUI란?

TUI는 터미널 환경에서 시각적 인터페이스를 제공하는 채팅 방식이다. 마우스 없이 키보드만으로 OpenClaw와 대화할 수 있어, SSH로 원격 서버에 접속한 상황에서 특히 유용하다.

TUI 실행 방법

# 기본 실행
openclaw tui

# 특정 세션으로 연결
openclaw tui --session main

# 원격 Gateway에 연결
openclaw tui --url ws://your-server:18789 --token YOUR_TOKEN

TUI가 유용한 상황

  • SSH 원격 접속 — 서버에서 직접 AI와 대화
  • GUI 없는 환경 — 헤드리스 서버, Docker 컨테이너
  • 저대역폭 환경 — 웹 UI보다 가벼움
  • 키보드 중심 워크플로우 — 마우스 사용 최소화

ex) tui 방식 모습

 

 

7.3 Web Dashboard & WebChat

가장 친숙한 방식의 인터페이스다. 브라우저에서 채팅하고, 설정을 변경하고, 세션을 관리할 수 있다.

Dashboard 실행 방법

# Dashboard 열기 (브라우저 자동 실행)
openclaw dashboard

# 브라우저 자동 열기 비활성화
openclaw dashboard --no-open

# 기본 URL: http://127.0.0.1:18789/

Web Dashboard 주요 기능

  • WebChat — 브라우저에서 AI와 실시간 대화
  • 설정 관리 — API 키, 채널, Skills 설정
  • 세션 모니터링 — 활성 세션 및 대화 기록 확인
  • 노드 관리 — 연결된 모바일/데스크톱 노드 확인

ex) 웹 채팅을 통한 대화 / 응답 방식 모습

 

7.4 CLI (Command Line Interface)

CLI는 스크립트 자동화나 빠른 명령 실행에 적합하다. 대화형 채팅보다는 특정 작업을 바로 실행하고 싶을 때 사용한다.

# 주요 CLI 명령어 예시
openclaw agent "오늘 날씨 알려줘"     # 단일 명령 실행
openclaw skills list                   # 설치된 Skills 목록
openclaw channels status               # 채널 연결 상태
openclaw memory search "회의록"        # Memory 검색
openclaw gateway status                # Gateway 상태 확인
openclaw logs --follow                 # 실시간 로그 확인

 

7.5 언제 어떤 인터페이스를 사용할까?

상황별 권장 인터페이스
  • 일상적인 대화 → Web Dashboard (WebChat)
  • 외출 중, 모바일 → Telegram/Discord (Part 2)
  • 서버 SSH 접속 중 → TUI
  • 스크립트/자동화 → CLI
  • 설정 변경 → Web Dashboard
메시징 채널 연동은 Part 2에서

Telegram, Discord, Slack, WhatsApp 등 23개 메시징 채널 연동 방법은 Part 2: 멀티채널에서 자세히 다룬다.

지금까지 OpenClaw가 무엇인지 살펴보았다.

이제부터는 실제로 설치하고 사용하는 방법을 단계별로 안내한다.
터미널을 열고 따라오기만 하면, 나만의 Personal AI Agent를 가동할 수 있다.

 

Part B: 설치 가이드

8. 사전 요구사항

OpenClaw를 설치하기 전에 다음 요구사항을 확인하자.

항목 요구사항 비고
Node.js ≥ 22 (필수) 22 미만 버전은 지원하지 않음
운영체제 macOS, Linux, Windows (WSL2) Windows는 WSL2 환경 필수
LLM API 키 Anthropic 또는 OpenAI Claude Pro/Max 권장
RAM ≥ 2GB (기본), ≥ 4GB (권장) 브라우저 자동화 시 4GB+ 필요
CPU 2 코어 이상 기본 채팅에 충분
디스크 공간 20GB 이상 앱, 대화 기록, 워크스페이스 포함
네트워크 인터넷 연결 LLM API 호출에 필요
중요: Node.js 버전 확인

OpenClaw는 Node.js 22 이상을 필수로 요구한다.
이전 버전(20, 18 등)에서는 설치는 되더라도 정상 작동하지 않을 수 있다.

현재 Node.js 버전 확인: node --version

 

9. Step 1: Node.js 22+ 설치

운영체제별 Node.js 22+ 설치 방법을 안내한다.

8.1 macOS

방법 1: Homebrew (권장)

# Homebrew로 Node.js 22 설치
brew install node@22

# PATH에 추가 (zsh 기준)
echo 'export PATH="/opt/homebrew/opt/node@22/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 버전 확인
node --version  # v22.x.x 출력 확인

 

방법 2: nvm (Node Version Manager)

# nvm 설치 (이미 설치되어 있다면 생략)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.zshrc

# Node.js 22 설치 및 사용
nvm install 22
nvm use 22
nvm alias default 22  # 기본값으로 설정

 

8.2 Linux (Ubuntu/Debian)

# NodeSource 저장소 추가
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

# Node.js 22 설치
sudo apt-get install -y nodejs

# 버전 확인
node --version

 

8.3 Windows (WSL2)

Windows 사용자 주의

OpenClaw는 네이티브 Windows를 지원하지 않는다.
반드시 WSL2 (Windows Subsystem for Linux 2) 환경에서 설치해야 한다.

# PowerShell (관리자)에서 WSL2 설치
wsl --install

# WSL 터미널에서 Node.js 설치 (Ubuntu)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

 

10. Step 2 : OpenClaw CLI 설치

Node.js 22+가 준비되었다면, OpenClaw CLI를 설치한다.

 

9.1 방법 1: 공식 설치 스크립트 (권장)

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

(출처: OpenClaw 공식 문서)

 

ex) 몰트봇으로 아직 덜 변견된 부분들도 보이긴 하지만... ㅎㅎ

ex) 한글화

  

9.2 방법 2: npm/pnpm 글로벌 설치

# npm 사용
npm install -g openclaw

# 또는 pnpm 사용
pnpm add -g openclaw

 

9.3 설치 확인

# 버전 확인
openclaw --version

# 도움말 확인
openclaw --help
설치 성공 확인

openclaw --version 명령이 버전 번호를 출력하면 설치 성공이다.

CLI 명령어 통합 안내

CLI 명령어는 openclaw로 통합되었다. npm 패키지명도 openclaw이다.

최신 정보는 공식 문서에서 확인할 것.

(아래 스크린샷은 과거 clawdbot 시절의 화면이다. 현재는 openclaw 명령어로 통합되었다.)

 

9.4 방법 3: Docker 컨테이너 배포

서버 환경이나 격리된 환경에서 운영하고 싶다면 Docker를 사용할 수 있다.

# Docker 이미지 pull
docker pull alpine/openclaw:latest

# 컨테이너 실행 (설정 파일 마운트)
docker run -d \
  --name openclaw \
  -v ~/.openclaw:/root/.openclaw \
  -p 18789:18789 \
  alpine/openclaw:latest

⚠️ Docker 이미지 이름/태그는 공식 릴리스에 따라 다를 수 있다. GitHub Container Registry에서 확인.

 

9.5 방법 4: PaaS 플랫폼 배포

Railway, Replit, Coolify 등 PaaS 플랫폼에서도 배포할 수 있다. 24시간 상시 운영이 필요한 경우 유용하다.

플랫폼 특징 비용
Railway GitHub 연동, 자동 배포, 간편한 환경 변수 설정 월 $5~ (사용량 기반)
Replit 브라우저 기반 개발 환경, Always On 기능 무료 / Hacker $7/월
Coolify Self-hosted PaaS, Docker 기반, 완전한 제어권 무료 (서버 비용만)

 

9.6 방법 5: VPS 호스팅

저렴한 VPS에서 24시간 운영하는 방법. 월 $4~5 수준의 저가 VPS로도 충분하다.

# 1. VPS 접속 후 Node.js 22 설치 (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# 2. OpenClaw 설치
npm install -g openclaw

# 3. 온보딩 실행
openclaw onboard --install-daemon

# 4. systemd 서비스로 등록 (자동 시작)
sudo openclaw service install
sudo systemctl enable openclaw
sudo systemctl start openclaw

권장 VPS 사양:

  • CPU: 1 vCPU 이상
  • RAM: 1GB 이상 (2GB 권장)
  • 저장소: 10GB 이상
  • 추천 업체: Vultr, DigitalOcean, Linode, Hetzner

 

11. Step 3: 온보딩 마법사 실행

OpenClaw의 핵심 설정은 온보딩 마법사를 통해 대화형으로 진행된다.

# 온보딩 마법사 실행 (데몬 자동 설치 포함)
openclaw onboard --install-daemon

 

10.0 온보딩 단계별 상세 가이드

온보딩 마법사는 여러 단계의 질문을 통해 설정을 진행한다. 각 단계별로 무엇을 선택해야 하는지 간다히 설명하며 넘어가보자. 

◇ Security ─────────────────────────────────────

Please read: https://docs.openclaw.ai/security

OpenClaw agents can run commands, read/write files, and act through any tools you enable.

If you're new to this, start with the sandbox and least privilege.

◆ I understand this is powerful and inherently risky. Continue?

○ Yes / ● No

선택 Yes - 동의해야 설치가 진행된다.
의미 OpenClaw는 시스템 명령 실행, 파일 읽기/쓰기 등 강력한 권한을 가진다는 것을 이해하고 동의하는 것.
보안 팁 • 처음 사용자는 Sandbox 모드로 시작하는 것을 권장
• 민감한 디렉토리(~/.ssh, ~/.aws 등)에 대한 접근 제한 설정 가능
• 자세한 내용: docs.openclaw.ai/sandboxing
⚠️ 보안 관련 중요 안내

OpenClaw는 AI 에이전트로서 시스템에 대한 강력한 권한을 가진다:

  • 명령 실행: 터미널 명령어를 실행할 수 있음
  • 파일 접근: 허용된 디렉토리 내 파일 읽기/쓰기
  • 도구 사용: 활성화된 스킬/플러그인을 통한 작업

권장 사항:

  • 처음에는 Sandbox 모드와 최소 권한 원칙으로 시작
  • 워크스페이스를 별도 디렉토리로 격리
  • API 키는 환경 변수로 관리, 절대 채팅으로 공유하지 말 것

 

◇ I understand this is powerful and inherently risky. Continue?

  Yes

◆ Onboarding mode

  ● QuickStart (Configure details later via openclaw configure.)

  ○ Manual

선택 QuickStart - 빠르게 시작하고 나중에 세부 설정 해도 될 것 같다.
옵션 설명 추천 대상
QuickStart • 기본값으로 빠르게 설치 완료
• 세부 설정은 openclaw configure로 나중에 변경 가능
• 최소한의 질문만 진행		 처음 사용자, 빠른 테스트
Manual • 모든 설정 항목을 하나씩 직접 선택
• 게이트웨이 모드, LLM 제공자, 채널 등 상세 설정
• 설치 시간이 더 오래 걸림		 세부 제어가 필요한 고급 사용자

 

 

◇ Onboarding mode

  QuickStart

◇ QuickStart ────────────────────────

Gateway port: 18789

Gateway bind: Loopback (127.0.0.1)

Gateway auth: Token (default)

Tailscale exposure: Off

Direct to chat channels.

◆ Model/auth provider

  ● OpenAI (Codex OAuth + API key)

  ○ Anthropic

  ○ MiniMax

  ○ Qwen

  ○ Google

  ○ OpenRouter

  ○ Z.AI (GLM 4.7)

  ○ Skip for now

  ... 그 외 다수

선택 본인 구독 상황에 따라 다르다 - 아래 표 참고
제공자 특징 추천 대상
Anthropic • Claude 모델 (Sonnet, Opus, Haiku)
• API 키 사용 권장 (아래 경고 참조)
• 코딩 및 복잡한 추론에 강점		 API 키 사용자
코딩 작업 중심
OpenAI • GPT 모델, Codex 모델
• Codex CLI 구독자는 OAuth 로그인 지원
• 범용적 성능, 넓은 생태계		 Codex 구독자
범용 작업
Google • Gemini 모델 (Pro, Ultra)
• 멀티모달 (이미지, 비디오 분석) 강점
• API 키 필요		 Gemini 사용자
멀티모달 작업
Z.AI • GLM 4.7 모델
• 중국어 및 한국어 성능 우수
• 비용 효율적		 Z.AI 구독자
다국어 작업
OpenRouter • 여러 모델을 하나의 API로 통합
• Claude, GPT, Llama 등 다양한 모델 선택 가능
• 크레딧 기반 과금		 여러 모델 테스트
유연한 선택 원할 때
Skip for now • 나중에 openclaw configure로 설정
• 먼저 설치만 완료하고 싶을 때		 일단 설치만 하고
나중에 설정
여러 제공자를 동시에 사용할 수 있다!

OpenClaw는 여러 LLM 제공자를 동시에 설정할 수 있다. 온보딩에서 하나를 선택하고, 이후 openclaw configure에서 추가 제공자를 등록할 수 있다.

예시 조합:

🚨 중요 경고: Claude 구독형을 제3자 도구에서 사용하지 마세요 (2026년 1월 정책 변경)

2026년 1월 9일 02:20 UTC, Anthropic은 제3자 도구에서 Claude Pro/Max 구독 OAuth 토큰 사용을 기술적으로 차단했습니다. 사전 예고 없이 진행되었으며, 많은 개발자들이 갑자기 서비스가 중단되는 상황을 겪었습니다.

Anthropic ToS 원문:
"Except when you are accessing our Services via an Anthropic API Key or where we otherwise explicitly permit it, to access the Services through automated or non-human means, whether through a bot, script, or otherwise." (자동화된 수단을 통한 접근 금지)
ToS 위반 공식 Claude Code CLI 외에서 구독 토큰 사용은 명시적 약관 위반
밴 사례 실제로 밴 당한 사례 다수 보고됨 (일부는 복구됨, 아래 참조)
에러 메시지 "This credential is only authorized for use with Claude Code and cannot be used for other API requests"
✅ 권장 사항 API 키를 사용하세요 (토큰당 과금, 공식 지원 방식)
Anthropic 공식 입장 (Thariq Shihipar, Claude Code 팀):
  • "제3자 harness 스푸핑 방지를 위한 safeguard를 강화했습니다" (의도적 정책)
  • "제3자 harness는 텔레메트리 없이 비정상적 트래픽 패턴을 생성하여 디버깅과 지원을 어렵게 합니다"
  • "커스텀 도구에서 Claude를 사용하려면 API를 통하는 것이 공식 지원 방법입니다"
  • "abuse filter로 인해 자동 밴된 계정들은 복구했습니다" (밴 복구 확인)

출처: X (@TeksEdge)

⚠️ 밴 복구 관련 안내:
일부 사용자는 abuse filter에 의해 자동으로 밴 당했으나, Anthropic은 이를 실수로 인정하고 복구했습니다. 그러나 제3자 도구 자체의 차단 정책은 유지됩니다. 즉, 계정은 복구되어도 제3자 도구에서 구독 토큰을 사용할 수는 없습니다.
영향받는 도구: OpenClaw (Moltbot), oh-my-opencode, OpenCode, Cursor, Windsurf 등 모든 제3자 harness

출처:
• VentureBeat - Anthropic crackdown
• GitHub - OpenCode Issue #6930
• Hacker News 토론
• DHH (Rails 창시자) 비판
• Theo (t3.gg) 보고
• Threads - 밴 복구 확인
안전한 Claude 사용 방법 비교
방법 안전성 비용 비고
Anthropic API 키 안전 (공식 권장) Sonnet: $3-15/1M tokens
Opus: $15-75/1M tokens		 OpenClaw에서 권장
OpenRouter 안전 크레딧 기반 과금 여러 모델 통합 접근
구독 + 공식 Claude Code CLI 안전 $100-200/월 공식 CLI에서만 사용 가능
Ollama (로컬 LLM) 안전 무료 Part 6 참조
구독 + 제3자 도구 위험 (밴 가능) - ToS 위반, 기술적 차단됨
실제 비용 예시 (API 사용 시):
  • 가벼운 사용 (하루 몇 번 명령): $10-30/월
  • 보통 사용 (정기적인 파일 작업, 리서치): $30-70/월
  • 무거운 사용 (지속적인 자동화, 긴 세션): $70-150/월
  • 매우 무거운 사용 (하루 종일 자동화 루프): $200+/월

구독형 $200/월과 비교하면, 대부분의 사용자는 API가 더 저렴할 수 있습니다.

결론: OpenClaw에서 Claude를 사용하려면 Anthropic API 키 또는 OpenRouter를 선택하세요. 비용이 걱정된다면 Ollama (로컬 LLM)를 Part 6에서 확인하세요.

 

◆ Default model

  ● Keep current (default: anthropic/claude-opus-4-5)

  ○ Enter model manually

  ○ anthropic/claude-haiku-4-5

  ○ anthropic/claude-sonnet-4-5

  ○ anthropic/claude-opus-4-5

  ... 그 외 다수

선택 Keep current 또는 사용 목적에 맞는 모델
모델 특징 추천 용도
claude-opus-4-5 • 최고 성능의 추론 능력
• 복잡한 코딩, 분석, 창작에 탁월
• 응답 속도 느림, 비용 높음		 복잡한 작업
고품질 필요 시
claude-sonnet-4-5 • 균형 잡힌 성능 (권장)
• 빠른 응답 + 우수한 품질
• 일상적인 대부분의 작업에 적합		 일반 사용 (권장)
claude-haiku-4-5 • 가장 빠른 응답 속도
• 비용 효율적
• 간단한 질문, 빠른 작업에 적합		 빠른 응답 필요
간단한 작업
팁: 나중에 언제든 변경 가능

기본 모델은 언제든 변경할 수 있다.
처음에는 Sonnet으로 시작하고, 필요에 따라 Opus나 Haiku로 조정하는 것을 권장한다.

 

◆ Select channel (QuickStart)

  ○ Telegram (Bot API)

  ○ WhatsApp (QR link)

  ○ Discord (Bot API)

  ○ Google Chat (Chat API)

  ○ Slack (Socket Mode)

  ○ Signal (signal-cli)

  ○ iMessage (imsg)

  ○ LINE (Messaging API)

  ○ Microsoft Teams (Bot Framework)

  ● Skip for now

선택 Skip for now - 별도 섹션에서 다루고 지금은 스킵.
채널 설정은 Part 2에서!

채널 연동(Telegram, Discord, Slack, LINE 등)은 각각 Bot 생성, API 키 발급, 권한 설정 등 추가 작업이 필요하다.

지금은 Skip for now를 선택하고 CLI로 먼저 테스트하는 것을 권장한다.

 

그래도 바로 채널을 연동하고 싶다면, 아래 표를 참고하자:

채널 설정 난이도 특징
Telegram ⭐ 쉬움 • @BotFather로 봇 생성 → 토큰 발급
• 가장 간단한 설정, 초보자 추천
Discord ⭐⭐ 보통 • Discord Developer Portal에서 봇 생성
• 서버 초대 및 권한 설정 필요
Slack ⭐⭐ 보통 • Slack App 생성 → Socket Mode 활성화
• 업무용 메신저와 AI 연동
LINE ⭐⭐⭐ 복잡 • LINE Developers에서 채널 생성
• Messaging API 설정 필요
WhatsApp ⭐ 쉬움 • QR 코드 스캔으로 연동
• 개인 계정 사용 (비즈니스 API 아님)
iMessage ⭐⭐⭐ 복잡 • macOS 전용, BlueBubbles 앱 필요
• Apple 생태계 사용자용
💡 추천 순서: CLI 먼저 → 채널 나중에

1단계: 채널 없이 CLI에서 먼저 OpenClaw 테스트
openclaw agent --message "안녕하세요!"

2단계: 동작 확인 후, Part 2를 보며 원하는 채널 연동
openclaw configure → 채널 추가

Updated ~/.openclaw/openclaw.json

Workspace OK: ~/clawd

Sessions OK: ~/.openclaw/agents/main/sessions

◇ Skills status ────────────────────────

Eligible: 8

Missing requirements: 41

Blocked by allowlist: 0

◆ Configure skills now? (recommended)

  ● Yes / ○ No

선택 Yes - 스킬 설정으로 OpenClaw 기능 확장
Skills status
Eligible: 8 현재 사용 가능한 스킬 수
Missing requirements: 41 필요 패키지 미설치로 비활성화된 스킬
(Yes 선택 시 필요한 것들을 설치할 수 있음)
Blocked by allowlist: 0 보안 정책으로 차단된 스킬 (없음 = 정상)

 

◇ Configure skills now? (recommended)

  Yes

◆ Preferred node manager for skill installs

  ● npm

  ○ pnpm

  ○ bun

선택 npm - 가장 안정적, 호환성 문제 없음
> 다만 나의 경우 pnpm 을 주로 쓰고 있어서 pnpm으로 선택 하려 한다.
패키지 매니저 특징 추천 대상
npm • Node.js 기본 제공
• 가장 넓은 호환성
• 설치 속도 보통		 대부분의 사용자
pnpm • 빠른 설치 속도
• 디스크 공간 효율적
• 별도 설치 필요		 pnpm 이미 사용 중인 경우
bun • 가장 빠른 속도
• 일부 호환성 이슈 가능
• 실험적		 bun 사용자, 실험적 환경
⚠️ bun 사용 시 주의

bun은 빠르지만 일부 스킬에서 호환성 문제가 발생할 수 있다.
문제가 생기면 openclaw configure에서 npm으로 변경하거나, Node.js로 재설치를 권장한다.

선택 사용할 스킬만 선택 또는 Skip for now
스킬이란?

스킬(Skills)은 OpenClaw의 기능을 확장하는 플러그인이다. 외부 앱/서비스와 연동하여 다양한 작업을 수행할 수 있다.

 

주요 스킬 설명:

스킬 기능 필요 조건
📄 summarize 웹페이지, 문서, 긴 텍스트 요약 추천!
🎤 openai-whisper 음성을 텍스트로 변환 (STT) 추천! OpenAI API 키
💎 obsidian Obsidian 노트 읽기/쓰기 Obsidian 앱 사용자
📝 apple-notes Apple 메모 앱 연동 macOS 전용
⏰ apple-reminders Apple 미리 알림 연동 macOS 전용
✅ things-mac Things 3 할일 관리 연동 Things 3 앱 (유료)
🐻 bear-notes Bear 노트 앱 연동 Bear 앱 (macOS/iOS)
🔐 1password 1Password 비밀번호 조회 1Password CLI
📧 himalaya 이메일 읽기/보내기 himalaya CLI 설치
🎬 video-frames 비디오에서 프레임 추출 ffmpeg 설치
추천 방식: 최소 설치 → 필요할 때 추가

처음에는: summarize, openai-whisper 정도만 선택하거나, Skip for now

나중에: 필요한 스킬이 생기면 openclaw configure에서 추가

스킬은 Part 3에서 자세히 다룰 예정이다.

⚠️ 주의: 스킬 설치에 시간이 걸릴 수 있음

많은 스킬을 선택하면 의존성 설치에 수 분이 소요될 수 있다.
빠르게 시작하고 싶다면 Skip for now를 선택하자.

 

◇ Install missing skill dependencies

  himalaya, 💎 obsidian, 🎤 openai-whisper, 📄 summarize

◇ Installed summarize

◇ Installed openai-whisper

◇ Installed obsidian

◇ Installed himalaya

◆ Set GOOGLE_PLACES_API_KEY for goplaces?

  ○ Yes / ● No

선택 No - 해당 스킬을 사용하지 않으면 Skip
스킬별 API 키 설정 질문

스킬 설치 후, 해당 스킬이 필요로 하는 API 키를 설정할지 물어본다.
설치한 스킬에 따라 여러 번 물어볼 수 있다:

  • GOOGLE_PLACES_API_KEY - goplaces 스킬 (장소 검색)
  • OPENAI_API_KEY - openai-whisper 스킬 (음성 변환)
  • OBSIDIAN_VAULT_PATH - obsidian 스킬 (노트 경로)
  • 기타 스킬별 설정...
질문 패턴 언제 Yes? 언제 No?
Set XXX_API_KEY for YYY? • 해당 스킬(YYY)을 당장 사용할 예정
• API 키를 이미 가지고 있음		 • 해당 스킬을 사용할지 아직 모름
• API 키가 없음
• 나중에 설정할 예정
팁: 나중에 언제든 설정 가능

API 키 설정을 건너뛰어도, 나중에 openclaw configure 또는 환경 변수로 설정할 수 있다.

# 예: 환경 변수로 설정
export OPENAI_API_KEY="sk-..."
export GOOGLE_PLACES_API_KEY="AIza..."

 

◇ Set GOOGLE_PLACES_API_KEY for goplaces? No

◇ Set GEMINI_API_KEY for nano-banana-pro? No

◇ Set OPENAI_API_KEY for openai-image-gen? No

◇ Set OPENAI_API_KEY for openai-whisper-api? No

◇ Set ELEVENLABS_API_KEY for sag? No

◇ Hooks ────────────────────────────────

Hooks let you automate actions when agent commands are issued.

Example: Save session context to memory when you issue /new.

Learn more: https://docs.openclaw.ai/hooks

◆ Enable hooks?

  ☐ Skip for now

  ☐ 🚀 boot-md

  ☐ 📝 command-logger

  ☐ 💾 session-memory

선택 session-memory (추천) 또는 Skip for now
Hooks란?

Hooks는 특정 이벤트가 발생할 때 자동으로 실행되는 동작을 정의한다.
예: 새 세션 시작 시 이전 대화 컨텍스트 저장, 명령어 로깅 등

Hook 기능 추천 대상
session-memory • /new 명령 시 세션 컨텍스트를 메모리에 저장
• 이전 대화 내용을 기억하여 연속성 유지
• Part 5 (Memory & Brain)에서 자세히 다룸		 대부분의 사용자
command-logger • 모든 명령어를 로그 파일에 기록
• 디버깅, 사용 패턴 분석에 유용		 개발자, 디버깅 필요 시
boot-md • 에이전트 시작 시 특정 마크다운 파일 로드
• 커스텀 시스템 프롬프트 설정 가능		 고급 사용자, 커스터마이징
Skip for now • Hooks 없이 기본 상태로 시작
• 나중에 openclaw configure로 추가 가능		 빠르게 시작하고 싶을 때
추천: session-memory 활성화

session-memory는 OpenClaw의 핵심 기능 중 하나다.
이전 대화 내용을 기억하여 "어제 얘기했던 그 프로젝트" 같은 자연스러운 대화가 가능해진다.

자세한 활용법은 Part 5 (Memory & Brain Upgrade)에서 다룬다.

 

◇ Gateway service installed

Agents: main (default)

Heartbeat interval: 30m (main)

Session store (main): ~/.openclaw/agents/main/sessions/sessions.json

◇ Control UI ────────────────────────

Web UI: http://127.0.0.1:18789/

Gateway WS: ws://127.0.0.1:18789

Gateway: reachable

◇ Start TUI (best option!) ────────────

This is the defining action that makes your agent you.

The more you tell it, the better the experience will be.

◆ How do you want to hatch your bot?

  ● Hatch in TUI (recommended)

  ○ Open the Web UI

  ○ Do this later

선택 Hatch in TUI - 터미널에서 바로 시작 (권장)
"Hatch"란?

"Hatch"는 OpenClaw의 첫 대화를 시작하는 것이다.
봇에게 자신을 소개하고, 어떤 역할을 해주길 원하는지 알려주면 더 나은 경험을 제공한다.

옵션 설명 추천 대상
Hatch in TUI • 터미널에서 대화형 인터페이스(TUI) 시작
• 봇과 첫 대화를 나누며 페르소나 설정
• "Wake up, my friend!" 메시지와 함께 시작		 터미널 익숙한 사용자
Open the Web UI • 웹 브라우저에서 Control UI 열기
• http://127.0.0.1:18789/
• 그래픽 인터페이스 선호 시		 GUI 선호, 웹 인터페이스
Do this later • 온보딩만 완료하고 종료
• 나중에 openclaw tui 또는 openclaw dashboard로 시작		 일단 설치만, 나중에 사용

ex) 난 Web UI 선택

ex) 다음과 같은 Web UI가 보이면 정상 설치가 완료된 것 이다.

온보딩 완료!

여기까지 왔다면 OpenClaw 설치가 완료 되었다.

다음 단계:

  • TUI를 선택했다면 바로 CLI에서 봇과 첫 대화 나누기
  • openclaw agent --message "안녕!"으로 CLI 테스트
  • 이후 단계에서는 채널 연동을 해보도록 하자 (Telegram, Discord 등)
접속 정보
Web UI http://127.0.0.1:18789/
Gateway WebSocket ws://127.0.0.1:18789
설정 파일 ~/.openclaw/openclaw.json
로그 파일 ~/.openclaw/logs/gateway.log
토큰 링크 확인 openclaw dashboard --no-open

 

10.1 온보딩 과정에서 묻는 항목 (Manual 선택 시)

Manual 모드를 선택했거나, 나중에 openclaw configure로 설정할 때 나오는 항목들이다.

항목 설명 권장값
게이트웨이 모드 Local vs Remote 선택 Local (개인 사용)
워크스페이스 경로 파일 작업 기본 디렉토리 ~/molt
LLM 제공자 Anthropic / OpenAI 선택 Anthropic (Claude)
채널 설정 WhatsApp, Telegram 등 나중에 추가 가능
데몬 설치 백그라운드 서비스 등록 Yes (권장)
팁: 채널 설정은 나중에

처음 설치할 때는 채널(WhatsApp, Telegram 등) 설정을 건너뛰어도 된다.
CLI에서 직접 테스트한 후, Part 2에서 채널 연동을 다룰 예정이다.

 

10.2 온보딩 완료 후 생성되는 파일

~/.openclaw/
├── openclaw.json      # 메인 설정 파일
├── .env               # API 키 등 환경변수
├── agents/            # 에이전트별 데이터
└── logs/              # 로그 파일

~/molt/               # 워크스페이스 (기본값)

 

12. Step 4: API 키 설정

API 키를 설정하여 통신하는 경우 참고.

 

11.1 Anthropic API 키 (Claude)

권장: Anthropic Claude

공식 문서에서는 Anthropic Pro/Max (Claude Opus 4.5)를 강력히 권장한다.
특히 복잡한 에이전트 작업에서 최상의 결과를 보여준다.

API 키 발급: Anthropic Console에서 발급

# ~/.openclaw/.env 파일에 추가
ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxx

 

11.2 OpenAI API 키 (대안)

API 키 발급: OpenAI Platform에서 발급

# ~/.openclaw/.env 파일에 추가
OPENAI_API_KEY=sk-xxxxxxxxxxxx

 

11.3 추가 API 키 (선택)

기능 환경변수 발급처
웹 검색 BRAVE_API_KEY Brave Search API
음성 합성 (TTS) ELEVENLABS_API_KEY ElevenLabs
Telegram 봇 TELEGRAM_BOT_TOKEN @BotFather
Discord 봇 DISCORD_BOT_TOKEN Discord Developer

 

11.4 Ollama 로컬 LLM (비용 절감 대안)

API 비용 없이 사용하기

Ollama를 사용하면 로컬에서 LLM을 무료로 실행할 수 있다.
특히 간단한 작업이나 테스트 용도로 적합하다.

# 1. Ollama 설치 (https://ollama.com)

# 2. 모델 다운로드
ollama pull llama3.3
# 또는: ollama pull qwen2.5-coder:32b
# 또는: ollama pull deepseek-r1:32b

# 3. OpenClaw에서 Ollama 활성화
export OLLAMA_API_KEY="ollama-local"
# 또는 CLI로 설정
openclaw config set models.providers.ollama.apiKey "ollama-local"

(출처: OpenClaw 공식 문서 - Ollama)

 

11.5 .env 파일 예시

# ~/.openclaw/.env

# LLM API (필수 - 둘 중 하나 이상)
ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxx
OPENAI_API_KEY=sk-xxxxxxxxxxxx

# Ollama 로컬 LLM (선택 - API 비용 절감)
OLLAMA_API_KEY=ollama-local

# 웹 검색 (선택)
BRAVE_API_KEY=BSA-xxxxxxxxxxxx

# 음성 (선택)
ELEVENLABS_API_KEY=xxxxxxxxxxxx

# 채널 (Part 2에서 설정)
# TELEGRAM_BOT_TOKEN=xxxx:xxxx
# DISCORD_BOT_TOKEN=xxxx

 

13. Step 5: 게이트웨이 시작

API 키 설정이 완료되었다면, 게이트웨이를 시작한다.

 

12.1 데몬으로 시작 (권장)

온보딩에서 --install-daemon을 사용했다면, 이미 서비스가 등록되어 있다.

# 상태 확인
openclaw gateway status

# 게이트웨이 재시작 (필요 시)
openclaw gateway restart

# Linux systemd 사용자의 경우
systemctl --user start openclaw-gateway.service
systemctl --user status openclaw-gateway.service

 

12.2 수동으로 시작 (디버깅용)

# 포그라운드에서 실행 (로그 확인 가능)
openclaw gateway --port 18789 --verbose

 

12.3 게이트웨이 상태 확인

# 기본 상태 확인
openclaw status

# 상세 상태 (채널, 세션 포함)
openclaw status --all

# 헬스 체크
openclaw health

# 웹 대시보드 열기 (브라우저)
openclaw dashboard
게이트웨이 정상 작동 확인

openclaw health 또는 openclaw gateway status에서
"Gateway is running" 또는 "Gateway reachable" 메시지가 출력되면 정상이다.

웹 대시보드는 http://127.0.0.1:18789/에서도 직접 접근할 수 있다.

 

14. Step 6: 첫 번째 명령 실행

13.1 CLI에서 직접 명령

# 간단한 질문
openclaw agent --message "안녕하세요, OpenClaw!"

# thinking 모드 활성화 (더 깊은 사고)
openclaw agent --message "오늘 할 일 체크리스트 만들어줘" --thinking high

 

13.2 실제 작업 명령 예시

# 파일 작업 (워크스페이스: ~/molt)
openclaw agent --message "~/molt 폴더에 hello.txt 파일 만들고 '안녕하세요' 라고 써줘"

# 쉘 명령 실행
openclaw agent --message "현재 디렉토리에서 git status 실행해줘"

# 웹 검색 (Brave API 키 필요)
openclaw agent --message "오늘 서울 날씨 검색해줘"

 

13.3 터미널 UI (TUI) 모드

대화형 인터페이스를 원한다면 TUI 모드를 사용할 수 있다.

# 터미널 UI 열기
openclaw tui
축하합니다!

여기까지 따라왔다면, 이제 나만의 Personal AI Agent가 작동하고 있다!

다음 파트에서는 WhatsApp, Telegram, Discord 등 멀티채널 연동을 다룬다.

 

13.4 Pairing 모드 (보안 설정)

기본 보안 정책

OpenClaw는 기본적으로 모르는 사용자의 DM을 처리하지 않는다.
새로운 사용자가 DM을 보내면 pairing 코드가 발급되고, 관리자가 승인해야 한다.

# 대기 중인 pairing 요청 확인
openclaw pairing list

# 특정 채널의 요청만 확인
openclaw pairing list telegram

# pairing 승인
openclaw pairing approve telegram ABC123

 

15. 설정 파일 구조 이해하기

OpenClaw의 동작을 커스터마이징하려면 설정 파일 구조를 이해해야 한다.

14.1 openclaw.json 기본 구조

// ~/.openclaw/openclaw.json (JSON5 형식 - 주석 허용)
{
  "agents": {
    "defaults": {
      "workspace": "~/molt",
      "model": {
        "primary": "anthropic/claude-opus-4-5",
        "fallbacks": ["openai/gpt-4o"]
      }
    }
  },
  "channels": {
    // Part 2에서 자세히 다룸
  },
  "session": {
    "scope": "per-sender",
    "reset": {
      "mode": "idle",
      "idleMinutes": 60
    }
  }
}

 

14.2 주요 설정 항목

섹션 용도
agents 에이전트 기본값 (워크스페이스, 모델, 샌드박스)
channels WhatsApp, Telegram, Discord 등 채널 설정
models 커스텀 LLM 제공자 정의
session 세션 범위 및 리셋 정책
tools 도구 정책 및 접근 제어
auth 인증 프로필 메타데이터

 

14.3 CLI로 설정 변경

# 설정값 조회
openclaw config get agents.defaults.model.primary

# 설정값 변경
openclaw config set agents.defaults.model.primary "anthropic/claude-sonnet-4"

# 대화형 설정 마법사
openclaw configure

 

16. 트러블슈팅

15.1 자동 진단 도구

# 자동 상태 점검
openclaw doctor

# 자동 수정 시도
openclaw doctor --fix

# 보안 감사 (설치 후 반드시 실행 권장)
openclaw security audit --deep
보안 감사 필수 체크 항목

openclaw security audit --deep 실행 시 다음 항목이 점검된다:

• Gateway 바인딩: 127.0.0.1 (로컬)로 설정되어야 함
• gateway.auth.mode: "token" 사용 권장 ("none" 금지)
• 인증 토큰: 32자 이상
• dmPolicy: "allowlist" 또는 "pairing" 권장 ("open" 금지)
• 파일 권한: chmod 600 ~/.openclaw/.env

경고: 2026년 1월 보안 연구에서 인증 없이 노출된 OpenClaw 인스턴스가 발견되었다.
설치 후 반드시 보안 감사를 실행하고, Gateway를 외부에 노출하지 않도록 주의해야 한다.

v2026.2.x 보안 업데이트 사항
  • 인증 필수화: v2026.2.x부터 auth: "none" 설정이 제거되었다. 반드시 token 또는 password 인증을 설정해야 한다.
  • CVE 패치: v2026.1.29에서 Control UI 취약점(토큰 추출 가능) 패치됨. 반드시 최신 버전으로 업데이트할 것.
  • 자동 진단: openclaw doctor --fix 명령으로 설정 문제를 자동 진단하고 수정할 수 있다.

 

15.2 자주 발생하는 문제

증상 원인 해결
"Node.js version too old" Node.js 22 미만 Node.js 22+ 설치
"auth not configured" API 키 미설정 ~/.openclaw/.env 확인
"Gateway not running" 게이트웨이 중지됨 openclaw gateway restart
"Permission denied" 파일 권한 문제 chmod 600 ~/.openclaw/.env
"Rate limit exceeded" API 한도 초과 API 플랜 확인, fallback 모델 설정
WhatsApp/Telegram 연결 오류 Bun 런타임 사용 Node.js로 전환 (Bun 호환성 문제)

 

15.3 로그 확인

# 실시간 로그 확인
openclaw logs --follow

# 로그 파일 위치
ls ~/.openclaw/logs/

 

15.4 커뮤니티 도움 받기

문제가 해결되지 않는다면?

OpenClaw Discord 서버에서 8,900+ 사용자 커뮤니티의 도움을 받을 수 있다.
설치 문제, 설정 방법, Skills 공유 등 다양한 주제가 활발히 논의되고 있다.

 

15.5 홈랩/VPS 배포 팁

장기 운영을 위한 배포 환경

OpenClaw는 메시징 플랫폼 연결을 유지하는 장기 실행 프로세스이다.
노트북보다는 서버 환경이 적합하며, 다음과 같은 옵션을 고려해볼 수 있다:

• VPS: Hetzner (€3-5/월), DigitalOcean/Vultr ($5-6/월)
• 홈랩: Raspberry Pi 4 (2GB+), 중고 노트북, Mac Mini
• 가상화: Proxmox LXC 컨테이너
• Docker: Docker + Docker Model Runner 조합

 

마무리

이 글에서 다룬 내용을 정리하면:

  • Part A - 소개: OpenClaw가란? 왜 Personal AI Agent인가?
  • Part B - 설치: Node.js 22+ → CLI 설치 → 온보딩 → API 키 → 게이트웨이 시작
개인적인 의견

OpenClaw 설치 과정은 다른 AI 도구들에 비해 다소 복잡할 수 있다.
하지만 이 과정을 거치면, 클라우드 서비스에 의존하지 않는 진정한 "내 AI"를 갖게 된다는 점에서 충분히 가치 있다고 생각한다.

ChatGPT로 코드를 받아서 복사-붙여넣기 하던 시대에서, AI에게 "이거 고쳐줘"라고 말하면 알아서 처리되는 시대로의 전환을 경험 해보자. 
다음 섹션에서는 이 OpenClaw를 WhatsApp, Telegram, Discord 등에서 접근할 수 있게 멀티채널 연동을 다뤄 보려고 한다.

참고 자료

공식 자료

(참고: 이전 URL인 docs.molt.bot, docs.clawd.bot은 docs.openclaw.ai로 리다이렉트됩니다)

미디어 리뷰

커뮤니티 & 튜토리얼

도구 설치

300x250
저작자표시 비영리 변경금지 (새창열림)

'AI > OpenClaw(구 Moltbotbot, Clawdbot)' 카테고리의 다른 글

OpenClaw (구 Moltbot, 구 Clawdbot) 리뷰(6) : Ollama 연동 가이드 - 로컬 LLM Ollama로 무료 AI 비서 만들기  (8) 2026.02.02
OpenClaw (구 Moltbot, 구 Clawdbot) 리뷰(5) : Memory 시스템 살펴보기 - OpenClaw는 어떻게 대화를 기억할까?  (2) 2026.02.02
OpenClaw (구 Moltbot, 구 Clawdbot) 리뷰(4) : Moltbot 브라우저 자동화 - AI가 직접 웹을 서핑하는 방법 (Browser Automation 설정, 활용)  (13) 2026.02.01
OpenClaw (구 Moltbot, 구 Clawdbot) 리뷰(3) : OpenClaw Skills 설치 방법(opencode, ohmyopencode 등), 추천 스킬 & 워크플로우 알아보기  (3) 2026.01.30
OpenClaw (구 Moltbot, 구 Clawdbot) 리뷰(2) : 멀티채널 연동 - Telegram, Discord, Slack 한 번에 설정하기  (0) 2026.01.29
Contents

당신이 좋아할만한 콘텐츠

댓글 25

포스팅 주소를 복사했습니다

이 글이 도움이 되었다면 공감 부탁드립니다.

SHARE

DARK

MENU

💡 AI 관련 질문이 있나요? 눌러보세요!

티스토리툴바