LLM Wiki

acpx — ACP 헤드리스 CLI 클라이언트

6 min read

acpx — ACP 헤드리스 CLI 클라이언트

AI 에이전트가 PTY 스크래핑 없이 ACP(Agent Client Protocol)를 통해 Codex·Claude 같은 코딩 에이전트를 구조적으로 제어할 수 있는 헤드리스 CLI 클라이언트. 2026-04-26 기준 ⭐ 2.3k, MIT 라이선스.

핵심 기능

  • 지속 세션: repo별 다중 턴 대화, 호출 간 상태 유지
  • 이름 지정 세션: 동일 repo에서 병렬 워크스트림 (-s backend, -s frontend)
  • 프롬프트 큐잉: 실행 중인 프롬프트가 있어도 대기열에 추가
  • 협력적 취소: cancel 명령으로 ACP session/cancel 전송 (세션 상태 유지)
  • Fire-and-forget: --no-wait로 프롬프트 큐잉 후 즉시 반환
  • 정형 출력: thinking, tool calls, diffs를 타입화된 ACP 메시지로 출력 (ANSI 스크래핑 불필요)
  • Crash 재연결: 에이전트 프로세스 종료 감지 후 세션 자동 재로드
  • Flows: TypeScript 기반 멀티스텝 워크플로우 실행

v0.6.0 업데이트 포인트

2026-04-25 공개된 v0.6.0 은 acpx를 단순 ACP 래퍼에서, 더 오래 살아 있는 멀티턴 런타임으로 다듬는 릴리스에 가깝다.

새 기능

  • Claude 시스템 프롬프트 제어: --system-prompt, --append-system-prompt 플래그로 Claude Code 시스템 프롬프트를 대체/추가 가능. persistent session 재사용 시에도 유지됨.
  • 세션 정리 명령: sessions prune 추가. --dry-run, age filter, --include-history 지원.
  • 임베디드 턴 핸들: startTurn(...) 으로 런타임 이벤트 스트림을 별도로 관찰, 취소, 닫기 가능.
  • --no-terminal: 새 agent client에서 ACP terminal capability 광고를 끌 수 있음.

안정성/운영 개선

  • persistent session 수정: session/set_config_option 값과 control operation이 새 backend session으로 튀지 않고 기존 persistent session을 계속 재사용.
  • WSL cwd 번역: WSL에서 Windows .exe ACP agent를 띄울 때 wslpath로 경로를 번역.
  • 큐 강화: queue / IPC 디렉토리 owner-only permission, cryptographically random generation ID 도입.
  • 더 명확한 오류 힌트: auth 필요, missing session, ACP failure, timeout, provider rate limit, invalid model name 등에 대해 text-mode remediation hint 제공.
  • 지연 업데이트 drain: session/prompt 성공 후 늦게 도착하는 tool/output update도 놓치지 않도록 후처리 개선.

왜 중요한가

  • Claude를 acpx로 다룰 때 persistent session을 깨지 않고 시스템 프롬프트를 조절 할 수 있게 됐다.
  • Codex/Claude를 상위 오케스트레이터가 부를 때, 세션 식별/정리/오류 복구가 더 실전적으로 바뀌었다.
  • --no-terminal, WSL path translation, queue hardening 같은 항목은 화려하진 않지만 에이전트 간 제어를 실제 운영 환경에서 덜 깨지게 만드는 수정 이다.

지원 에이전트

명령어에이전트URL
acpx piPi Coding Agenthttps://github.com/mariozechner/pi
acpx openclawOpenClaw ACP bridgehttps://github.com/openclaw/openclaw
acpx codexCodex CLIhttps://codex.openai.com
acpx claudeClaude Codehttps://claude.ai/code

사용법

# 설치
npm install -g acpx@latest
 
# 기본 사용
acpx codex "fix the failing tests"
acpx claude "refactor auth middleware"
 
# 네임드 세션 (병렬 작업)
acpx codex -s api 'implement token pagination'
acpx codex -s docs 'rewrite API docs'
 
# Fire-and-forget
acpx codex --no-wait 'draft test migration plan'
 
# Flow 실행 (멀티스텝 워크플로우)
acpx flow run ./my-flow.ts --input-file ./flow-input.json
 
# JSON 출력 (자동화용)
acpx --format json codex exec 'review this PR' | jq '.type'

Claude Code에서 ACP CLI를 서브 에이전트로 사용하는 방법

방법 1: Claude Code 네이티브 서브에이전트

.claude/agents/ 디렉토리에 마크다운 파일로 정의하면 자동 위임. ACP 불필요.

방법 2: acpx로 다른 ACP 에이전트 호출

Claude Code의 Bash 도구에서 npx acpx codex "task" 또는 npx acpx claude "task" 형태로 호출.

# Claude Code의 커스텀 서브에이전트에서
npx acpx@latest codex "fix the failing tests"
npx acpx@latest claude "refactor the auth module"

방법 3: invoke-opencode-acp 스킬

Claude Code 스킬로 설치하면 ACP 프로토콜로 OpenCode를 서브에이전트로 위임. 토큰 50~90% 절약.

node ~/.claude/skills/invoke-opencode-acp/acp_client.cjs "$PWD" "task description"

핵심 구분

  • MCP: 도구 연결 (Tool connection)
  • ACP: 에이전트 간 통신 (Agent-to-agent communication)

멀티에이전트 오케스트레이션 설계 시 두 프로토콜의 역할을 명확히 구분하는 것이 중요.

설정

// ~/.acpx/config.json 또는 <cwd>/.acpxrc.json
{
  "defaultAgent": "codex",
  "defaultPermissions": "approve-all",
  "authPolicy": "skip",
  "ttl": 300,
  "timeout": null,
  "format": "text"
}

참고

  • 알파 단계 — CLI/런타임 인터페이스 변경 가능
  • ACP 스펙 커버리지: ACP Spec Coverage Roadmap
  • Node.js 기반, MIT 라이선스

그래프 뷰

백링크