openclaw: 공식 문서 기반 매뉴얼 전면 재작성

기존 2개 섹션(4/8, 6/8)에서 14개 섹션 완전 체계로 확장:
1. 개요/설치, 2. 아키텍처, 3. 에이전트 런타임, 4. 도구,
5. 스킬, 6. 플러그인, 7. 세션, 8. 채널, 9. 게이트웨이,
10. 메모리, 11. 멀티에이전트, 12. 하트비트, 13. 자동화, 14. 보안

출처: https://docs.openclaw.ai/

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

openclaw/openclaw-manual.md

@@ -1,60 +1,250 @@
 ---
 title: OpenClaw 매뉴얼
-updated: 2026-03-12
+updated: 2026-03-18
+tags: [openclaw, agent, ai]
 ---
 
-## 도구/스킬/플러그인 시스템 (4/8)
+공식 문서: https://docs.openclaw.ai/
 
-[OpenClaw 매뉴얼 4/8 - 도구/스킬/플러그인 시스템]
+## 1. 개요 및 설치
-도구 시스템:
-- 프로필: minimal|coding|messaging|full (agents.defaults.tools 또는 per-agent)
-- exec 보안: deny(기본)|allowlist|full
-- exec 설정: backgroundMs:10000, timeoutSec:1800
-- 루프 감지: historySize:30, warningThreshold:10, criticalThreshold:20
-- 웹 도구: tools.web.search(Brave API)/tools.web.fetch
-- 미디어 도구: tools.media.audio/video (whisper, gemini 등)
-- 에이전트 간 통신: tools.agentToAgent.enabled
-- 서브에이전트: tools.subagents.model/maxConcurrent/runTimeoutSeconds
 
-스킬 시스템:
+오픈소스 AI 에이전트 프레임워크. 메시징 앱(WhatsApp, Telegram, Discord, Slack, Signal, iMessage 등)을 통해 LLM과 대화하고, 셸 명령, 브라우저 자동화, 이메일, 파일 작업 등을 자율 수행.
-- 위치: workspace/skills/ > ~/.openclaw/skills/ > bundled (우선순위)
-- 매니페스트: skills/{name}/SKILL.md (YAML frontmatter)
-- 필드: name, description, user-invocable, metadata(requires.bins/env/config/os)
-- ClawHub: npx clawhub install/update/sync
-- 현재 IronDesk: 3/51 ready (healthcheck, skill-creator, weather)
 
-플러그인 시스템:
+**설치:**
-- 명령: openclaw plugins list|info|install|enable|disable|doctor
+```bash
-- 매니페스트: openclaw.plugin.json (id, configSchema 필수)
+# macOS/Linux
-- 슬롯: plugins.slots.memory/contextEngine
+curl -fsSL https://openclaw.ai/install.sh | bash
-- 현재 loaded: device-pair, memory-core, phone-control, talk-voice, telegram (5개)
-- memory-lancedb: disabled (벡터 검색용, 임베딩 API 키 필요)
 
-## 세션/채널/게이트웨이 관리 (6/8)
+# 온보딩 (인증, 게이트웨이, 채널 설정)
+openclaw onboard --install-daemon
+```
 
-[OpenClaw 매뉴얼 6/8 - 세션/채널/게이트웨이 관리]
+**요구사항:** Node 24 권장 (22.16+ 호환)
-세션 관리:
-- dmScope: main(기본, 전체공유)|per-peer|per-channel-peer(IronDesk 현재 설정)|per-account-channel-peer
-- 세션 키: agent:{agentId}:{mainKey} 또는 agent:{agentId}:dm:{peerId}
-- 그룹: agent:{agentId}:{channel}:group:{id}, 텔레그램 토픽: ...group:{id}:topic:{threadId}
-- 리셋: session.reset.mode=daily(atHour:4)|idle(idleMinutes:60), resetTriggers:["/new","/reset"]
-- 저장소: ~/.openclaw/agents/{agentId}/sessions/sessions.json
-- 유지보수: pruneAfter:30d, maxEntries:500, maxDiskBytes:500mb
-- 채팅 명령: /new, /reset, /status, /context list|detail, /compact
 
