도입 전 개발자가 반드시 확인하는 가지 실무 질문
OpenClaw CLI는 서브에이전트 풀 기반의 로컬 AI 에이전트 orchestrator로, Homebrew 또는 공식 바이너리로 설치하고 openclaw gateway start로 데몬을 실행합니다. ACP 8단계 채널바인딩으로 세션 격리를 보장하며, 3~5개 Worker가 FanOut/FanIn 패턴으로 병렬 작업을 분해·합성합니다. execFileAsync와 spawn 두 가지 실행 모드를 지원하고, 결함 격리 구조에 Exponential Backoff로 자동 복구합니다. Memory persistence는 파일 기반 일일·장기 메모리로 보장되며, 수평 확장은 노드 추가로 자동 라우팅됩니다.
이 글의 핵심 주장과 근거
OpenClaw CLI 설치 및 실행 환경
OpenClaw CLI는 로컬에서 AI 에이전트를 서브에이전트 풀 구조로 구동하는 명령줄 도구로, ACP 프로토콜 기반 세션 격리와 FanOut/FanIn 병렬 실행을 지원합니다. 설치는 Homebrew(`brew install openclaw`) 또는 공식 바이너리 다운로드로 진행하며, `openclaw gateway start`로 데몬을 실행한 후 `openclaw status`로 정상 구동 여부를 확인합니다. macOS/Linux용 바이너리와 `~/.openclaw/` 디렉터리에 쓰기 권한이 필수적으로 필요합니다.
ACP 세션 격리와 런타임 구조
ACP 8단계 채널바인딩은 에이전트 간 메시지를 채널 단위로 바인딩·라우팅하는 프로토콜로, 독립 네임스페이스 격리를 통해 세션 분열을 방지합니다. 메인 세션과 격리된 서브 세션(runtime=`subagent` 또는 `acp`)을 구분하며, 격리된 세션은 독립적인 메모리와 파일 시스템을 가져 외부 파일 접근 시 명시적 권한이 필요합니다. dmScope 격리는 ACP에서 물리적 Worker 격리와 논리적 메시지 라우팅을 이중으로 수행하여 단일 장애점을 구조적으로 제거합니다.
멀티모델 연동과 런타임 아키텍처
모델은 전역 설정(agents.defaults.model) 또는 세션별 오버라이드(model=)로 지정하며, acp-router 기술을 통해 Claude Code, Codex, Gemini 등 다양한 외부 코딩 에이전트와 연동할 수 있습니다. execFileAsync는 파일 경로 기반 동기 실행이고, spawn은 동적 명령어 생성 기반 비동기 실행을 지원하여 두 가지 실행 모드를 상황에 맞게 전환하며 활용할 수 있습니다. 모델 전환 시 session_status로 현재 활성 모델을 확인하고 sessions_spawn으로 새 세션을 생성해 다른 모델을 병렬로 사용할 수 있습니다.
FanOut/FanIn 병렬 실행의 한계와 실무 권장사항
FanOut은 동일 라운드 내에서 스폰 가능한 서브 에이전트 수에 하드 리밋이 없으나, 시스템 리소스(CPU·메모리)와 openclaw tasks 실행 제한에 따라 실질적인 상한이 존재합니다. FanIn은 하나의 메인 세션에서 여러 격리된 작업을 병렬로 진행할 수 있으나, 모든 작업의 결과가 동기화될 때까지 process로 폴링하거나 cron으로 알림을 받아야 합니다. 결함 격리 구조로 개별 Worker 실패가 전체 시스템에 영향을 주지 않으며, 과도한 병렬 실행 시 rate-limit(429)에 걸릴 수 있어 동시에 3~5개의 작업을 권장합니다.
자동 복구 메커니즘과 상태 관리
작업 중 예외가 발생하면 exec가 자동으로 retry 로직을 시도하고, 실패 시 process로 상태를 기록하는 2단계 실행 체계가 작동합니다. Exponential Backoff는 서브에이전트 실행 실패 시 대기 시간을 지수적으로 증가시키며 재시도하는 자동 복구 메커니즘으로, 복구 정책은 cron으로 설정된 wake-up 이벤트와 결합해 일정 간격(예: 5분)마다 실패 여부를 재검사합니다. 복구가 계속 실패하면 sessions_yield로 현재 세션을 종료하고, 수동으로 openclaw gateway restart를 실행해야 할 수도 있습니다.
Memory Persistence와 버전 관리
일일 메모리(memory/YYYY-MM-DD.md)와 장기 메모리(MEMORY.md)는 파일에 직접 기록되어 세션 재시작 후에도 유지됩니다. memory_search로 키워드 검색 후 memory_get으로 특정 라인을 읽어올 수 있으며, 중요한 내용은 반드시 파일에 저장해 두어야 합니다. 자동 백업은 cron으로 MEMORY.md를 주기적으로 커밋하도록 설정하면 버전 관리가 가능하고, 메인 세션에서는 memory/와 MEMORY.md만 직접 조회할 수 있어 보안과 데이터 유출 위험을 최소화합니다.
확장성 설계와 제어된 규모 확장
수평 확장은 기존 클러스터에 새로운 노드(예: Pi, VPS)를 추가하고 openclaw gateway start로 등록하면 자동으로 라우팅됩니다. 스레드-바운드 ACP 세션은 sessions_spawn으로 생성한 고정된 스레드에서만 작업을 수행하도록 지정할 수 있어 특정 작업에 대한 고정 자원을 확보합니다. FanOut/FanIn 한계를 고려해 작업 큐를 cron으로 관리하고 각 워커가 처리할 job을 할당하면 무한 확장보다는 제어된 규모 확장이 가능하며, LMStudio GGUF K-Quant 양자화와 결합하면 16GB RAM에서도 효율적인 멀티모델 서빙 환경을 구축할 수 있습니다. > 이 주제의 전체 맥락 방향성은 **15. 오래 쓸수록 보이는 AI의 경계** 원본 글에 세밀하게 정리되어 있습니다. 더 깊게 탐구하고 싶다면 관련 내부 대표 문서(Pillar/Entity)를 참조하세요.