From 8182838eaeec25e9a9310447bf10f2999355170e Mon Sep 17 00:00:00 2001 From: Claude-51124 Date: Thu, 5 Feb 2026 10:13:00 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20openclaw=20=EA=B3=B5=EC=8B=9D=20?= =?UTF-8?q?=EB=AC=B8=EC=84=9C=20=EC=9A=94=EC=95=BD=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docs.openclaw.ai 요약 문서 추가 - orchestration_tools README 업데이트 --- .../260205_openclaw_official_docs_summary.md | 211 ++++++++++++++++++ ...260205_openclaw_로빙_적용_리서치.md | 107 +++++++++ .../research/orchestration_tools/README.md | 7 + 3 files changed, 325 insertions(+) create mode 100644 journey/research/orchestration_tools/260205_openclaw_official_docs_summary.md create mode 100644 journey/research/orchestration_tools/260205_openclaw_로빙_적용_리서치.md create mode 100644 journey/research/orchestration_tools/README.md diff --git a/journey/research/orchestration_tools/260205_openclaw_official_docs_summary.md b/journey/research/orchestration_tools/260205_openclaw_official_docs_summary.md new file mode 100644 index 0000000..111bccb --- /dev/null +++ b/journey/research/orchestration_tools/260205_openclaw_official_docs_summary.md @@ -0,0 +1,211 @@ +# 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..enabled, env, apiKey 등 + +--- + +## 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 (“저장해줘” “연결해줘” 등) diff --git a/journey/research/orchestration_tools/260205_openclaw_로빙_적용_리서치.md b/journey/research/orchestration_tools/260205_openclaw_로빙_적용_리서치.md new file mode 100644 index 0000000..552b7cf --- /dev/null +++ b/journey/research/orchestration_tools/260205_openclaw_로빙_적용_리서치.md @@ -0,0 +1,107 @@ +# OpenClaw 아키텍처 분석 및 로빙 적용 리서치 + +**작성일**: 2026-02-05 +**참고**: 312_문서_작성_원칙.md, 311_백엔드_구조_원칙.md +**원본**: https://github.com/openclaw/openclaw + +--- + +## 1. 개요 + +OpenClaw(구 Moltbot/Clawdbot)는 WhatsApp·Slack·Telegram 등 메신저로 대화하며 실제 작업을 수행하는 오픈소스 개인 AI 비서이다. 본 문서는 OpenClaw 폴더 구조·설계 패턴을 분석하고, 로빙(rb8001 + skill-*)에 적용 가능한 아이디어를 정리한다. + +--- + +## 2. OpenClaw 아키텍처 요약 + +### 2.1 핵심 디렉터리 + +| 디렉터리 | 역할 | 주요 구성 | +|----------|------|------------| +| src/gateway | WebSocket 컨트롤 플레인 | 세션·채널·도구·이벤트 통합 | +| src/agents | Pi Agent 런타임, RPC 모드 | 도구 스트리밍, 블록 스트리밍 | +| src/channels/plugins | 채널 플러그인 | slack, whatsapp, telegram, discord 등 | +| extensions/ | 채널 확장 (openclaw.plugin.json) | 블루버블, 마이크로소프트 팀즈, 매트릭스 등 | +| skills/ | 스킬 패키지 | SKILL.md + YAML frontmatter + scripts/references | + +### 2.2 설계 패턴 + +- **Gateway 중심**: 단일 WebSocket 컨트롤 플레인, 제품은 어시스턴트 +- **채널 플러그인화**: `openclaw.plugin.json` 기반 확장, channel.ts·runtime.ts 인터페이스 +- **스킬 포맷**: `SKILL.md` + name·description·metadata(YAML frontmatter) +- **멀티 에이전트 라우팅**: 발신자·워크스페이스별 에이전트 분리, 세션 격리 +- **보안 기본값**: DM pairing, allowlist, 비-main 세션 Docker 샌드박스 + +--- + +## 3. 로빙 적용 아이디어 + +### 3.1 Gateway 강화 + +| OpenClaw | 로빙 적용 | +|----------|-----------| +| Gateway = 세션·라우팅·도구 호출 단일 진실 원천 | robeing-gateway(8100)에 세션·라우팅 로직 추가 | +| 채널 커넥터는 이벤트만 Gateway로 전달 | 슬랙 드라이버는 이벤트 전달, Gateway가 세션·라우팅 담당 | + +### 3.2 멀티 에이전트 라우팅 → 존재 분화 + +| OpenClaw | 로빙 적용 | +|----------|-----------| +| 워크스페이스·에이전트별 세션 분리 | 메일·캘린더·리서치·퍼블리싱 에이전트 논리적 분리 | +| 의도 분류 후 해당 에이전트로 라우팅 | rb8001 의도 분석 → 해당 skill-* 또는 내부 에이전트로 분기 | + +### 3.3 스킬 포맷 표준화 + +| OpenClaw | 로빙 적용 | +|----------|-----------| +| SKILL.md + 입력/출력 스키마, 권한 스코프 | skill-*를 SKILL.md 스타일로 문서화·계약화 | +| 번들/관리/워크스페이스 스킬 우선순위 | 기본 스킬(번들) vs 사용자 맞춤 스킬 구분, 수정률·재사용률 → 스탯·레벨업 반영 | + +### 3.4 보안 기본값 + +| OpenClaw | 로빙 적용 | +|----------|-----------| +| DM·외부 입력 기본 불신, pairing/allowlist | 메신저 입력 기본 불신, 명시적 allowlist | +| 스킬 서드파티 출처 공급망 공격 대응 | 스킬은 서명된 출처만 허용, 권한 스코프 메타데이터 명시 | + +--- + +## 4. 로빙 vs OpenClaw 비교 + +### 4.1 아키텍처 + +| 구분 | OpenClaw | 로빙 (rb8001 + skill-*) | +|------|----------|--------------------------| +| 런타임 | Node.js ≥22, TypeScript | Python, FastAPI | +| 채널 | WhatsApp, Slack, Telegram, iMessage 등 다수 | Slack 중심 | +| 에이전트 | Pi Agent(RPC), 멀티 에이전트 라우팅 | 단일 rb8001 + skill-* HTTP 호출 | +| 스킬 | SKILL.md + 번들/관리/워크스페이스 | skill-* 별도 서비스 (skill_email, skill_news 등) | +| 게이트웨이 | 로컬 WebSocket 컨트롤 플레인 | robeing-gateway(JWT 인증, 프록시) | +| 철학 | 개인용 로컬 비서 | 존재형 에이전트, 기억·감정·윤리 | + +### 4.2 융합 시나리오별 장단점 + +| 시나리오 | 장점 | 단점 | +|----------|------|------| +| **A. 채널 확장** | extensions 구조 참고 가능 | rb8001은 Python, OpenClaw 코드 직접 활용 불가 | +| **B. Gateway 강화** | 세션·라우팅 단일 제어점 확보 | robeing-gateway 수정 시 51123 서버 영향 | +| **C. 스킬 포맷** | skill-* 문서화·계약화 가능 | 기존 skill-*와 호환성 설계 필요 | +| **D. 참조만** | 기존 스택·운영 유지 | 설계 수준 참고에 그침 | + +--- + +## 5. 결론 + +- **코드 융합보다 설계 참고**: OpenClaw(Node/TS)와 로빙(Python/FastAPI) 스택 차이로 직접 코드 병합은 부적합. +- **우선 적용 후보**: Gateway 중심 세션·라우팅 설계, SKILL.md 스타일 스킬 정의, 멀티 에이전트 라우팅(존재 분화), 보안 기본값(입력 불신·스킬 출처 검증). +- **적용 방식**: DOCS에 설계 패턴으로 정리 후, robeing-gateway·rb8001·skill-*에 맞게 단계적으로 반영. + +--- + +## 6. 참고 문서 + +- 311_백엔드_구조_원칙.md: 계층 분리, LangGraph 워크플로우 +- 312_문서_작성_원칙.md: 핵심만 간결, 파일명:줄번호 +- 360_로빙_컨테이너_경량화_전략.md: Stateless Router + Microservices +- orchestration_tools/250925_langgraph_vs_n8n_comparison.md: LangGraph vs n8n +- orchestration_tools/260205_openclaw_official_docs_summary.md: OpenClaw 공식 문서 요약 (docs.openclaw.ai) diff --git a/journey/research/orchestration_tools/README.md b/journey/research/orchestration_tools/README.md new file mode 100644 index 0000000..ef292ac --- /dev/null +++ b/journey/research/orchestration_tools/README.md @@ -0,0 +1,7 @@ +# 오케스트레이션·에이전트 플랫폼 리서치 + +## 문서 목록 + +- [LangGraph vs n8n 비교](250925_langgraph_vs_n8n_comparison.md) — LLM 에이전트·워크플로우 오케스트레이션 도구 비교 +- [OpenClaw 로빙 적용 리서치](260205_openclaw_로빙_적용_리서치.md) — OpenClaw 아키텍처 분석 및 로빙 적용 아이디어 +- [OpenClaw 공식 문서 요약](260205_openclaw_official_docs_summary.md) — docs.openclaw.ai 요약 및 로빙 적용 우선순위