-채널:
+**환경변수:**
-- Telegram: botToken, dmPolicy(pairing|allowlist|open|disabled), streaming(off|partial|block|progress), groups, topics
+- `OPENCLAW_HOME`: 홈 디렉토리
-- Discord: token, guilds, channels, voice, thread bindings, reactions
+- `OPENCLAW_STATE_DIR`: 상태 디렉토리
-- WhatsApp: dmPolicy, allowFrom, textChunkLimit, sendReadReceipts
+- `OPENCLAW_CONFIG_PATH`: 설정 파일 경로
-- Slack: socketMode 또는 HTTP, slash commands
-- Signal, iMessage, IRC, Matrix, Mattermost, MS Teams, LINE, Google Chat 등
 
-게이트웨이:
+## 2. 아키텍처
-- mode: local|remote, port:18789(기본)
+
+게이트웨이(Gateway)가 중앙 데몬으로 모든 메시징 채널을 관리. 호스트당 1개만 존재. 기본 `127.0.0.1:18789`.
+
+```
+채널(WhatsApp/Telegram/Discord...) ← WebSocket → 게이트웨이 ← WebSocket → 클라이언트(CLI/macOS앱/웹UI)
+                                                      ↕
+                                                   노드(macOS/iOS/Android)
+```
+
+**구성요소:**
+- **게이트웨이**: 메시징 연결 유지, WebSocket API, JSON Schema 검증
+- **클라이언트**: 게이트웨이에 WebSocket 연결, `send`/`agent`/`status` 요청
+- **노드**: `role: node`로 연결, 기기 ID 기반 페어링, camera/screen 등 명령
+
+**연결 프로토콜:**
+- 첫 프레임은 반드시 `connect` 요청
+- 요청/응답: `{type:"req", id, method, params}` ↔ `{type:"res", id, ok, payload}`
+- 이벤트: `{type:"event", event, payload}`
+- 보안: 새 기기는 페어링 승인 필요, 로컬은 자동 승인
+- 원격: Tailscale/VPN 또는 SSH 터널 (`ssh -N -L 18789:127.0.0.1:18789 user@host`)
+
+## 3. 에이전트 런타임
+
+pi-mono 기반 단일 임베디드 에이전트 런타임. 세션 관리와 도구 연동은 OpenClaw가 직접 담당.
+
+**워크스페이스 구조:**
+- `AGENTS.md` — 운영 지침 및 메모리
+- `SOUL.md` — 페르소나, 경계, 톤
+- `TOOLS.md` — 도구 사용법 가이드
+- `IDENTITY.md` — 에이전트 이름/이모지
+- `USER.md` — 사용자 프로필
+- `BOOTSTRAP.md` — 일회성 초기화 (완료 후 삭제)
+- `HEARTBEAT.md` — 하트비트 체크리스트 (선택)
+
+**모델 참조:** `provider/model` 형식 (예: `anthropic/claude-opus-4-6`)
+
+**설정 파일:** `~/.openclaw/openclaw.json` (JSON5)
+
+## 4. 도구 시스템
+
+도구 접근 제어: `tools.allow`/`tools.deny` (deny 우선)
+
+**프로필:**
+- `minimal`: 세션 상태만
+- `coding`: 파일시스템, 런타임, 세션, 메모리, 이미지
+- `messaging`: 메시징 관련
+- `full`: 제한 없음
+
+**핵심 도구:**
+
+| 카테고리 | 도구 | 기능 |
+|----------|------|------|
+| 파일/실행 | exec, process, read, write, edit, apply_patch | 셸 명령, 백그라운드 관리, 파일 조작 |
+| 웹 | web_search, web_fetch | Brave/Firecrawl 검색, URL 콘텐츠 추출 |
+| UI 자동화 | browser, canvas | 브라우저 제어, 캔버스 드라이브 |
+| 노드 | nodes, device_status | 페어링 노드, 카메라/화면 캡처 |
+| 메시징 | message | Discord/Slack/Telegram/WhatsApp 메시지 전송 |
+| 세션 | sessions_list, sessions_history, sessions_send, sessions_spawn | 세션 관리, 서브에이전트 |
+| 이미지 | image, image_generate, pdf | 이미지 분석/생성, PDF 분석 |
+| 자동화 | cron, gateway | 크론 작업, 게이트웨이 설정 |
+
+**도구 그룹:** `group:fs`, `group:runtime`, `group:sessions`, `group:web`, `group:ui`
+
+## 5. 스킬 시스템
+
+AgentSkills 호환 스킬 폴더. 각 스킬은 `SKILL.md` (YAML frontmatter) 포함 디렉토리.
+
+**로드 우선순위:** 워크스페이스 `skills/` > `~/.openclaw/skills/` > 번들
+
+**SKILL.md 형식:**
+```yaml
+---
+name: 스킬-이름
+description: 설명
+user-invocable: true
+metadata: { "openclaw": { "requires": { "bins": [], "env": [], "config": [] }, "os": ["darwin","linux"] } }
+---
+스킬 본문 (사용법, 도구 호출 가이드)
+```
+
+**설정 오버라이드:** `openclaw.json`의 `skills.entries`에서 활성화/비활성화, API 키, 환경변수 주입
+
+**ClawHub:** 공개 스킬 레지스트리 — `clawhub install/update/sync`
+
+## 6. 플러그인 시스템
+
+- 매니페스트: `openclaw.plugin.json` (id, configSchema 필수)
+- 슬롯: `plugins.slots.memory` (기본: memory-core), `contextEngine`
+- 명령: `openclaw plugins list|info|install|enable|disable|doctor`
+- 플러그인은 자체 스킬 디렉토리 배포 가능
+
+## 7. 세션 관리
+
+**dmScope** (DM 격리 방식):
+
+| 값 | 동작 |
+|----|------|
+| `main` (기본) | 모든 DM 주 세션 공유 |
+| `per-peer` | 발신자 ID로 격리 |
+| `per-channel-peer` | 채널+발신자로 격리 (다중 사용자 필수) |
+| `per-account-channel-peer` | 계정+채널+발신자로 격리 |
+
+**세션 키 체계:**
+- DM: `agent:<agentId>:main` 또는 `agent:<agentId>:direct:<peerId>`
+- 그룹: `agent:<agentId>:<channel>:group:<id>`
+- Telegram 토픽: `...group:<id>:topic:<threadId>`
+- Cron: `cron:<job.id>`, 웹훅: `hook:<uuid>`
+
+**리셋 정책:**
+- `daily` (기본, atHour:4) 또는 `idle` (idleMinutes)
+- `/new`, `/reset` 명령으로 즉시 리셋
+- `resetByType`으로 direct/group/thread별, `resetByChannel`로 채널별 재정의
+
+**유지보수:** pruneAfter:30d, maxEntries:500, maxDiskBytes:500mb (mode: warn|enforce)
+
+**저장소:** `~/.openclaw/agents/<agentId>/sessions/sessions.json`
+
+## 8. 채널
+
+각 채널은 `openclaw.json`에 설정 섹션이 있으면 자동 시작.
+
+**DM 정책:** pairing(기본)|allowlist|open|disabled
+
+**주요 채널:**
+- **Telegram**: botToken, streaming(off|partial|block|progress), groups, topics
+- **Discord**: token, guilds, channels, voice, thread bindings
+- **WhatsApp**: dmPolicy, allowFrom, textChunkLimit, mediaMaxMb
+- **Slack**: botToken + appToken (Socket Mode), slash commands
+- **Signal, iMessage, IRC, Matrix, Mattermost, MS Teams, LINE, Google Chat, Nostr, Twitch, Zalo** 등
+
+## 9. 게이트웨이
+
+- mode: local|remote, port: 18789
 - bind: loopback|lan|tailnet|custom|auto
 - auth: none|token|password|trusted-proxy
 - Tailscale: mode=off|serve|funnel
