backup_openclaw/memory/2026-03-27.md

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으로 자식 세션 기본 모델 오버라이드 가능