# OpenClaw 공식 문서 요약 (docs.openclaw.ai)

**작성일**: 2026-02-05
**작성자**: happybell80
**출처**: docs.openclaw.ai

---

## 1. 개요

- 정의: WhatsApp·Telegram·Discord·iMessage 등 메신저를 하나의 Gateway로 묶는 개인 AI 비서 플랫폼
- 핵심: Pi 코딩 에이전트를 RPC로 연결해 실제 작업 수행
- 변경: Legacy Claude/Codex/Gemini/Opencode 경로 제거, 현재 Pi만 코딩 에이전트로 지원

---

## 2. Docs Hubs 구조

| Hub | 주요 문서 |
|---|---|
| Start here | Getting Started, Onboarding, Wizard, Setup, Configuration |
| Installation | Docker, Nix, Ansible, Updating, Uninstall, Development Channels |
| Core concepts | Architecture, Agent loop, Memory, Sessions, Multi-agent, OAuth, Presence, Channel routing |
| Providers + ingress | Channels(WhatsApp/Telegram/Slack 등), Model providers, Webhooks, Gmail Pub/Sub |
| Gateway + operations | Runbook, Pairing, Doctor, Logging, Sandboxing, Remote, Tailscale, Security |
| Tools + automation | Exec, Browser, Cron, Sub-agents, Skills, ClawHub |
| Nodes, media, voice | Camera, Images, Audio, Voice wake, Talk mode |
| Platforms | macOS, iOS, Android, Windows(WSL2), Linux |
| Workspace | Skills, ClawHub, Templates(AGENTS/SOUL/TOOLS 등) |

---

## 3. Getting Started

- 목표: 0 → 최초 채팅까지 빠르게 진행
- 빠른 채팅: Control UI(`http://127.0.0.1:18789/`)만으로도 가능 (채널 설정 없이)
- 권장 경로: `openclaw onboard --install-daemon` 온보딩 마법사
- 요구사항: Node ≥22, Brave Search API 키 권장
- 순서: (1) CLI 설치 → (2) 온보딩 → (3) Gateway 시작 → (4) 채널 연결(WhatsApp QR 등) → (5) DM pairing 승인

---

## 4. Gateway Architecture

- 역할: 세션·라우팅·채널·도구·이벤트의 단일 진실 원천
- 구성: WebSocket(127.0.0.1:18789) + HTTP(Control UI, WebChat, A2UI)
- 클라이언트: macOS 앱, CLI, Web UI → WS 연결
- Nodes: role: node로 접속, canvas.*, camera.*, screen.record, location.get 등 제공
- 프로토콜: 첫 프레임 connect 필수, 토큰/비밀번호 인증, idempotency key로 재시도 처리

---

## 5. Features

- 채널: WhatsApp(Baileys), Telegram(grammY), Discord, Slack, Mattermost, iMessage(BlueBubbles), Signal, WebChat 등
- 플러그인: Mattermost, LINE, Matrix, Nostr, Twitch, Zalo 등 확장 가능
- 라우팅: 워크스페이스/발신자별 세션 격리
- 미디어: 이미지·음성·문서 송수신
- 앱: Web Control UI, macOS 메뉴바 앱, iOS/Android 노드 + Canvas

---

## 6. Channels

- 지원 채널: WhatsApp(QR), Telegram(봇), Discord, Slack, Feishu, Google Chat, Mattermost, Signal, BlueBubbles(iMessage), iMessage(legacy), MS Teams, LINE, Matrix, Nostr, Twitch, Zalo 등
- 공통 사항: 여러 채널 동시 사용 가능, DM pairing·allowlist로 접근 제어
- 권장: iMessage는 BlueBubbles 사용, Telegram이 초기 설정이 가장 간단

---

## 7. Tools

- 내장 도구: exec, process, web_search, web_fetch, browser, canvas, nodes, image, message, cron, gateway, sessions_* 등
- 프로파일: minimal / coding / messaging / full
- provider별 정책: tools.byProvider로 모델별 도구 제한
- 그룹: group:runtime, group:fs, group:sessions, group:web, group:ui 등
- 플러그인: Lobster, LLM Task 등 추가 도구 등록 가능

