OpenClaw 구축·운영 (5/26) — 설치 → Discord 봇 30분 완전판

-

npm 글로벌 설치, 게이트웨이 기동, Discord 봇 페어링, ClawHub에서 스킬 고를 때 체크할 것

핵심 요약

  • 대상 독자: OpenClaw를 처음 쓰는 사용자. 설치 → Discord 연결 → 스킬 1개 설치까지 한 번에 끝내고 싶다.
  • 얻을 것: 공식 openclaw/openclaw GitHub README 기준 verbatim 설치 명령, onboard/gateway 흐름, Discord Developer Portal 봇 세팅 단계, OpenClaw CLI로 토큰 등록·페어링, ClawHub에서 안전한 스킬을 고르는 체크리스트 7개.
  • 선행 조건: Node 22.16+ (24 권장), pnpm 또는 npm, macOS·Linux·WSL2.
  • 중요: OpenClaw는 Codex·Claude Code와 같은 "코딩 CLI"가 아니라 채널 중심 에이전트 오케스트레이터다. Discord/Slack/Telegram 같은 메신저가 Claude·Codex 호출의 "입구"가 된다.

1. OpenClaw가 무엇인가 — 사실만

공식 README 기준 정리.

  • 핵심 개념: "Local-first Gateway" — 세션·채널·도구·이벤트를 하나의 제어 평면으로 통합.
  • 동작 방식: 채널(메신저)에서 온 메시지를 Gateway가 받아 격리된 워크스페이스·세션으로 라우팅.
  • 지원 채널 (README 명시): WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, iMessage, BlueBubbles, IRC, Microsoft Teams, Matrix, Feishu, LINE, Mattermost, Nextcloud Talk, Nostr, Synology Chat, Tlon, Twitch, Zalo, WeChat, QQ, WebChat, 그리고 iOS·Android 컴패니언 앱.
  • 지원 OS: macOS, Linux, Windows(WSL2 경유).

Claude Code/Codex는 IDE·터미널 중심. OpenClaw는 메신저 + 이벤트 허브. 설계 목표가 다르다.

2. 설치 — verbatim 명령

2.1 글로벌 설치 (권장)

npm install -g openclaw@latest
pnpm add -g openclaw@latest

openclaw onboard --install-daemon

--install-daemon은 시스템 부팅 시 자동으로 gateway를 띄우는 데몬을 설치한다. 서버/개인 홈서버에서 24/7 가동하려면 이 옵션 권장.

2.2 소스에서 빌드 (개발용)

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm openclaw setup
pnpm gateway:watch

README는 pnpm을 1차 빌드 툴로 권장 (npm·bun도 동작).

2.3 요구사항

  • Node: 24 권장, 22.16+ 필수
  • pnpm: 소스 빌드 시
  • OS: macOS / Linux / Windows(WSL2)
  • 디스크: 충분 (pnpm node_modules + ClawHub 캐시)

3. 첫 Onboard

openclaw onboard --install-daemon는 대화형 프로세스:

  1. Gateway 경로: 기본 포트 18789 사용 여부 확인
  2. Workspace: ~/.openclaw/workspace/ 생성
  3. 채널 선택: Discord / Slack / Telegram 등 원하는 것 선택(나중 추가 가능)
  4. 에이전트 모델: ~/.openclaw/openclaw.json에 기본 agent.model 기록
  5. Daemon: 시스템 부팅 시 자동 시작 등록

완료 후 ~/.openclaw/openclaw.json:

{
  "agent": {
    "model": "<provider>/<model-id>"
  }
}

예:

{
  "agent": {
    "model": "anthropic/claude-sonnet-4-6"
  }
}

4. Gateway 수동 기동

데몬을 안 쓰고 수동 실행:

openclaw gateway --port 18789 --verbose

첫 실행 시 설치된 채널 어댑터를 로드하고, 등록된 페어링 정보에 따라 각 메신저에 연결한다. 종료는 Ctrl+C.

실시간 로그:

openclaw logs --follow

5. Discord 봇 생성 — Discord Developer Portal

Discord 연결 전 Discord 쪽 설정이 필요하다.

