🚀 OpenClaw 설치 가이드 — 처음 시작하기

나만의 AI 비서를 만들어보세요 🐱

OpenClaw는 당신의 일상과 업무를 돕는 AI 에이전트 프레임워크입니다. 이 가이드는 처음 시작하는 분들도 설치부터 텔레그램 연결까지 따라할 수 있도록 안내합니다.

📋 목차

  1. 사전 준비
  2. Quick Start 진행
  3. 텔레그램 봇 만들기 & 연결
  4. 첫 대화 테스트
  5. 다음 단계
  6. 트러블슈팅

1. 사전 준비

필수

  • macOS, Linux, 또는 Windows (WSL 권장)
  • Node.js 18+ 설치
  • Claude API 키 (console.anthropic.com)
    • Opus 또는 Sonnet 모델 사용 권장
    • API 크레딧 $5 정도면 충분히 테스트 가능
  • 텔레그램 계정 (봇과 대화하기 위해)

선택 (권장)

  • Gemini API 키 (ai.google.dev)
    • 웹 검색 기능 활성화용
    • 무료 티어로도 충분히 사용 가능

2. Quick Start 진행

OpenClaw 설치

npm install -g openclaw

초기 설정 마법사 실행

openclaw setup

마법사가 단계별로 질문합니다. 아래를 참고하세요:

2.1 Claude 구독 연결

→ Claude API 키 입력 → Sonnet 4.5 추천 (빠르고 저렴하면서 충분히 강력)

2.2 Search Provider 설정

→ Yes (웹 검색 활성화) → Gemini 선택 → Gemini API 키 입력

2.3 스킬 설치

→ No 선택 (나중에 필요할 때 설치)

처음엔 스킬 없이 시작하세요. 나중에 필요한 기능이 생기면 에이전트에게 물어보면 알아서 안내해줍니다!

"웹 페이지 크롤링하는 스킬 있어?"
"GitHub 이슈 관리 도와주는 스킬 설치해줘"

2.4 Hooks 설정

→ session-memory only 선택

session-memory hook은 대화 맥락을 기억하도록 도와줍니다. 이건 켜두세요.

2.5 Hatchet TUI

→ recommend 선택

설정 완료! 🎉

3. 텔레그램 봇 만들기 & 연결

텔레그램이 가장 쉬운 채널입니다! 📱

3.1 봇 만들기

  1. 텔레그램에서 @BotFather 검색
  2. /newbot 입력
  3. 봇 이름 입력 (예: 내 AI비서)
  4. 유저네임 입력 (예: myopenclaw_bot)
    • 전세계에서 유일해야 함
    • 반드시 bot으로 끝나야 함
  5. API 토큰 복사 (예: 7123456789:AAF-xxxxx)

3.2 OpenClaw에 연결

openclaw channels add --channel telegram --token "봇토큰_붙여넣기"

3.3 페어링 (봇과 나를 연결하기)

텔레그램 봇에게 처음 말을 걸면 서로 코드를 교환해서 연결합니다:

  1. 텔레그램에서 봇 검색 → /start 또는 아무 메시지 전송
  2. 봇이 셋업 코드를 보내줌 → 이걸 터미널에 입력
  3. 터미널에 페어링 코드가 표시됨 → 이걸 텔레그램 봇 DM에 입력
[텔레그램] 봇이 셋업 코드 보냄 (예: SETUP-XXXX)
    ↓ 터미널에 입력
[터미널] 페어링 코드 표시됨 (예: ABC123)
    ↓ 텔레그램 봇 DM에 입력
[완료!] 🎉

또는 터미널에서 직접 승인할 수도 있어요:

openclaw pairing approve telegram <코드>

💡 페어링이란? 아무나 봇에게 말 걸면 안 되니까, 처음 한 번 “이 사람은 허용된 사용자야”라고 승인하는 과정이에요. 한 번만 하면 됩니다.

4. 첫 대화 테스트

텔레그램에서 봇에게 메시지 보내기:

안녕? 자기소개해줘

봇이 답장하면 성공! 🎉

5. 다음 단계

워크스페이스 꾸미기

에이전트의 성격과 역할을 정의할 수 있습니다:

  • SOUL.md — 에이전트의 성격, 역할, 말투 (예: “나는 ○○야, 간결하고 실용적인 비서.”)
  • USER.md — 사용자(나) 정보 (이름, 직업, 선호 스타일)
  • MEMORY.md — 에이전트의 장기 기억
# 워크스페이스 위치 확인
ls ~/.openclaw/workspace/

멀티에이전트로 확장

에이전트 1개로 시작했다면, 역할을 나눠서 AI 비서 팀을 만들 수 있어요!

👉 워크스페이스 구조와 멀티에이전트 셋업 가이드에서 자세히 다룹니다.

더 나아가기

  • 스킬 설치: 에이전트에게 “GitHub 관리 스킬 설치해줘” 요청
  • 자동화: 크론잡으로 주기적 보고 받기
  • MCP 연동: Google Sheets, Notion, Linear 같은 도구 연결

6. 트러블슈팅

봇이 응답하지 않아요

  1. openclaw gateway status — 게이트웨이 실행 중인지 확인
  2. botToken이 정확한지 확인
  3. 로그 확인: openclaw gateway logs

API 비용이 걱정돼요

  • Sonnet 4.5 사용 (Opus보다 10배 저렴)
  • Gemini Flash (무료)를 웹 검색용으로 활용

에이전트가 기억을 못 해요

  • session-memory hook이 활성화됐는지 확인
  • 에이전트에게 “이거 기억해줘” 또는 “MEMORY.md에 저장해줘” 요청

커뮤니티

마지막 업데이트: 2026-03-23