---

## 8. Skills

- 형식: AgentSkills 호환, SKILL.md + YAML frontmatter
- 로딩 우선순위: workspace > ~/.openclaw/skills > bundled
- Gating: bins, env, config, os 등으로 로드 시 필터링
- ClawHub: clawhub.com에서 스킬 검색·설치·업데이트
- 설정: skills.entries.<name>.enabled, env, apiKey 등

### 8.1 SKILL.md 메타데이터 예시 (레포 검증)

```yaml
---
name: github
description: "GitHub operations via gh CLI..."
metadata:
  openclaw:
    emoji: "🐙"
    requires: { bins: ["gh"], config: ["channels.slack"] }
    install:
      - { id: "brew", kind: "brew", formula: "gh", bins: ["gh"], label: "Install GitHub CLI (brew)" }
      - { id: "apt", kind: "apt", package: "gh", bins: ["gh"], label: "Install GitHub CLI (apt)" }
---
```

- `requires.bins`: 실행에 필요한 CLI (gh 등)
- `requires.config`: 채널·설정 의존
- `install`: 사용자 설치 가이드 (brew, apt 등)
- `emoji`: UI 표시용

---

## 9. Gateway Runbook

- 실행: `openclaw gateway --port 18789 --verbose`
- 기본값: gateway.bind: loopback, gateway.auth 필수
- Canvas: 18793 포트(기본), canvasHost.enabled=false로 비활성화 가능
- 서비스: launchd(macOS), systemd(Linux/WSL2)
- 원격: Tailscale Serve/Funnel 또는 SSH 터널

---

## 10. Security

- 위협 모델: 셸 실행·파일 접근·네트워크·메시지 전송 가능 → 프롬프트 인젝션·사회공학에 취약
- 원칙: 접근 제어 우선(Identity → Scope → Model)
- DM 정책: pairing(기본), allowlist, open, disabled
- 그룹: requireMention 권장
- 샌드박스: agents.defaults.sandbox.mode: "non-main" 권장
- 브라우저: 전용 프로필 사용, 개인 브라우저 프로필 노출 금지
- 점검: `openclaw security audit --deep`

---

## 11. Help

- 트러블슈팅: docs.openclaw.ai/help/troubleshooting
- FAQ: docs.openclaw.ai/help/faq
- CLI: Doctor, Logging, Debugging, Testing, Scripts

---

## 12. 문서 규모 추정

- Docs Hubs 기준: 약 150+ 페이지 (설치·설정·아키텍처·채널·도구·보안·플랫폼 등)
- 핵심 섹션: Start here, Gateway, Tools, Security, Channels
- 플랫폼 상세: macOS 앱·iOS·Android·Windows·Linux, macOS 내부(메뉴바·Voice wake·Canvas·XPC 등) 별도 문서

---

## 13. 로빙 적용 우선 목록

### 13.1 아키텍처 / Gateway

| 항목 | OpenClaw | 로빙 적용 |
|---|---|---|
| 단일 컨트롤 플레인 | Gateway가 세션·라우팅·이벤트의 단일 소스 | robeing-gateway(8100)에 세션·라우팅 책임 집중 |
| 채널 → 이벤트 전달 | 채널은 메시지만 전달, 라우팅은 Gateway | skill-slack 등은 이벤트만 전달, Gateway가 라우팅·의도 분기 |
| 연결 수명 주기 | connect → hello-ok → agent/presence/tick | JWT 인증 이후 세션 수명·헬스 모델 참고 |

### 13.2 멀티 에이전트 / 존재 분화

| 항목 | OpenClaw | 로빙 적용 |
|---|---|---|
| 워크스페이스별 세션 | 에이전트·워크스페이스별 격리 | 메일·캘린더·리서치·퍼블리싱 등 존재별 세션 분리 |
| 의도 라우팅 | 의도 → 해당 에이전트로 분기 | rb8001 의도 분석 → skill-* 또는 내부 에이전트 호출 |
| sessions_* 도구 | sessions_list, sessions_send, sessions_spawn | 에이전트 간 메시지·태스크 위임 패턴 참고 |