5.1 Application + Bot 생성

  1. Discord Developer Portal → New Application
  2. 생성된 앱 → Bot 섹션 → 사용자명(OpenClaw agent 이름) 설정
  3. Reset Token → 토큰을 복사해 안전한 곳에 저장 (화면을 떠나면 다시 못 봄)

5.2 Intents 활성화

Bot 설정 페이지의 Privileged Gateway Intents:

Intent 필요성
Message Content Intent 필수 (메시지 본문 읽기)
Server Members Intent 권장
Presence Intent 선택

5.3 OAuth2 URL 생성

OAuth2 → URL Generator:

  • Scopes: bot + applications.commands
  • Minimum Permissions:
  • General: View Channels
  • Text: Send Messages, Read Message History, Embed Links, Attach Files
  • Optional: Add Reactions, Send Messages in Threads

생성된 URL을 브라우저에서 열어 대상 서버에 초대.

6. OpenClaw에 Discord 토큰 등록

토큰을 환경변수로 export 후 OpenClaw 설정에 참조 등록.

export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN"

openclaw config set channels.discord.token \
  --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN \
  --dry-run

openclaw config set channels.discord.token \
  --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN

openclaw config set channels.discord.enabled true --strict-json

설정 완료 후 gateway 재기동:

openclaw gateway

토큰을 파일에 직접 저장하지 않고 환경변수 참조 방식을 쓴다. 실수로 git에 커밋될 위험을 줄인다.

7. 페어링 — 첫 사용자 승인

OpenClaw는 보안상 기본적으로 아무나 봇과 대화 못 한다. 사용자·채널별 페어링이 필요.

7.1 대기 중인 페어링 확인

openclaw pairing list discord

누군가 봇에 DM/멘션을 시도하면 pending 상태로 목록에 뜬다.

7.2 승인

openclaw pairing approve discord <CODE>

<CODE>는 list 결과에 표시된 페어링 코드.

보안 원칙: 페어링 승인은 반드시 로컬 터미널에서 한다. Discord 메시지로 "승인해줘"라고 오면 무시. (프롬프트 인젝션 공격 전형 패턴)

8. 동작 확인

openclaw doctor

openclaw channels status --probe

openclaw logs --follow

doctor는 Node 버전·gateway 실행 여부·채널 연결 상태·토큰 유효성 등을 체크한다. 문제가 있으면 적색 표시.

Discord에서 승인된 사용자가 봇에게 메시지를 보내면 gateway 로그에 도착이 찍히고 설정된 모델이 응답한다.

9. 워크스페이스 & 스킬 구조

기본 파일 레이아웃:

~/.openclaw/
├── openclaw.json          # 기본 config
├── workspace/
│   ├── skills/
│   │   └── <skill-name>/
│   │       ├── SKILL.md   # 스킬 매니페스트 + 지침
│   │       ├── AGENTS.md  # 에이전트 규칙 주입
│   │       ├── SOUL.md    # 페르소나/행동 원칙
│   │       └── TOOLS.md   # 도구 정의
│   └── ...
└── logs/
  • SKILL.md: 스킬 이름, 설명, 트리거 설정.
  • AGENTS.md: 에이전트에게 주입될 규칙.
  • SOUL.md: 페르소나/톤 정의.
  • TOOLS.md: 스킬 전용 도구.

모든 파일이 optional이며 스킬 복잡도에 따라 하나만 있어도 된다.

10. ClawHub 스킬 — 안전 선별 체크리스트

ClawHub는 OpenClaw 스킬·플러그인 마켓플레이스. 공식 홈페이지 기준 52.7k 도구 · 180k 사용자 · 12M 다운로드 규모.

