OpenClaw Onboarding Guide - 5분 설치 가이드

openclaw-onboarding-guide.md

OpenClaw Onboarding Guide

10분 안에 OpenClaw 설치 → 채널 연결 → AI 대화까지

---

사전 준비물

• Git — git-scm.com — git --version으로 확인
• Node.js 24 (22.14+ 가능) — nodejs.org — node --version으로 확인
• AI API 키 — Anthropic / OpenAI / Google 모델 비교
• Claude Code CLI — github.com/anthropics/claude-code — npm i -g @anthropic-ai/claude-code
• Telegram 계정 — telegram.org — 채널 연결 및 모바일 AI 대화용
• Brave Search - api brave.com
• VS Code — 코드 에디터 (code.visualstudio.com)

있으면 좋은 것

• GitHub gh CLI — cli.github.com — gh auth login으로 인증
• OpenAI Codex CLI — OpenAI 코딩 에이전트 — npm i -g @openai/codex
• Google Gemini CLI — Google AI 코딩 에이전트 — npm i -g @google/gemini-cli

---

Windows 사용자: WSL2 설치 먼저

Windows에서는 WSL2 필수. PowerShell(관리자)에서:

wsl --install

재부팅 후 Ubuntu 터미널이 열림.

중요: 이후 모든 명령어(Node.js·Git 설치 포함)는 WSL2 Ubuntu 안에서 실행하세요. Windows 측 Node.js/Git은 별도 설치 불필요합니다.

상세: docs.openclaw.ai/platforms/windows

---

1. 설치

---

# macOS / Linux / WSL2
curl -fsSL https://openclaw.ai/install.sh | bash

보안 참고: 설치 전 스크립트 내용을 확인하려면:

curl -fsSL https://openclaw.ai/install.sh -o install.sh
sha256sum install.sh   # 공식 체크섬과 대조: docs.openclaw.ai/install#checksum
bash install.sh

Docker, Nix, npm 등 다른 방법: docs.openclaw.ai/install

---

2. 온보딩 실행

---

openclaw onboard --install-daemon

약 2분. 아래 항목을 차례로 설정:

단계	내용
Model/Auth	프로바이더 선택 + API 키 입력
Workspace	에이전트 파일 저장 위치 (기본 ~/.openclaw/workspace)
Gateway	포트(18789), 인증, 바인드 설정
Channels	Telegram, Discord, Slack 등 채널 연동
Daemon	자동 시작 서비스 설치

---

3. Gateway 확인

---

openclaw gateway status

listening on port 18789 출력되면 정상.

---

4. 대시보드에서 첫 대화

---

openclaw dashboard

브라우저에 Control UI가 열림 → 채팅창에 메시지 입력 → AI 응답 확인.

---

5. 채널 연결 (Telegram 예시)

---

5-1. 봇 생성

1. Telegram에서 @BotFather 검색
2. /newbot → 이름/유저네임 설정 → 토큰 저장

5-2. 설정

API 키와 봇 토큰은 환경변수 사용을 권장합니다:

export OPENCLAW_TELEGRAM_TOKEN="YOUR_BOT_TOKEN"

또는 openclaw configure 명령어로 설정 (내부적으로 암호화 저장):

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "${OPENCLAW_TELEGRAM_TOKEN}",
      "dmPolicy": "pairing"
    }
  }
}

설정값 참고:

• enabled — 채널 활성화 여부
• botToken — BotFather에서 발급받은 토큰 (환경변수 참조 가능)
• dmPolicy — "pairing": 페어링 코드 승인 필요 / "open": 누구나 DM 가능 / "deny": DM 차단

5-3. 시작 & 페어링

openclaw gateway restart
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

봇에게 DM → 페어링 코드 발급 → approve → 완료!

---

6. 다른 채널

---

채널	문서
Discord	docs.openclaw.ai/channels/discord
Slack	docs.openclaw.ai/channels/slack
WhatsApp	docs.openclaw.ai/channels/whatsapp
Signal	docs.openclaw.ai/channels/signal
iMessage	docs.openclaw.ai/channels/imessage

전체 목록: docs.openclaw.ai/channels

---

주요 명령어 치트시트

openclaw gateway status    # 게이트웨이 상태
openclaw gateway restart   # 재시작
openclaw dashboard         # 웹 대시보드 열기
openclaw configure         # 설정 재구성
openclaw doctor            # 문제 진단
openclaw logs              # 로그 확인
openclaw status            # 전체 상태

---

트러블슈팅

증상	해결
Gateway 안 뜸	openclaw doctor 실행
봇 응답 없음	API 키 확인, openclaw logs로 에러 체크
페어링 만료	코드는 1시간 유효 → 새 DM 보내서 재발급
포트 충돌	config에서 gateway.port 변경

---

참고 링크

• 공식 문서: docs.openclaw.ai
• GitHub: github.com/openclaw/openclaw
• Discord 커뮤니티: discord.gg/clawd

              🦞 OPENCLAW 🦞

