# 2026-03-27

## OpenClaw 프로젝트 아키텍처 분석 (tmp/openclaw-src)

### TL;DR

이 repo는 OpenClaw 자체 (`github.com/openclaw/openclaw`)이며, "OpenCode"라는 별도 프로젝트는 없음.
ACPX는 ACP(Agent Client Protocol) 브릿지 플러그인.

---

## 1. 프로젝트란?

**OpenClaw** — 개인 AI 어시스턴트 플랫폼. 멀티채널(WhatsApp/Telegram/Discord 등) + 임베디드 AI 에이전트 런타임 + ACP 프로토콜 브릿지를 하나의 게이트웨이(WS 포트 18789)에 통합.

핵심 구성:
- **Gateway** (`src/infra/`): WS 控制-plane. 세션 관리, 라우팅, 도구 실행, 채널 연결
- **Pi Agent** (`src/agents/pi-embedded-runner/`): 내장 에이전트 런타임. OpenAI 호환 API로 모델 호출. 실제 Labor 수행.
- **ACP Bridge** (`openclaw acp`): IDE 연동을 위한 ACP 프로토콜 CLI 브릿지 (stdio/NDJSON)
- **ACPX Plugin** (`extensions/acpx/`): 외부 ACP 에이전트(Codex, Claude Code, Gemini 등)를 `sessions_spawn(runtime="acp")`로 스폰하기 위한 플러그인. 별도 npm 패키지 `acpx`를 서브프로세스로 실행.
- **Channels** (`src/telegram/`, `src/discord/` 등): 각 메신저 플랫폼별 통합

---

## 2. 스폰(Subagent) 메커니즘 비교

### `sessions_spawn(runtime="subagent")` (내장)
- Pi Agent 자식 세션을 Gateway 프로세스 내에서 실행
- 부모와 동일한 도구/워크스페이스 상속
- 가볍고 빠름, 부모와 직접 WS 통신
- **OpenClaw의 기본 워커 스폰 방식**

### `sessions_spawn(runtime="acp")` (ACPX)
- ACPX Plugin → `acpx` 서브프로세스 실행 (npm 패키지 `acpx`)
- ACPX → 외부 ACP 에이전트(Codex/Claude Code 등)와 NDJSON 통신
- 부모와 IPC 구조: Gateway ↔ ACPX Plugin ↔ `acpx` 바이너리 ↔ 외부 ACP 에이전트
- 주 용도: IDE (Zed 등) 연동 + 외부 ACP 에이전트 스폰
- **오버헤드가 크고, 주 용도가 IDE 연동**

---

## 3. Strengths / Weaknesses

### Strengths (OpenClaw 전체)
- 멀티채널 통합이 매우 강력 (20+ 플랫폼)
- ACP 프로토콜로 IDE 연동 표준화
- 내장 Pi Agent로 로컬 모델 직접 호출 가능
- `sessions_spawn`으로 멀티에이전트 오케스트라 지원
- sandbox 모드 (Docker) 지원

### Weaknesses
- ACPX는 IDE 연동용. 백그라운드 워커로는 오버엔지니어링
- `runtime="acp"` 스폰은 부모 ↔ 자식 통신 경로가 깊음 (Gateway → ACPX plugin → acpx binary → 외부 ACP 에이전트)
- 내장 Pi Agent가 ACP 프로토콜을 직접 이해하지 않음 (ACP 브릿지가 별도)
- 노드 22+ 필요

---

## 4. 현재 워크스페이스와의 관계

현재 지웅의 운영 모델:
- **Codex** (gpt-5.4) = 오케스트라/검증
- **로컬 LLM** (qwen3-8b, qwen2.5-coder-32b, deepseek-r1) = 실제 노동
- **ACPX** = 현재 acpx.json에 등록된 MCP 서버 관리 (KIS MCP, Playwright, SSH Terminal)

현재 `sessions_spawn` 사용 패턴: 없음 (MEMORY.md에 없음)

---

## 5. 결론: ACPX를 서브에이전트 워커로 쓸 것인가?

### ❌ ACPX(`runtime="acp"`)를 워커로 쓸 이유 없음
- 주 용도가 IDE 연동 → 백그라운드 워커로 부적합
- 오버헤드 큼 (최소 2개 프로세스 추가)
- 현재 워크스페이스는 IDE 연동이 아닌 CLI/Telegram 워크플로우
- 로컬 LLM으로 충분히 노동 가능

### ✅ `runtime="subagent"` (내장 Pi Agent) 활용 고려
- 현재架构에 자연스럽게 통합
- Gateway WS로 부모-자식 통신 (프로세스 내)
- 로컬 모델(qwen2.5-coder 등)과 직접 연결 가능
- 이미 Pi Agent가 워크스페이스 파일 시스템/도구 접근 가능

### ACP/OpenRouter 경유 여부
- **불필요**: 로컬 LLM (llamacpp-8080~8083)이 동일 머신에서 직접 호출 가능
- Gateway → ACP 브릿지 경유는 IDE 연동에서만 의미 있음
- Codex가 오케스트라 역할이면, ACPX 브릿지 없이 `sessions_spawn(runtime="subagent")`로 충분

---

## 6. 설정 참고

ACPX Plugin 활성화 (이미 설정됨):
- `~/.openclaw/openclaw.json`에 `plugins.entries.acpx.enabled = true`
- `extensions/acpx`가 설치됨
- `acpx` npm 패키지 (`npm install --omit=dev acpx@0.1.16`)
- ACPX의 `sessions_spawn(runtime="acp")`는 `agentId` 필요 (MEMORY.md의 `acp.defaultAgent` 설정)

내장 Subagent 스폰 (설정 불필요, 이미 내장):
- `sessions_spawn(runtime="subagent")`는 Gateway 내장 기능
- `agents.defaults.subagent.*`에서 maxDepth, maxChildren 등 설정 가능
- `agents.defaults.model`으로 자식 세션 기본 모델 오버라이드 가능