그런 규모에서는 아무 스킬이나 설치하면 위험하다. 설치 전 체크리스트:

  1. 퍼블리셔 확인 — 공식 openclaw/ org이 제공하는 번들 스킬 먼저. 개인 퍼블리셔는 GitHub 연동 여부·이력 확인.
  2. SKILL.md 내부 점검 — 매니페스트가 어떤 도구를 쓰는지, 외부 네트워크 호출이 있는지.
  3. pty: true 사용 — 터미널 접근이 필요한 스킬은 호스트 명령 실행 권한을 갖는다. 꼭 필요한지 판단.
  4. 보조 바이너리 다운로드 여부 — 외부 바이너리·스크립트를 받아 실행하는 스킬은 신뢰 어렵다면 피한다.
  5. 시크릿·토큰 수집 — 환경변수나 openclaw config 값을 참조하는 스킬은 그 값의 용도·전송처를 확인.
  6. "security soul" 필터 — ClawHub는 /skills?nonSuspicious=true 같은 filter를 제공. 기본 노출에 포함되지 않은 스킬은 더 경계.
  7. 최근 업데이트 — 마지막 업데이트가 오래된 스킬은 OpenClaw 최신 버전과 호환 깨질 수 있다.

10.1 안전하게 시작할 수 있는 스킬 카테고리

특정 이름보다 카테고리 기준 선택이 안전하다.

카테고리 예시 용도 주의
Coding agent 호출 Claude Code·Codex를 OpenClaw 세션에서 실행 pty:true 또는 --permission-mode bypassPermissions --print 필요
메시지 유틸리티 알림·요약·포워딩 채널 접근권만 있으면 됨. 안전도 높음
파일 유틸리티 읽기·요약·포맷 읽기 전용은 안전, 쓰기는 샌드박스 필수
메모리·FTS 대화 검색·세션 인덱싱 DB 위치 확인. 외부 전송 없어야 함
외부 API 연동 GitHub·Notion·Linear 등 각 서비스 스코프 최소화. read-only 토큰 권장

공식 repo의 openclaw/openclaw/skills/ 하위에 번들로 들어있는 스킬 — 예: coding-agent — 이 가장 안전한 시작점.

10.2 coding-agent 스킬 — 개요

공식 coding-agent SKILL은 feature work·PR 리뷰·리팩터링·반복 작업을 Codex·Claude Code·Pi 백그라운드 에이전트로 위임하는 스킬. 중요 규칙:

  • Codex / Pi / OpenCode: pty: true 필수 (인터랙티브 터미널 필요)
  • Claude Code: --permission-mode bypassPermissions --print 사용, PTY 불필요
  • 실행 패턴: workdir + background + pty 조합

예:

bash pty:true workdir:~/project background:true command:"codex exec --full-auto 'Build a snake game'"

background:true는 세션 ID를 반환, process action:log로 모니터링 가능.

11. 보안 모델 — 기본값의 함정

공식 README 명시:

  • 기본 main 세션은 호스트에서 도구가 전체 권한으로 실행된다.
  • 비-main 세션은 Docker·SSH·OpenShell 백엔드로 샌드박스 가능.
  • 그룹 채팅·채널 안전을 원하면 config에:
{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main"
      }
    }
  }
}

Discord 서버에 봇을 붙여 여러 사람과 공유할 계획이면 이 설정은 거의 필수. 기본값으로 그냥 두면 임의 사용자가 호스트에서 임의 명령을 실행할 수 있다.

12. 업데이트 채널

openclaw update --channel stable|beta|dev
  • stable: 태그된 릴리즈 (npm latest)
  • beta: 프리릴리즈
  • dev: 최신 커밋 추적 (실험적)

개인 개발/테스트: beta. 프로덕션 서버: stable.

13. 반대 시나리오 — OpenClaw를 쓰지 말아야 할 때

  • 로컬 IDE 안에서만 AI 쓰고 싶다 → Claude Code / Codex가 적합. OpenClaw는 오버킬.
  • 메신저 연동이 필요 없다 → Gateway·Channel 개념이 불필요. Claude Code + MCP 서버 조합이 가벼움.
  • 공개 서버에서 다수 사용자에게 열고 싶은데 샌드박스 세팅이 부담 → 기본 설정 위험. non-main 샌드박스 설정 완전히 이해 후 도입.
  • Node 환경을 유지하고 싶지 않다 → 현재 경로는 Node 기반. Rust 기반(Codex)이나 네이티브(Claude Code) 대체.