┌  OpenClaw setup
│
◇  Security ─────────────────────────────────────────────────────────────────────────────────╮
│                                                                                            │
│  Security warning — please read.                                                           │
│                                                                                            │
│  OpenClaw is a hobby project and still in beta. Expect sharp edges.                        │
│  By default, OpenClaw is a personal agent: one trusted operator boundary.                  │
│  This bot can read files and run actions if tools are enabled.                             │
│  A bad prompt can trick it into doing unsafe things.                                       │
│                                                                                            │
│  OpenClaw is not a hostile multi-tenant boundary by default.                               │
│  If multiple users can message one tool-enabled agent, they share that delegated tool      │
│  authority.                                                                                │
│                                                                                            │
│  If you’re not comfortable with security hardening and access control, don’t run           │
│  OpenClaw.                                                                                 │
│  Ask someone experienced to help before enabling tools or exposing it to the internet.     │
│                                                                                            │
│  Recommended baseline:                                                                     │
│  - Pairing/allowlists + mention gating.                                                    │
│  - Multi-user/shared inbox: split trust boundaries (separate gateway/credentials, ideally  │
│    separate OS users/hosts).                                                               │
│  - Sandbox + least-privilege tools.                                                        │
│  - Shared inboxes: isolate DM sessions (`session.dmScope: per-channel-peer`) and keep      │
│    tool access minimal.                                                                    │
│  - Keep secrets out of the agent’s reachable filesystem.                                   │
│  - Use the strongest available model for any bot with tools or untrusted inboxes.          │
│                                                                                            │
│  Run regularly:                                                                            │
│  openclaw security audit --deep                                                            │
│  openclaw security audit --fix                                                             │
│                                                                                            │
│  Must read: https://docs.openclaw.ai/gateway/security                                      │
│                                                                                            │
├────────────────────────────────────────────────────────────────────────────────────────────╯
│
◆  I understand this is personal-by-default and shared/multi-user use requires lock-down. Continue?
│  ● Yes / ○ No

              🦞 OPENCLAW 🦞 (한국어 번역)

┌  OpenClaw 설정
│
◇  보안 경고 ──────────────────────────────────────────────────────────────────────────────────╮
│                                                                                              │
│  보안 경고 — 반드시 읽어주세요.                                                                │
│                                                                                              │
│  OpenClaw은 개인 프로젝트이며 아직 베타 단계입니다. 거친 부분이 있을 수 있습니다.                    │
│  기본적으로 OpenClaw은 개인 에이전트입니다: 하나의 신뢰된 운영자 경계입니다.                        │
│  이 봇은 도구가 활성화되면 파일을 읽고 작업을 실행할 수 있습니다.                                  │
│  악의적인 프롬프트가 봇을 속여 안전하지 않은 작업을 수행하게 할 수 있습니다.                        │
│                                                                                              │
│  OpenClaw은 기본적으로 적대적 다중 사용자 경계를 제공하지 않습니다.                                │
│  여러 사용자가 도구가 활성화된 하나의 에이전트에 메시지를 보낼 수 있다면,                           │
│  해당 도구 권한을 공유하게 됩니다.                                                              │
│                                                                                              │
│  보안 강화 및 접근 제어에 익숙하지 않다면 OpenClaw을 실행하지 마세요.                              │
│  도구를 활성화하거나 인터넷에 노출하기 전에 경험 있는 사람에게 도움을 요청하세요.                    │
│                                                                                              │
│  권장 보안 기준:                                                                               │
│  - 페어링/허용 목록 + 멘션 게이팅 사용.                                                         │
│  - 다중 사용자/공유 수신함: 신뢰 경계 분리 (별도 게이트웨이/자격증명,                              │
│    가능하면 별도 OS 사용자/호스트).                                                              │
│  - 샌드박스 + 최소 권한 도구 사용.                                                              │
│  - 공유 수신함: DM 세션 격리 (`session.dmScope: per-channel-peer`) 및                           │
│    도구 접근 최소화.                                                                           │
│  - 에이전트가 접근 가능한 파일시스템에 비밀정보를 두지 마세요.                                     │
│  - 도구 또는 신뢰할 수 없는 수신함이 있는 봇에는 가장 강력한 모델을 사용하세요.                     │
│                                                                                              │
│  정기적으로 실행:                                                                              │
│  openclaw security audit --deep                                                              │
│  openclaw security audit --fix                                                               │
│                                                                                              │
│  필독: https://docs.openclaw.ai/gateway/security                                              │
│                                                                                              │
├──────────────────────────────────────────────────────────────────────────────────────────────╯
│
◆  이것이 기본적으로 개인용이며, 공유/다중 사용자 사용 시 보안 잠금이 필요하다는 것을 이해합니다. 계속하시겠습니까?
│  ● 예 / ○ 아니오

Hi, CC. Continuing from WSL session. Need to install Ubuntu 24.04 in WSL.

Why: Current WSL distro is Ubuntu 18.04 (glibc 2.27, EOL). Node 22 requires glibc
2.28+, so nvm install 22 failed with GLIBC_2.28 not found. This blocked the
OpenClaw installer (curl -fsSL https://openclaw.ai/install.sh | bash), which had
been hanging for 6h because Linux-side Node never installed and PATH was picking
up Windows Node from /mnt/c/Program Files/nodejs/ (fails with "exec: node:
Permission denied" from WSL).

Do:

1. wsl --install -d Ubuntu-24.04
2. After first-run user setup: wsl --set-default Ubuntu-24.04
3. Old distro (Ubuntu-18.04) stays; nothing in /home/dkmin migrates automatically
   — ask me if I want to tar anything over.
4. Once in the new distro, install nvm + Node 22, then re-run the OpenClaw
   installer.