From 71a1e08a476ce0e25156258d505b9d7d8c494ccc Mon Sep 17 00:00:00 2001 From: kappa Date: Wed, 18 Mar 2026 16:53:35 +0900 Subject: [PATCH] =?UTF-8?q?openclaw:=20=EA=B3=B5=EC=8B=9D=20=EB=AC=B8?= =?UTF-8?q?=EC=84=9C=20=EA=B8=B0=EB=B0=98=20=EB=A7=A4=EB=89=B4=EC=96=BC=20?= =?UTF-8?q?=EC=A0=84=EB=A9=B4=20=EC=9E=AC=EC=9E=91=EC=84=B1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 기존 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) --- openclaw/openclaw-manual.md | 282 ++++++++++++++++++++++++++++++------ 1 file changed, 236 insertions(+), 46 deletions(-) diff --git a/openclaw/openclaw-manual.md b/openclaw/openclaw-manual.md index 3882dd4..62990dd 100644 --- a/openclaw/openclaw-manual.md +++ b/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 - 도구/스킬/플러그인 시스템] -도구 시스템: -- 프로필: 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 +## 1. 개요 및 설치 -스킬 시스템: -- 위치: 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) +오픈소스 AI 에이전트 프레임워크. 메시징 앱(WhatsApp, Telegram, Discord, Slack, Signal, iMessage 등)을 통해 LLM과 대화하고, 셸 명령, 브라우저 자동화, 이메일, 파일 작업 등을 자율 수행. -플러그인 시스템: -- 명령: openclaw plugins list|info|install|enable|disable|doctor -- 매니페스트: openclaw.plugin.json (id, configSchema 필수) -- 슬롯: plugins.slots.memory/contextEngine -- 현재 loaded: device-pair, memory-core, phone-control, talk-voice, telegram (5개) -- memory-lancedb: disabled (벡터 검색용, 임베딩 API 키 필요) +**설치:** +```bash +# macOS/Linux +curl -fsSL https://openclaw.ai/install.sh | bash -## 세션/채널/게이트웨이 관리 (6/8) +# 온보딩 (인증, 게이트웨이, 채널 설정) +openclaw onboard --install-daemon +``` -[OpenClaw 매뉴얼 6/8 - 세션/채널/게이트웨이 관리] -세션 관리: -- 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 +**요구사항:** Node 24 권장 (22.16+ 호환) -채널: -- Telegram: botToken, dmPolicy(pairing|allowlist|open|disabled), streaming(off|partial|block|progress), groups, topics -- Discord: token, guilds, channels, voice, thread bindings, reactions -- WhatsApp: dmPolicy, allowFrom, textChunkLimit, sendReadReceipts -- Slack: socketMode 또는 HTTP, slash commands -- Signal, iMessage, IRC, Matrix, Mattermost, MS Teams, LINE, Google Chat 등 +**환경변수:** +- `OPENCLAW_HOME`: 홈 디렉토리 +- `OPENCLAW_STATE_DIR`: 상태 디렉토리 +- `OPENCLAW_CONFIG_PATH`: 설정 파일 경로 -게이트웨이: -- mode: local|remote, port:18789(기본) +## 2. 아키텍처 + +게이트웨이(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::main` 또는 `agent::direct:` +- 그룹: `agent:::group:` +- Telegram 토픽: `...group::topic:` +- Cron: `cron:`, 웹훅: `hook:` + +**리셋 정책:** +- `daily` (기본, atHour:4) 또는 `idle` (idleMinutes) +- `/new`, `/reset` 명령으로 즉시 리셋 +- `resetByType`으로 direct/group/thread별, `resetByChannel`로 채널별 재정의 + +**유지보수:** pruneAfter:30d, maxEntries:500, maxDiskBytes:500mb (mode: warn|enforce) + +**저장소:** `~/.openclaw/agents//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 -- RPC: openclaw gateway call {method} --params {json} -- 헬스: openclaw gateway health|probe|discover -- HTTP 엔드포인트: chatCompletions, responses (OpenAI 호환) +- 서비스: `openclaw gateway install|start|stop|restart|status|uninstall` +- RPC: `openclaw gateway call {method} --params {json}` +- 헬스: `openclaw gateway health|probe|discover` +- 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자 스킬은 신뢰할 수 없는 코드로 취급, 활성화 전 검토 필수