acpx: AI 에이전트를 위한 헤드리스 ACP 클라이언트 - PTY 스크래핑의 끝

acpx Banner

“당신의 에이전트는 acpx를 사랑합니다! 🤖❤️ 그들은 PTY 세션에서 문자를 스크래핑하는 걸 싫어합니다 😤”

이 문구가 acpx의 핵심을 완벽하게 설명한다. AI 에이전트가 다른 코딩 에이전트와 통신할 때, 터미널 출력을 파싱하는 건 고통스럽다. ANSI 이스케이프 코드, 불규칙한 포맷, 변경되는 출력 형식. acpx는 이 문제를 Agent Client Protocol (ACP)로 해결한다.

acpx는 OpenClaw 팀이 만든 헤드리스 CLI 클라이언트로, 구조화된 프로토콜을 통해 Codex, Claude Code, Gemini CLI, OpenCode, Pi 같은 코딩 에이전트와 통신한다.

왜 acpx인가

기존 방식의 문제

AI 오케스트레이터가 코딩 에이전트를 호출할 때:

PTY 스폰 - 터미널 세션을 생성
출력 스크래핑 - ANSI 코드가 섞인 텍스트 파싱
상태 추정 - “thinking”, “tool call”, “done”을 휴리스틱으로 구분
에러 처리 - 출력 형식이 바뀌면 깨짐

acpx의 접근

acpx codex "fix the failing tests"
[thinking] Investigating test suite for flaky failures
[tool] Run npm test -- --reporter=verbose (running)
[tool] Run npm test -- --reporter=verbose (completed)
output: ✓ auth.login (0.8s)
        ✗ checkout.submit (timed out after 5000ms)
[thinking] Found it — checkout.submit has a race condition
[tool] Edit src/checkout.test.ts (completed)
[done] end_turn

구조화된 메시지. 파싱 불필요. 그냥 작동한다.

핵심 기능

지속적 세션

멀티턴 대화 - 호출 사이에서 살아남는 세션
디렉토리 스코프 - 리포지토리별로 세션 관리
명명된 세션 - 같은 리포에서 병렬 워크스트림 (-s backend, -s frontend)

프롬프트 큐잉

한 프롬프트가 실행 중일 때 새 프롬프트 제출 → 순서대로 실행
--no-wait으로 즉시 반환

협력적 취소

acpx codex cancel → ACP session/cancel 전송
세션 상태를 파괴하지 않고 안전하게 중단

소프트 클로즈

세션을 닫아도 히스토리는 디스크에 유지
나중에 다시 열 수 있음

큐 소유자 TTL

--ttl로 후속 프롬프트를 위해 큐 소유자 유지

파일/표준입력에서 프롬프트

echo 'fix flaky tests' | acpx codex
acpx codex --file prompt.md

크래시 재연결

에이전트 프로세스가 죽으면 자동 감지
세션을 자동으로 리로드

설치

글로벌 설치 (권장)

npm install -g acpx@latest

설치 없이 실행

npx acpx@latest codex "fix the tests"

세션 상태는 어느 쪽이든 ~/.acpx/에 저장된다.

지원 에이전트

에이전트	어댑터	래핑 대상
codex	codex-acp	Codex CLI
claude	claude-agent-acp	Claude Code
gemini	native	Gemini CLI
openclaw	native	OpenClaw ACP bridge
opencode	native	OpenCode
pi	pi-acp	Pi Coding Agent

커스텀 에이전트

acpx --agent './bin/dev-acp --profile ci' 'run checks'

사용 예시

기본 사용법

# 세션 생성
acpx codex sessions new

# 프롬프트
acpx codex 'fix the tests'

# stdin에서
echo 'fix flaky tests' | acpx codex

# 파일에서
acpx codex --file prompt.md

명명된 세션

# API 세션
acpx codex sessions new --name api
acpx codex -s api 'implement cursor pagination'

# 문서 세션 (병렬)
acpx codex sessions new --name docs
acpx codex -s docs 'rewrite API docs'

세션 관리

acpx codex sessions        # 목록
acpx codex sessions show   # 현재 세션 정보
acpx codex sessions history # 최근 턴 히스토리
acpx codex sessions close  # 세션 닫기
acpx codex status          # 로컬 프로세스 상태

세션 제어

