ACP adapter for Codex CLI

What it is – @agentclientprotocol/codex-acp 是一个 Node-JS 服务器，允许 Agent Client Protocol (ACP) 客户端与 OpenAI Codex 进行通信。它将 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	发送 shell 命令、文件更改、权限请求、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 可以在一轮对话后保持 shell 命令运行；适配器向支持 AIR 的客户端显示任务状态和停止请求。

---

License

Contributions are licensed under the Apache 2.0 license.

---

Bottom line – codex-acp 是一个生产就绪的桥梁，允许任何兼容 ACP 的 AI 代理使用 OpenAI Codex，并全面支持最新的 AIR 扩展、子代理会话和交互式工具。