ACP adapter for Codex CLI

What it is – @agentclientprotocol/codex-acp는 Agent Client Protocol (ACP) 클라이언트가 OpenAI Codex와 통신할 수 있게 해주는 Node-JS 서버입니다. Codex를 하위 프로세스로 실행하고, 표준 ACP 요청/응답 형식을 Codex API 호출로 변환하며, Codex 이벤트를 클라이언트로 다시 전달합니다.

Why it matters – ACP는 코드 실행, 파일 편집, 웹 브라우징 등을 수행할 수 있는 AI 기반 "에이전트"를 구축하기 위한 프로토콜입니다. 이 어댑터는 Codex(GitHub Copilot의 기반이 되는 코드 생성 모델)를 해당 생태계에 연결하여, 개발자가 다른 에이전트(ChatGPT, Claude 등)와 동일한 통합 인터페이스를 통해 Codex를 사용할 수 있도록 합니다.

---

Key capabilities

Feature	What it does
Authentication	ChatGPT 스타일 로그인, API 키 인증 (CODEX_API_KEY / OPENAI_API_KEY) 및 사용자 지정 OpenAI 호환 게이트웨이를 지원합니다.
Configurable session	환경 변수 또는 CODEX_CONFIG를 통해 모델, 추론 강도, 빠른 모드, 샌드박스 모드 및 기타 Codex 설정을 선택할 수 있습니다.
Rich I/O	텍스트 프롬프트, 임베디드 컨텍스트, 이미지, 리소스 링크 및 추가 작업 공간 디렉토리를 처리합니다.
Tool-call events	셸 명령, 파일 변경, 권한 요청, MCP 도구 호출, 웹 검색, 이미지 생성, 토큰 사용량 등의 이벤트를 방출합니다.
AIR extensions	Agent Interaction Runtime (AIR) 확장을 구현합니다: diff-patch, 비동기 백그라운드 작업, 목표 추적, 유형화된 경고/오류, 턴별 파일 변경 보고서 등.
Sub-agent sessions	기능 협상 후, 별도의 기록과 권한 라우팅을 가진 네이티브 하위 에이전트 세션을 생성합니다.
Slash commands	대화형 제어를 위한 내장 명령 (/status, /mcp, /goal, /review, /compact, /logout, …)을 제공합니다.
MCP integration	stdio 또는 HTTP를 통한 클라이언트 제공 MCP 서버를 허용합니다.
Packaging	npm을 통해 배포되며, npx로 실행하거나 전역으로 설치할 수 있습니다.

---

Quick start (npm)

# Run the latest released version without installing
npx -y @agentclientprotocol/codex-acp

# Or install globally
npm install -g @agentclientprotocol/codex-acp
codex-acp --version

Optional: point the adapter at a different Codex binary:

CODEX_PATH=/my/codex npx -y @agentclientprotocol/codex-acp

For the bleeding-edge preview builds:

npx -y @agentclientprotocol/codex-acp@preview

---

Runtime configuration (environment variables)

Variable	Purpose
CODEX_API_KEY / OPENAI_API_KEY	Codex 인증을 위한 API 키 (전자가 우선순위가 높음).
CODEX_PATH	사용자 지정 Codex 실행 파일 경로.
CODEX_CONFIG	Codex 세션 구성에 병합되는 JSON 문자열.
MODEL_PROVIDER	새 세션에서 Codex가 사용할 모델 제공자를 선택합니다.
INITIAL_AGENT_MODE	초기 권한 모드 (read-only, workspace-write, agent, agent-full-access)를 설정합니다.
NO_BROWSER	브라우저 기반 ChatGPT 로그인 흐름을 억제합니다.
APP_SERVER_LOGS	어댑터가 로그를 기록하는 디렉토리.

---

Development workflow

npm install          # install deps
npm run start        # launch the adapter locally
npm run typecheck    # TypeScript check
npm test             # run test suite
npm run bundle:all   # produce self-contained binaries in dist/bin

See readme-dev.md for details on local client configuration, binary packaging, and Codex type regeneration.

---

Extensibility & protocol details

• AIR extensions – 이 어댑터는 docs/air-extensions.md에 문서화된 전체 AIR 확장 세트(diff-patch, 비동기 작업, 목표 추적, 세션 실패 등)를 구현합니다. 이러한 기능을 협상하는 클라이언트는 더 풍부하고 구조화된 이벤트를 수신합니다.
• Sub-agent sessions – 초안 ACP 하위 에이전트 RFD를 따릅니다. 양자 협상 후 하위 세션은 자체 기록과 권한 라우팅을 가지며, 클라이언트가 지원하지 않는 경우 일반 도구 호출로 대체됩니다.
• Background terminal tasks – Codex는 턴이 끝난 후에도 셸 명령을 계속 실행할 수 있습니다. 어댑터는 AIR 인식 클라이언트에 작업 상태와 중지 요청을 표시합니다.

---

License

Contributions are licensed under the Apache 2.0 license.

---

Bottom line – codex-acp는 ACP 호환 AI 에이전트가 OpenAI Codex를 사용할 수 있게 해주는 프로덕션 준비 완료 브리지로, 최신 AIR 확장, 하위 에이전트 세션 및 대화형 도구를 완벽하게 지원합니다.