# OpenClaw 아키텍처 분석 및 로빙 적용 리서치

**작성일**: 2026-02-05 (260226 보완)
**참고**: 312_writing-principles.md, 311_backend_coding_principles.md
**원본**: https://github.com/openclaw/openclaw
**로컬 클론**: `ivada/openclaw` (260226 클론)

---

## 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 실제 레포 구조 (클론 검증, 260226)

`ivada/openclaw` 클론 기준 검증 결과.

| 디렉터리 | 검증 | 비고 |
|----------|------|------|
| src/gateway | ✓ | WebSocket 컨트롤 플레인 |
| src/agents | ✓ | Pi Agent, acp-spawn 등 |
| src/channels | ✓ | dock.ts, registry.ts, plugins/ (채널 레지스트리·설정) |
| src/channels/plugins | ✓ | 확장 채널 로딩 |
| src/slack, telegram, whatsapp, discord 등 | ✓ | 코어 채널은 src/ 직접 |
| extensions/ | ✓ | 37개+ openclaw.plugin.json (Slack, Telegram, BlueBubbles, Matrix 등) |
| skills/ | ✓ | 46개+ SKILL.md (slack, github, coding-agent 등) |
| packages/ | (추가) | pnpm workspace 패키지 |
| apps/ | (추가) | macOS, Android 등 앱 |
| docs/ | (추가) | docs.openclaw.ai 소스 |
| openclaw.mjs | (추가) | CLI 엔트리포인트 |

- **채널 구조**: 코어 채널(src/slack 등) + extensions/ 플러그인(openclaw.plugin.json)으로 확장.
- **스킬 메타**: `metadata.openclaw.requires`(bins/config/env), `install`(brew/apt), `emoji` 등.
- **버전**: package.json `2026.2.26` (클론 시점).

### 2.3 설계 패턴

- **Gateway 중심**: 단일 WebSocket 컨트롤 플레인, 제품은 어시스턴트
- **채널 플러그인화**: `openclaw.plugin.json` 기반 확장( extensions/ 37개+), 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_backend_coding_principles.md: 계층 분리, LangGraph 워크플로우
- 312_writing-principles.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)