14. 30분 요약 체크리스트

  • [ ] Node 22.16+ 또는 24 설치 확인 (node --version)
  • [ ] npm install -g openclaw@latest 실행
  • [ ] openclaw onboard --install-daemon으로 초기 세팅
  • [ ] Discord Developer Portal에서 앱·봇 생성 + Intents 활성화 + OAuth2 URL로 서버 초대
  • [ ] export DISCORD_BOT_TOKEN=... → openclaw config set channels.discord.token ...
  • [ ] openclaw config set channels.discord.enabled true --strict-json
  • [ ] openclaw gateway 기동 → 봇 멘션해서 페어링 pending 발생
  • [ ] openclaw pairing list discord → openclaw pairing approve discord <CODE>
  • [ ] 봇에 DM해서 응답 확인 → openclaw doctor로 최종 점검
  • [ ] ClawHub 방문 → 체크리스트 통과하는 스킬 1개만 먼저 설치

15. 다음 단계

OpenClaw 기본이 잡혔다면:

  1. OpenClaw 프로덕션 운영 — systemd · 로그 · 멀티 채널 공존 (예정)
  2. OpenClaw ↔ Claude Code 브릿지 — 채널 트리거 → 코드 실행 (예정)
  3. Claude Code 설치 완전판 — OpenClaw 안에서 호출되는 coding agent 쪽 기초.

참고

이 글은 "AI 코딩 CLI 진입 가이드" 시리즈의 9/15 편입니다. OpenClaw 파트 시작. last verified: 2026-04-25 (openclaw/openclaw 공식 GitHub README 기준).

시리즈 전체 안내: 시리즈 목차

댓글

댓글 쓰기

이 블로그의 인기 게시물

"LLM 핵심 학습 (1/6) — 기본: 토큰화·임베딩·어텐션·위치 인코딩"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/6 파인튜닝 → 트랜스포머 한 블록의 데이터 흐름을 문자열 → 토큰 → 임베딩 → 어텐션 → 출력 표현 까지 손으로 풀어 본다. 이번 편이 끝나면 "왜 \(\sqrt{d_k}\)로 나누는가", "RoPE는 무엇을 회전시키는가", "한국어가 영어보다 토큰이 많은 까닭은 무엇인가"가 한 줄로 설명될 수 있다. 0. 학습 목표 이 편을 마치면 다음을 직접 할 수 있다. BPE 토크나이저 가 어휘를 어떻게 학습하고 새 문자열을 어떻게 자르는지 종이 위에서 시뮬레이션한다. 임베딩 행렬 의 모양과 초기화, weight tying의 의미를 한 줄로 설명한다. Scaled Dot-Product Attention 의 식을 차원 단위로 추적하고 PyTorch 30줄로 재현한다. Multi-Head Attention 이 한 헤드와 비교해 무엇이 다른지, 헤드 수가 늘면 어디가 비싸지는지 답한다. Sinusoidal·RoPE·ALiBi 세 위치 인코딩의 식과 외삽 성질을 구분한다. 컨텍스트 확장이 왜 \(O(N^2)\)인지, "Lost in the Middle"이 왜 발생하는지 설명한다. 1. 핵심 요약 트랜스포머의 입력은 문자열 이 아니라 정수 ID 시퀀스 다. 토크나이저가 문자열 → ID로 자른다. 임베딩은 정수 ID를 \(d\)차원 벡터로 lookup하는 학습 가능한 테이블이다. Self-Attention은 \(\text{softmax}(QK^\top / \sqrt{d_k}) V\) 한 줄이 핵심이고, 멀티헤드는 같은 연산을 여러 부분 공간에서 병렬화한 것이다. 위치 정보는 임베딩에 직접 더하거나(Sinusoidal), Q·K에 회전을 가하거나(RoPE), 어텐션 스코어에 거리 패널티를 더해서(ALiBi) 주입한다. 컨텍스트 길이 \(N\)에 대해 표준 어텐션은 \(O(N^2)\) 비용을 갖고, 긴 컨텍스트에서는 중간 위...
Read more »

"LLM 핵심 학습 (2/6) — 파인튜닝: LoRA·QLoRA·증류·Adapter"