-- 서비스: openclaw gateway install|start|stop|restart|status|uninstall
+- 서비스: `openclaw gateway install|start|stop|restart|status|uninstall`
-- RPC: openclaw gateway call {method} --params {json}
+- RPC: `openclaw gateway call {method} --params {json}`
-- 헬스: openclaw gateway health|probe|discover
+- 헬스: `openclaw gateway health|probe|discover`
-- HTTP 엔드포인트: chatCompletions, responses (OpenAI 호환)
+- HTTP API: chatCompletions, responses (OpenAI 호환)
+- Control UI: `openclaw dashboard` 또는 `http://127.0.0.1:18789/`
+
+## 10. 메모리 시스템
+
+평문 마크다운 파일이 유일한 진실 공급원.
+
+**파일 구조:**
+- `memory/YYYY-MM-DD.md` — 일일 로그 (추가 전용)
+- `MEMORY.md` — 장기 메모리 (정선된 지속 정보)
+
+**메모리 도구:** `memory_search` (벡터 검색), `memory_get` (파일 읽기)
+
+**벡터 검색:**
+- 기본 활성화, 마크다운 변경 자동 감시
+- 제공자: local(node-llama-cpp) → openai → gemini → voyage → mistral
+- 하이브리드 검색: BM25(30%) + 벡터(70%)
+- 시간 감쇠: 반감기 30일 (MEMORY.md는 감쇠 없음)
+
+**메모리 플러시:** 컴팩션 전 자동으로 메모리 저장 트리거 (softThresholdTokens: 4000)
+
+## 11. 멀티 에이전트
+
+각 에이전트는 독립된 워크스페이스, 세션, 인증 프로필 보유.
+
+**설정:**
+```json5
+agents: {
+  list: [
+    { id: "home", workspace: "~/.openclaw/workspace-home" },
+    { id: "work", workspace: "~/.openclaw/workspace-work" }
+  ]
+},
+bindings: [
+  { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
+  { agentId: "work", match: { channel: "discord", guildId: "123" } }
+]
+```
+
+**라우팅 우선순위:** peer > parentPeer > guildId+roles > guildId > teamId > accountId > channel > 기본
+
+**에이전트 관리:** `openclaw agents add|list|remove`, 에이전트별 샌드박스/도구 제한 가능
+
+## 12. 하트비트
+
+정기적 에이전트 실행으로 백그라운드 작업/상태 확인 자동화.
+
+**설정:**
+```json5
+heartbeat: {
+  every: "30m",
+  activeHours: "09:00-22:00",
+  model: "openai/gpt-5.2-mini",
+  to: "last",
+  isolatedSession: true
+}
+```
+
+- `HEARTBEAT_OK` 응답 시 자동 제거 (알림 없음)
+- `isolatedSession: true`로 토큰 100K → 2-5K 절감
+- `HEARTBEAT.md` 파일로 체크리스트 관리
+
+## 13. 자동화
+
+- **Cron**: `openclaw cron list|add|remove`, 게이트웨이 내장 스케줄러
+- **Hooks**: 이벤트 기반 트리거 (automation/hooks)
+- **Webhooks**: 외부 서비스 연동 (automation/webhook)
+- **Polls**: 주기적 외부 상태 확인 (automation/poll)
+- **Gmail PubSub**: Gmail 실시간 알림 (automation/gmail-pubsub)
+
+## 14. 보안 및 샌드박싱
+
+**샌드박스 모드:**
+- `off`: 제한 없음
+- `non-main`: 메인 에이전트 외 샌드박스 적용
+- `all`: 모든 에이전트 샌드박스
+
+**도구 정책:** exec deny(기본)|allowlist|full
+
+**기기 페어링:** 새 기기는 승인 필요, 로컬은 자동, 원격은 명시적
+
+**스킬 보안:** 제3자 스킬은 신뢰할 수 없는 코드로 취급, 활성화 전 검토 필수