openclaw/backup_openclaw

Fork 0

Files

arin f3726b39d1 chore: update workspace config and memory

2026-03-30 19:30:25 +09:00

4.5 KiB

Raw Blame History

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

4.5 KiB Raw Blame History