acpx codex set-mode plan           # session/set_mode
acpx codex set approval_policy conservative  # session/set_config_option

원샷 모드

acpx exec 'summarize this repo'
acpx codex exec 'what does this repo do?'

권한 제어

acpx --approve-all codex 'apply the patch and run tests'
acpx --approve-reads codex 'inspect repo structure'
acpx --deny-all codex 'explain without tool access'

출력 포맷

text (기본)

acpx codex 'review this PR'

json (NDJSON)

acpx --format json codex exec 'review this PR' \
  | jq -r 'select(.type=="tool_call") | [.status, .title] | @tsv'

json-strict

비-JSON stderr 억제

acpx --format json --json-strict codex exec 'review this PR'

quiet

최종 어시스턴트 텍스트만

acpx --format quiet codex 'give me a 3-line summary'

설정 파일

{
  "defaultAgent": "codex",
  "defaultPermissions": "approve-all",
  "nonInteractivePermissions": "deny",
  "authPolicy": "skip",
  "ttl": 300,
  "timeout": null,
  "format": "text",
  "agents": {
    "my-custom": {
      "command": "./bin/my-acp-server"
    }
  },
  "auth": {
    "my_auth_method_id": "credential-value"
  }
}

글로벌: ~/.acpx/config.json
프로젝트: /.acpxrc.json
CLI 플래그가 항상 우선

에이전트에 acpx 스킬 설치하기

OpenClaw, Pi, Claude Code 같은 에이전트에 이 블록을 붙여넣으면 된다:

I want you to use acpx to run coding agents over the Agent Client Protocol (ACP) instead of scraping PTY sessions.

Please do the following:
1. Install acpx globally: npm install -g acpx@latest
2. Install the acpx skill: npx acpx@latest --skill install acpx
3. Read the skill reference: https://raw.githubusercontent.com/openclaw/acpx/main/skills/acpx/SKILL.md
4. Full CLI reference: https://raw.githubusercontent.com/openclaw/acpx/main/docs/CLI.md

From now on, use acpx instead of spawning raw terminal sessions.

세션 라우팅 규칙

프롬프트는 cwd에서 시작해 가장 가까운 git 루트까지 올라가며 세션 검색
git 루트가 없으면 정확한 cwd 세션만 매칭
-s로 병렬 명명 세션 선택
sessions new는 기존 세션을 소프트 클로즈하고 새 세션 생성
sessions ensure는 기존 세션이 없을 때만 생성 (멱등)
closed: true인 세션은 자동 재개에서 스킵

기술적 세부사항

세션 메타데이터

저장 위치: ~/.acpx/sessions/
각 성공 프롬프트마다 가벼운 턴 히스토리 프리뷰 추가

큐 시스템

프롬프트는 세션별로 큐잉됨
실행 중인 프롬프트가 있으면 새 프롬프트는 대기
큐 소유자는 idle TTL (기본 300초) 동안 유지

크래시 복구

저장된 세션의 pid가 죽어있으면:
1. 에이전트 재시작
2. session/load 시도
3. 실패하면 session/new로 폴백

Ctrl+C 처리

실행 중인 턴에서 Ctrl+C → ACP session/cancel 전송
stopReason=cancelled 대기 후 타임아웃 시 force-kill

마치며: PTY 스크래핑에서 프로토콜로

acpx는 AI 에이전트 오케스트레이션의 “파이프”를 표준화한다. 더 이상 터미널 출력을 정규식으로 파싱할 필요가 없다. ACP가 제공하는 구조화된 메시지를 그대로 사용하면 된다.

특히 인상적인 것은:

멀티 에이전트 지원 - Codex, Claude, Gemini, OpenCode, Pi를 하나의 CLI로
지속적 세션 - 멀티턴 대화가 자연스럽게
프롬프트 큐잉 - 동시 요청을 안전하게 처리
크래시 복구 - 에이전트가 죽어도 세션을 잃지 않음

AI 에이전트를 오케스트레이션하는 개발자라면, acpx를 시도해보라. PTY 스크래핑의 고통에서 벗어날 수 있다.

🔗 관련 정보

GitHub: https://github.com/openclaw/acpx
npm: https://www.npmjs.com/package/acpx
ACP 사양: https://agentclientprotocol.com
CLI 참조: docs/CLI.md
스킬 참조: skills/acpx/SKILL.md