-
이미지
← 1/6 기본 📚 시리즈 목차 3/6 디코딩과 생성 → 사전학습된 LLM을 내 데이터 에 적응시키는 방법을 비용·메모리·일반화 관점에서 정리한다. Full FT의 한계 → Adapter → LoRA → QLoRA → Distillation 순으로 같은 그림을 점점 확대해 본다. 0. 학습 목표 Full fine-tuning의 메모리 병목을 옵티마이저 상태·그래디언트·가중치·활성화 의 4분할로 설명한다. Adapter(Houlsby 2019)와 LoRA(Hu 2021)의 식 차이를 한 줄로 적는다. LoRA의 \(A, B\) 행렬이 왜 저랭크 이고, rank \(r\) 선택이 무엇을 결정하는지 답한다. QLoRA(Dettmers 2023)의 NF4·double-quant·paged optimizer를 분리해서 설명한다. Catastrophic Forgetting을 분포 시프트 관점에서 정의하고 완화 기법을 두 개 이상 든다. Hinton 2015의 Knowledge Distillation 식을 손으로 유도한다. 1. 핵심 요약 Full FT는 메모리/디스크/시간 모두 비싸다. 7B 모델 full FT는 V100 8장 + A100 1장으로도 큰 부담이다. PEFT(파라미터 효율 파인튜닝) 일가족은 극히 일부 파라미터만 학습 해 같은 효과를 얻는다. LoRA: \(\Delta W = BA\) (rank \(r \ll \min(d_{\text{in}}, d_{\text{out}})\))로 가중치 업데이트를 저랭크 분해. QLoRA: 베이스 모델을 4-bit(NF4)로 양자화한 채 LoRA만 풀-정밀(BF16)으로 학습. Catastrophic Forgetting: 새 분포에 적응하느라 이전 능력이 무너지는 현상. PEFT 자체가 부분 완화책. Distillation: 큰 교사 모델의 soft target 을 학습 신호로 써서 작은 학생 모델 을 만든다. 2. 직관: 왜 사전학습만으로는 부족한가 사전학습은 일반...
Read more »

"ML 기초 학습 (1/9) — 머신러닝과 sklearn: 학습의 좌표계"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/9 이웃 알고리즘 → 이 시리즈는 신경망과 로컬 LLM으로 가기 전에 손에 익혀 둬야 할 머신러닝 기초 9편이다. 1편은 모든 ML 코드가 공유하는 공통 문법 을 잡는 데 쓴다. sklearn은 그 문법을 가장 일관되게 보여주는 도구다. 이번 편이 끝나면 어떤 모델을 만나도 fit → predict → score → 평가 흐름이 같다는 것이 손에 잡힌다. 0. 학습 목표 이 편을 마치면 다음을 할 수 있어야 한다. 지도학습·비지도학습·강화학습을 한 문장씩 구분해 설명한다. sklearn의 estimator 인터페이스 ( fit , predict , score , transform )를 코드 한 화면 안에서 쓸 수 있다. train/validation/test 분할을 왜 하는지, 어디서 데이터 누수가 생기는지 식과 그림으로 설명한다. 분류·회귀의 핵심 평가 지표(accuracy, precision, recall, F1, MSE, R²)를 정의에서 직접 계산할 수 있다. k-fold 교차검증 을 코드 한 줄로 돌리고, 결과의 평균과 표준편차를 함께 보고할 수 있다. Pipeline 으로 전처리와 모델을 묶어 데이터 누수를 구조적으로 막는 방법을 설명한다. 1. 핵심 요약 머신러닝은 데이터에서 함수 \(f: X \to Y\)를 찾는 작업 이다. 어떤 모델이든 이 본질은 같다. sklearn은 모든 모델을 같은 인터페이스( fit , predict , score )로 통일해, 모델을 바꿀 때 한 줄만 바꾸면 되게 한다. train/val/test 세 분할이 표준이다. 검증으로 하이퍼파라미터를 고르고, 테스트는 마지막에 한 번만 본다. 데이터 누수 (test 정보가 train에 새는 현상)는 ML 입문자가 가장 자주 만드는 실수이며, Pipeline + cross_val_score 조합으로 구조적으로 막을 수 있다. 평가 지표는 문제 유형 (분류/회귀) 과 클래스 불균형...
Read more »