### 13.3 스킬 / skill-* 표준화

| 항목 | OpenClaw | 로빙 적용 |
|---|---|---|
| SKILL.md 포맷 | name, description, metadata(YAML) | skill-별 SKILL.md로 계약·문서 통일 |
| 권한 스코프 | requires.bins, requires.env, requires.config | 권한·환경요구·입출력 스키마 메타데이터 명시 |
| 우선순위 | bundled > managed > workspace | 기본 스킬 vs 사용자 맞춤 스킬 구분 |
| ClawHub 개념 | 스킬 레지스트리·검색·설치 | 로빙 스킬 카탈로그·배포·버전 관리 참고 |

### 13.4 보안 기본값

| 항목 | OpenClaw | 로빙 적용 |
|---|---|---|
| DM pairing | 알 수 없는 발신자 기본 거부 | 메신저 입력 기본 불신, 명시적 allowlist |
| 그룹 requireMention | 언급 시에만 응답 | Slack 채널·멘션 정책에 반영 |
| sandbox 기본값 | 비-main 세션 Docker 샌드박스 | 그룹·외부 입력 처리 시 샌드박스/격리 |
| security audit | openclaw security audit | 설정·토큰·노출점 점검 CLI/스크립트 도입 |
| Credential 분리 | ~/.openclaw/credentials | 채널/스킬 토큰·비밀값 저장 위치·권한 정책 참고 |

### 13.5 도구 / Tools 설계

| 항목 | OpenClaw | 로빙 적용 |
|---|---|---|
| 프로파일 | minimal / coding / messaging / full | 에이전트별 도구 세트(읽기 전용, 전체 등) |
| provider별 정책 | tools.byProvider로 모델별 제한 | rb8001·skill 호출 모델에 따라 도구 제한 |
| 그룹 단축 | group:fs, group:runtime 등 | skill- 호출 허용/차단을 그룹으로 관리 |

### 13.6 채널 / 확장성

| 항목 | OpenClaw | 로빙 적용 |
|---|---|---|
| 플러그인 구조 | openclaw.plugin.json | skill-를 플러그인처럼 등록·설정·활성화 |
| 채널별 설정 | channels.whatsapp.allowFrom 등 | Slack 외 채널 추가 시 동일 패턴 적용 |

### 13.7 UX / 자연어 우선

| 항목 | OpenClaw | 로빙 적용 |
|---|---|---|
| 설정 직접 입력 | Config/Channels에서 폼 입력 | 자연어로 “이거 봇 토큰이야 저장해줘” 같은 UX |
| 온보딩 마법사 | openclaw onboard | 채널·스킬·인증 가이드 흐름 참고 |

### 13.8 운영 / 모니터링

| 항목 | OpenClaw | 로빙 적용 |
|---|---|---|
| Doctor | config/상태 진단·마이그레이션 | robeing 진단 CLI·헬스 체크 확장 |
| Presence | 연결된 클라이언트·노드 목록 | rb8001, skill- 상태·헬스 집계 |
| Troubleshooting Hub | Help → Troubleshooting → FAQ | DOCS/journey/troubleshooting 구조 참고 |

### 13.9 문서 / 템플릿

| 항목 | OpenClaw | 로빙 적용 |
|---|---|---|
| Docs Hubs | Start / Install / Concepts / Help | DOCS 구조화·진입점 분리 |
| AGENTS/SOUL/TOOLS 템플릿 | 시스템 프롬프트용 | rb8001 시스템 프롬프트·스킬 문서 템플릿화 |

---

## 14. 우선순위 제안

1. SKILL.md 스타일 skill-* 문서화 (기존 구조 유지하면서 계약화)
2. Gateway에 세션·라우팅 집중 (채널은 이벤트만 전달)
3. 보안 기본값 (allowlist, requireMention, security audit)
4. 멀티 에이전트 라우팅 (존재별 분기·세션 격리)
5. 자연어 설정 UX (“저장해줘” “연결해줘” 등)
