[AI/Agent/编辑器/ACP] Agent Client Protocol：AI 编程时代的 LSP——编辑器与编码 Agent 的标准化桥接通信协议

0 序

image

从运行日志看，这个任务的执行过程中，发现 codex-cli 常用的底层文件内容检索命令： rg -n -i xxx

rg = ripgrep，是一个用 Rust 写的高速递归文本搜索工具，比传统 grep 更快，广泛用于代码 / 笔记检索。

  • 回到本文正题： ACP、codex-acp 是个啥？Agent Client Protocol：AI 编程时代的 LSP——编辑器与编码 Agent 的标准化【桥接】通信协议

本文以其子项目 codex-acp 为典型实现案例。

1 概述

产品介绍

  • Agent Client Protocol（ACP，智能体客户端协议） 是由 Zed Industries 于 2025 年 8 月 发起并发布的开放标准，旨在标准化代码编辑器（Client）与 AI 编码 Agent（Agent/Server）之间的通信接口。

  • 在 ACP 出现之前，每一款编辑器/IDE若要接入某一款 AI 编码 Agent（如 Claude Code、Codex、Gemini CLI），都需要编写一套专属的集成胶水代码，形成 N × M 的集成爆炸。

    • ACP 将这一关系解耦为 N + M：任意 ACP 兼容的 Agent 可以即插即用地运行在任意 ACP 兼容的编辑器中，无需定制开发。

  • ACP 的核心理念常被类比为 LSP（Language Server Protocol）之于 AI Coding Agent——LSP 统一了编辑器与语言智能服务的接口，ACP 则统一了编辑器与 AI Coding Agent 的接口。

  • 官方网站：https://agentclientprotocol.com/

  • 规范仓库：https://github.com/agentclientprotocol/agent-client-protocol

  • 协议版本：当前稳定线协议为 v2（v1 已进入迁移阶段）

  • 开源许可：Apache License 2.0，无需 CLA

发展历程

时间 事件
2025-06 Zed 团队开始内部设计编辑器与外部 Agent 的通信接口
2025-08-27 Zed 正式发布 ACP，首版支持"Bring Your Own Agent"，Gemini CLI 成为首个外部原生实现
2025-09-03 Claude Code 通过 claude-agent-acp 适配器接入 Zed
2025-10 JetBrains 宣布与 Zed 合作，共同开发 ACP，计划在 IntelliJ IDEA、PyCharm、WebStorm 中原生支持
2025-10-24 项目发布 GOVERNANCE.md、CODE_OF_CONDUCT.md，确立开放治理模式
2025-12 JetBrains IDE 正式上线 ACP 支持，发布"Bring your own AI agent to JetBrains IDEs"
2026-01 ACP Agent Registry 上线，提供在 IDE 内发现和连接 ACP 兼容 Agent 的目录服务
2026 上半年 协议演进至 v2，重构鉴权方法（auth/* 命名空间）、会话模型与流式传输规范
2026-07 发布 Streamable HTTP & WebSocket Transport RFD，推进远程传输能力
2026-08 主仓库累计 2,097+ Commits，codex-acp 发布 v1.3.0，生态持续高速扩张

主要功能

ACP 协议提供的核心能力可归纳为以下几类：

  1. 连接初始化与能力协商

    • initialize 握手：协商 protocolVersion，双向声明各自支持的能力集（如 Client 的 fileSystem、terminal；Agent 的 modelSelector、loadSession）
    • 版本兼容性由线上协议版本号决定，而非 SDK 发布号

  2. 会话生命周期管理

    • session/new：创建新会话
    • session/resume / session/load：恢复历史会话，Agent 回放完整对话
    • session/list：列出已知会话
    • session/close：关闭活跃会话

  3. 提示与流式响应

    • session/prompt：Client 向 Agent 发送用户输入
    • session/update 通知：Agent 流式回传增量输出、工具调用状态、推理内容、计划等，支持实时渲染

  4. 权限请求与人机协同

    • session/request_permission：Agent 对敏感操作（文件编辑、命令执行）向用户请求授权，编辑器作为权限守门人
    • 工具调用分类：read、edit、delete、move、search、execute、think、fetch

  5. Client 侧能力暴露

    • 文件系统：fs/read_text_file、fs/write_text_file
    • 终端控制：terminal/create、terminal/output、terminal/wait_for_exit、terminal/kill、terminal/release
    • Agent 通过调用这些 Client 原语来操作文件和执行命令，而非自行管理沙箱

  6. 鉴权机制

    • auth/login / auth/logout：支持 ChatGPT 登录、API Key、自定义网关等多种鉴权方式
    • Agent 在 initialize 时声明支持的 authMethods

  7. 可扩展机制

    • 所有消息支持可选 _meta 字段承载自定义数据
    • 自定义方法以 _ 前缀命名
    • 初始化时声明自定义能力

  8. MCP 集成

    • session/new 可声明 mcpServers，在一次握手中同时完成 ACP 与 MCP 的接线
    • Agent 本身通常也是 MCP Client，通过 MCP 调用外部工具

核心优势

  • 彻底解耦编辑器与 Agent：将 N × M 的集成复杂度降为 N + M，用户可在同一编辑器中自由切换不同 AI 编码 Agent
  • 以 LSP 为范式，心智模型成熟：开发者和编辑器厂商对"子进程 + JSON-RPC + 能力协商"模式已有丰富经验
  • 安全-by-design 的权限模型：敏感操作必须经过 session/request_permission，编辑器始终是权限守门人，Agent 无法自行越权
  • 开放治理与多厂商参与：Zed、JetBrains、Google 等直接对标规范实现，避免单一厂商锁定
  • 与 MCP 互补而非竞争：ACP 管"编辑器 ↔ Agent"，MCP 管"Agent ↔ 工具"，两者可在同一流水线中协同工作
  • 多语言 SDK 覆盖：官方提供 TypeScript、Python、Rust、Kotlin、Java SDK，降低接入门槛
  • 传输层灵活：本地 stdio 已稳定，远程 HTTP/WebSocket 传输在推进中

主要短板

  • 协议仍在快速演进：v1 → v2 存在不兼容变更，早期接入者面临迁移成本；部分特性（如终端能力、会话模式、斜杠命令）仍标记为 unstable
  • 远程传输尚未成熟：当前主流仍是本地 stdio 子进程模式，Streamable HTTP/WebSocket 仍在 RFD 阶段，云端/远程 Agent 场景体验有限
  • 原生支持的 Agent 仍有限：Claude Code、Codex CLI 等头部 Agent 仍需通过适配器（adapter）间接接入，存在功能映射不完整和性能损耗
  • 编辑器生态集中：原生深度支持主要在 Zed 和 JetBrains，VS Code 依赖社区插件，Neovim/Emacs 为社区实现
  • 鉴权体验碎片化：不同 Agent 的鉴权方式差异大（OAuth、API Key、自定义网关），用户配置成本较高
  • 缺少标准化的 Agent 能力描述：虽然有能力协商，但 Agent 的实际行为差异（如工具调用策略、审批粒度）仍需用户逐个适应

局限性

  • 仅覆盖"编辑器 ↔ Agent"一层：不解决 Agent 之间的协作（A2A 协议的领域），也不解决 Agent 与外部工具的连接（MCP 的领域）
  • 强依赖编辑器作为宿主：Agent 的文件操作和命令执行必须经由 Client 暴露的能力，在非编辑器场景（如纯后端服务）中适用性受限
  • stdio 模式下 Agent 生命周期绑定编辑器进程：编辑器关闭则 Agent 终止，不适合长驻后台 Agent
  • 协议内容块以 Markdown 为先：对非文本类复杂交互（如可视化调试、图形化重构）的表达能力有限

适用场景

  • 多 Agent 切换的编码工作流：开发者在同一 IDE 中根据任务切换 Codex、Claude Code、Gemini CLI 等不同 Agent
  • 编辑器厂商快速接入 AI 能力：IDE 团队只需实现 ACP Client 端，即可接入所有 ACP 兼容 Agent，无需逐个对接
  • AI 编码工具厂商扩大分发：Agent 团队实现 ACP Server 端，即可在所有 ACP 兼容编辑器中运行
  • 企业内部统一 AI 编码入口：通过 ACP Registry 统一管理和分发内部 Agent，标准化权限审批流程
  • 适配器/桥接层开发：为尚未原生支持 ACP 的 Agent（如 Codex CLI）构建 ACP 适配层

同类竞品

协议/标准 发起方 定位 与 ACP 的关系
MCP（Model Context Protocol） Anthropic Agent ↔ 工具/数据源 互补，不同层；ACP 管编辑器-Agent，MCP 管 Agent-工具
A2A（Agent2Agent Protocol） Google Agent ↔ Agent 对等协作 互补，不同层；A2A 管多 Agent 编排
Agent Communication Protocol（IBM ACP） IBM Research / BeeAI Agent 间 REST 通信 同名不同物，定位为 Agent 间通信，基于 REST
LSP（Language Server Protocol） Microsoft 编辑器 ↔ 语言服务 范式来源，ACP 借鉴其架构思想，但领域不同
各 Agent 私有 CLI/API OpenAI、Anthropic 等 厂商专属集成 被 ACP 抽象替代，但适配器仍需翻译私有协议

注意：市场上存在三个都缩写为"ACP"的协议，搜索时需区分：

  1. Agent Client Protocol（本文，Zed 发起，编辑器-Agent）
  2. Agent Communication Protocol（IBM/BeeAI，Agent-Agent，REST 基）
  3. Agentic Commerce Protocol（OpenAI + Stripe，AI 驱动结账）

发展趋势

  • 开源社区活跃度：

    • 主仓库 agentclientprotocol/agent-client-protocol：截至 2026-08，2,097+ Commits，几乎每日有提交（最近提交为 2 小时前），Issues 9 个、PR 27 个，维护节奏极快
    • codex-acp 子项目：466 Commits、63 个 Releases、被 110 个项目依赖，最新 v1.3.0（2026-08-14）
    • 官方 SDK 覆盖 TypeScript（npm @agentclientprotocol/sdk，当前 0.21.0）、Python（PyPI agent-client-protocol，当前 0.12.0）、Rust（crates.io）、Kotlin、Java
    • 社区衍生 SDK：Swift（swift-acp）、Dart（dart_acp）等

  • 生态扩张趋势：

    • 原生支持 Agent 持续增加：Gemini CLI、GitHub Copilot CLI（公开预览）、Goose、Cline、OpenHands、Mistral Vibe、Auggie、Blackbox AI、Qwen Code、Kiro CLI 等
    • 编辑器侧：Zed（参考实现）、JetBrains 全系列、VS Code 社区插件（strato-space.acp-plugin、formulahendry.acp-client）、Neovim、Emacs
    • ACP Registry 已成为 Agent 发现和安装的统一入口

  • 协议演进方向：

    • v2 稳定化，v1 逐步淘汰
    • 远程传输（Streamable HTTP + WebSocket）从 RFD 走向实现，使云端 Agent 成为可能
    • MCP-over-ACP 等跨协议融合特性在 unstable 通道中探索
    • 目标扩展（Goal Extension）、子 Agent（Subagent）等高级会话特性逐步标准化

总结：ACP 正沿着 LSP 的成功路径快速演进，从 Zed 专属机制成长为编辑器-Agent 互操作的事实标准，v2 稳定化与远程传输的落地将是下一阶段的关键里程碑。

2 工作原理与架构

概念术语

术语 含义
Client ACP 客户端，通常是代码编辑器/IDE，负责 UI 渲染、用户交互、权限审批、环境管理
Agent ACP 服务端，AI 编码 Agent 进程，运行 LLM 推理循环、调用工具、修改代码
Session 会话，一个具有共享上下文的对话上下文，包含多轮交互
Turn 轮次，一个会话内的一次"提示→响应"循环
initialize 初始化握手，协商协议版本与双方能力集
protocolVersion 线上协议版本号，决定兼容性，与 SDK 版本号解耦
Capabilities 能力声明，Client 和 Agent 在初始化时各自声明支持的可选功能
session/update 会话更新通知，Agent 向 Client 流式推送增量内容
session/request_permission 权限请求，Agent 对敏感操作向用户申请授权
Content Block 内容块，Markdown 优先的富文本，支持图片、音频、资源引用
Tool Call 工具调用，Agent 执行的操作，分类为 read/edit/delete/move/search/execute/think/fetch
_meta 元数据字段，所有消息可选的扩展数据载体
Adapter 适配器，为不原生支持 ACP 的 Agent（如 Codex CLI）提供协议翻译层

架构与运行原理

整体架构

ACP 的部署模型包含三个核心角色：

graph LR subgraph Editor["代码编辑器 (ACP Client)"] UI[聊天 UI / Diff 渲染 / 权限弹窗] FS[文件系统能力 fs/*] TERM[终端能力 terminal/*] end subgraph AgentProc["AI 编码 Agent (ACP Agent / 子进程)"] LLM[LLM 推理循环] TOOLS[工具调用引擎] MCP_CLIENT[MCP Client] end subgraph External["外部工具与数据"] MCP_SERVER[MCP Server 1] MCP_SERVER2[MCP Server 2] end Editor -- "JSON-RPC 2.0 over stdio" --> AgentProc AgentProc -- "session/update 流式通知" --> Editor AgentProc -- "session/request_permission" --> Editor MCP_CLIENT -- "MCP 协议" --> MCP_SERVER MCP_CLIENT -- "MCP 协议" --> MCP_SERVER2

关键设计要点：

  1. 编辑器启动 Agent 为子进程：Client 通过 stdin/stdout 与 Agent 交换 JSON-RPC 2.0 消息（行分隔 JSON）
  2. 控制方向与 MCP 相反：ACP 中编辑器是 Client、Agent 是被驱动的子进程；MCP 中 AI 应用是 Client、工具是 Server
  3. 编辑器是权限守门人：Agent 的文件写入和命令执行必须经由 Client 暴露的 fs/* 和 terminal/* 能力，并通过 session/request_permission 获得用户批准
  4. Agent 同时是 MCP Client：Agent 通过 MCP 协议调用外部工具，ACP 与 MCP 在 session/new 时可一次性完成接线

消息流（典型会话生命周期）

sequenceDiagram participant C as ACP Client (编辑器) participant A as ACP Agent (子进程) Note over C,A: 1. 初始化阶段 C->>A: initialize (protocolVersion, capabilities) A-->>C: initialize result (agentInfo, capabilities, authMethods) opt 需要鉴权 C->>A: auth/login (credentials) A-->>C: auth/login result end Note over C,A: 2. 会话建立 C->>A: session/new (mcpServers, mode, config) A-->>C: session/new result (sessionId) Note over C,A: 3. 提示生命周期 C->>A: session/prompt (content blocks) A-->>C: session/prompt result (已接受) loop 流式处理 A->>C: session/update (消息块/工具调用/推理/计划) opt 敏感操作 A->>C: session/request_permission (tool call details) C-->>A: permission result (approve/deny) end end A->>C: session/update (state_update: idle, stop_reason) opt 用户中断 C->>A: session/cancel (notification) end Note over C,A: 4. 会话关闭 C->>A: session/close A-->>C: session/close result

协议方法总览

Agent 侧方法（Client → Agent）：

方法 类型 说明
initialize Request 协商协议版本与能力，建立连接
auth/login Request 向 Agent 鉴权（如 Agent 声明了 authMethods）
auth/logout Request 结束当前鉴权状态
session/new Request 创建新会话
session/prompt Request 发送用户提示
session/list Request 列出已知会话
session/resume Request 恢复已有会话，可选回放历史
session/close Request 关闭活跃会话
session/cancel Notification 取消正在进行的操作

Client 侧方法（Agent → Client）：

方法 类型 说明
session/request_permission Request 请求用户授权工具调用/命令执行
elicitation/create Request（可选） 向用户请求结构化信息
session/update Notification 推送会话更新（消息、工具调用、终端输出、计划等）
elicitation/complete Notification 报告带外 URL 交互完成

工具调用分类与默认权限

类别 说明 默认权限
read 读取文件或列出目录 自动允许
edit 写入或修改文件 始终询问
delete 删除文件或目录 始终询问
move 重命名或移动文件 始终询问
search 搜索文件内容 自动允许
execute 执行 Shell 命令 始终询问
think 内部推理 自动允许
fetch HTTP 请求 询问

传输层

  • 本地 stdio（当前主流）：JSON-RPC 2.0 消息通过 stdin/stdout 交换，行分隔 JSON，轻量、可流式、易于子进程接线
  • 远程传输（开发中）：Streamable HTTP & WebSocket Transport RFD 已发布，initialize 返回 Acp-Connection-Id，后续响应通过 GET 流按 JSON-RPC id 关联

约定与规范

  • 所有文件路径必须为绝对路径
  • 行号从 1 开始
  • JSON 对象属性键使用 camelCase，判别器字段的字符串值使用 snake_case
  • 错误处理遵循标准 JSON-RPC 2.0：成功响应含 result，错误含 error（code + message）
  • 扩展值以 _ 前缀保留给实现特定扩展，未知非下划线值保留给未来 ACP 变体

子项目案例：codex-acp 深度解析（Obsidian-Copilot插件 + Codex的用户: 必读）

项目定位

  • codex-acp 是 OpenAI Codex CLI 的 ACP 适配器，由 ACP 官方组织（agentclientprotocol）维护。它是一个 stdio ACP Agent Server，其核心职责是：
  1. 启动 Codex App Server（Codex 的底层服务进程）
  2. 将 ACP 请求翻译为 Codex 操作
  3. 将 Codex 事件映射回 ACP 客户端

由于 Codex CLI 本身不原生支持 ACP，codex-acp 充当了协议翻译层，是 ACP 生态中"适配器模式"的典型代表。

  • Git仓库：https://github.com/agentclientprotocol/codex-acp

  • npm 包：@agentclientprotocol/codex-acp

  • 最新版本：v1.6.2（2026-08-19）

  • 实现语言：TypeScript

  • 开源许可：Apache 2.0

  • 社区数据：466 Commits、63 Releases、110 个项目依赖、28 Issues、44 PRs

架构与工作原理

graph TB subgraph Editor["ACP Client (编辑器)"] direction LR ZED[Zed] JB[JetBrains IDE] VSCODE[VS Code 插件] end subgraph Adapter["codex-acp (ACP Agent Server / stdio)"] ACP_HANDLER[ACP 请求处理器] TRANSLATOR[协议翻译层] EVENT_MAPPER[事件映射器] AUTH[鉴权管理器] SESSION[会话管理器] end subgraph Codex["Codex App Server (子进程)"] CODEX_RUNTIME[Codex 运行时] CODEX_MCP[MCP Client] end subgraph Tools["外部工具"] MCP_SRV[MCP Servers] end Editor -- "JSON-RPC over stdio" --> Adapter ACP_HANDLER --> TRANSLATOR TRANSLATOR --> CODEX_RUNTIME CODEX_RUNTIME --> EVENT_MAPPER EVENT_MAPPER --> Editor AUTH --> CODEX_RUNTIME SESSION --> CODEX_RUNTIME CODEX_MCP --> MCP_SRV

关键设计：

  • codex-acp 本身不执行 AI 推理，它是一个【纯协议桥接器】
  • 内部通过 npm 依赖 @openai/codex 捆绑兼容的 Codex 二进制，也可通过 CODEX_PATH 环境变量指定自定义 Codex 路径
  • 支持完整的 ACP 生命周期：initialize → authenticate → session/new → session/prompt → session/update 流式回传

核心功能特性

  1. 多模式鉴权

    • ChatGPT 登录（浏览器 OAuth，可通过 NO_BROWSER=1 在无浏览器环境隐藏）
    • API Key（CODEX_API_KEY 优先，回退 OPENAI_API_KEY）
    • 客户端提供的自定义 OpenAI 兼容网关（需客户端 opt-in gateway 鉴权能力）

  2. 丰富的运行时配置

    • 模型选择（Model）
    • 推理努力程度（Reasoning Effort）
    • 快速模式（Fast Mode）
    • 审批模式（Approval Mode）
    • 沙箱模式（Sandbox Mode）
    • 初始 Agent 模式：read-only / agent / agent-full-access

  3. 多模态输入支持

    • 文本提示
    • 嵌入上下文（Embedded Context）
    • 图片
    • 资源链接（Resource Links）
    • 额外工作区目录

  4. 全量事件映射

    • Shell 命令执行、文件变更、权限请求
    • MCP 工具调用、终端输出
    • 推理（Reasoning）、计划（Plan）
    • Web 搜索、图片生成、图片查看
    • Token 使用量统计、代码审查（Review）事件

  5. 子 Agent 支持

    • Codex 的子 Agent 启动被映射为标准 ACP 工具调用
    • Codex 线程标识和活动详情通过命名空间 _meta.codex.subagent 元数据传递

  6. 会话级长期目标

    • 通过提供商中立的 Goal Extension 支持会话范围的长期运行目标

  7. 客户端提供的 MCP 服务器

    • 支持基于命令的 stdio 配置和 HTTP 传输的 MCP 服务器注入

  8. 斜杠命令

    • /status、/mcp、/skills、/goal、/review、/review-branch、/review-commit、/compact、/logout
    • 以及用户配置的自定义 Skills

项目结构

codex-acp/
├── src/                    # 核心源码（TypeScript）
│   └── app-server/        # Codex App Server 类型定义与交互层
├── docs/                   # 文档
├── examples/               # 使用示例
├── scripts/                # 构建与发布脚本
├── .github/                # CI/CD（release-please 自动化发布）
├── .agents/skills/         # Agent 辅助技能（codex-update-compat）
├── .claude/skills/         # Claude 辅助技能（run-codex）
├── build.mjs               # 构建脚本
├── package.json            # npm 包配置（含 @openai/codex 依赖）
├── readme-dev.md           # 开发者文档
├── CHANGELOG.md            # 变更日志
└── LICENSE                 # Apache 2.0

版本与发布

  • 采用 release-please 自动化发布流程
  • 支持构建独立二进制（需 bun）：npm run bundle:all 生成 dist/bin 下单文件可执行文件
  • 发布平台：Linux、Darwin（macOS）、Win32（Windows）
  • Windows 开发需安装 C++ 可再发行组件包

3 使用指南

安装部署

方式1：手动下载、安装 Git Release 包

方式2：npx 直接运行（推荐快速体验）

> npx -y @agentclientprotocol/codex-acp 或者: npm install @agentclientprotocol/codex-acp --registry=https://registry.npmmirror.com
> codex-acp --version
@agentclientprotocol/codex-acp 1.6.2

此方式比较现代，只是 Obsidian Copilot 插件目前可能适配不足。

image

安装完成后， nodejs 的安装目录(如:D:\Program_Files\nodejs\node-v25.9.0-win-x64\)下会新增类似下列这些的新程序文件。

codex-acp
codex-acp.cmd
codex-acp.ps1

方式3：全局安装

npm install -g @agentclientprotocol/codex-acp
codex-acp --version

方式4：使用独立二进制

  1. 从 GitHub Releases 下载对应平台的 codex-acp-<platform>.zip（platform 为 linux / darwin / win32）
  2. 解压：
    unzip codex-acp-linux.zip    # Linux/macOS
# Windows 下使用资源管理器解压或 Expand-Archive

方式5：从源码构建

git clone https://github.com/agentclientprotocol/codex-acp.git
cd codex-acp
npm install
npm run start          # 开发模式运行
npm run typecheck      # 类型检查
npm test               # 运行测试
npm run bundle:all     # 构建独立二进制（需 bun）

指定自定义 Codex 二进制

默认使用 npm 包捆绑的 @openai/codex，如需使用其他版本：

CODEX_PATH=/path/to/codex npx -y @agentclientprotocol/codex-acp

编辑器接入配置

Zed

在 Zed 的 settings.json 中配置 Agent Server：

{
  "agent_servers": {
    "Codex (ACP)": {
      "command": "npx",
      "args": ["-y", "@agentclientprotocol/codex-acp"]
    }
  }
}

JetBrains IDE

通过 Settings → Tools → AI Assistant → External Agents 添加 ACP Agent，命令填写：

npx -y @agentclientprotocol/codex-acp

VS Code（社区插件）

安装 strato-space.acp-plugin 或 formulahendry.acp-client 后，在 settings.json 中配置：

{
  "acp.agents": {
    "codex": {
      "command": "npx",
      "args": ["--yes", "@agentclientprotocol/codex-acp@latest"]
    }
  }
}

通用 ACP Client 配置（从源码运行）

{
  "agent_servers": {
    "Codex (app-server)": {
      "command": "npm",
      "args": ["run", "start", "--prefix", "/path/to/codex-acp/"],
      "env": {
        "CODEX_PATH": "node_modules/.bin/codex",
        "APP_SERVER_LOGS": "/optional/path/to/logs"
      }
    }
  }
}

环境变量配置

环境变量 说明
CODEX_API_KEY API Key 鉴权时使用，优先级高于 OPENAI_API_KEY
OPENAI_API_KEY API Key 鉴权的回退选项
CODEX_PATH 指定自定义 Codex 可执行文件路径
CODEX_CONFIG 合并到 Codex 会话配置的 JSON 对象
MODEL_PROVIDER 传递给 Codex 的模型提供商
DEFAULT_AUTH_REQUEST Codex 需要鉴权时使用的 ACP auth request JSON
INITIAL_AGENT_MODE 初始模式：read-only / agent / agent-full-access
NO_BROWSER 设置为 1 时隐藏基于浏览器的 ChatGPT 鉴权（远程/无浏览器环境）
APP_SERVER_LOGS 适配器日志输出目录

关键操作

鉴权

启动后，适配器在 initialize 阶段声明支持的鉴权方式。客户端可选择：

  • ChatGPT 登录：触发浏览器 OAuth 流程（无浏览器环境设 NO_BROWSER=1）
  • API Key：设置 CODEX_API_KEY 或 OPENAI_API_KEY 环境变量
  • 自定义网关：客户端 opt-in gateway 鉴权能力后，提供 OpenAI 兼容网关地址

常用斜杠命令

在 ACP 客户端的聊天界面中输入：

命令 功能
/status 查看当前会话状态
/mcp 管理 MCP 服务器
/skills 查看和管理已配置的 Skills
/goal 设置或查看会话级长期目标
/review 触发代码审查
/review-branch 审查当前分支变更
/review-commit 审查指定提交
/compact 压缩会话上下文
/logout 退出登录

权限审批

当 Codex 尝试执行敏感操作（文件编辑、命令执行等）时，codex-acp 通过 session/request_permission 向编辑器发起权限请求，编辑器弹窗让用户选择：

  • 允许一次（Approve once）
  • 始终允许（Always allow）
  • 拒绝（Deny）

Z FAQ

Q: ACP 和 MCP 有什么区别？是竞争关系吗？

不是竞争关系，而是互补关系，工作在不同层级。

维度 ACP MCP
连接双方 编辑器 ↔ AI 编码 Agent AI 应用 ↔ 工具/数据源
解决的问题 编辑器如何驱动和渲染 Agent Agent 如何调用外部工具
Client 角色 代码编辑器/IDE AI 应用/Host
Server 角色 AI 编码 Agent（子进程） 工具/数据提供者
会话模型 有状态多轮会话 无状态工具调用为主
传输 stdio（主流）/ HTTP+WS（开发中） stdio / HTTP / SSE

一个编码 Agent 可以同时通过 ACP 与宿主编辑器通信、通过 MCP 调用外部工具。MCP 给 Agent 工具，ACP 给 Agent 编辑器。

Q: 为什么 Codex CLI 需要 codex-acp 适配器，而不是原生支持 ACP？

  • Codex CLI 发布于 ACP 规范之前，拥有自己的 App Server 协议和 CLI 交互模式。为了不破坏 Codex 已有的用户体验和 API，社区选择通过适配器模式将 Codex 的私有协议翻译为标准 ACP。
    • 类似地，Claude Code 也通过 claude-agent-acp 适配器接入。原生支持 ACP 的 Agent（如 Gemini CLI）则直接实现 ACP 协议，无需适配器。

Q: ACP 的权限模型如何保证安全？

ACP 的安全模型核心是编辑器作为权限守门人：

  1. Agent 不能直接访问文件系统或执行命令，必须调用 Client 暴露的 fs/* 和 terminal/* 能力
  2. 敏感操作（edit/delete/move/execute）必须通过 session/request_permission 向用户请求授权
  3. 工具调用按类别预设默认权限（read/search/think 自动允许，edit/delete/execute 始终询问）
  4. 所有操作通过 session/update 通知实时展示给用户，保持透明

Q: ACP 支持远程 Agent（云端运行）吗？

当前主流是本地 stdio 子进程模式。远程传输（Streamable HTTP & WebSocket Transport）已发布 RFD 并在开发中，initialize 将返回 Acp-Connection-Id，后续响应通过 GET 流按 JSON-RPC id 关联。在远程传输正式稳定前，可通过 SSH 端口转发等方式间接使用远程 Agent。

Q: 如何为自己的 AI 编码工具添加 ACP 支持？

  1. 阅读官方规范：https://agentclientprotocol.com/protocol/v2/overview
  2. 使用官方 SDK：TypeScript（@agentclientprotocol/sdk）、Python（agent-client-protocol）、Rust（agent-client-protocol crate）
  3. 实现 Agent 侧基线方法：initialize、session/new、session/prompt、session/update 通知
  4. 如工具已有私有协议，可参考 codex-acp 构建适配器层
  5. 提交到 ACP Registry 扩大分发

Q: ACP v1 和 v2 有什么主要差异？

v2 的主要变更包括：

  • 鉴权方法重构为 auth/login、auth/logout 命名空间（v1 为 authenticate）
  • 会话恢复方法从 session/load 调整为 session/resume
  • 权限请求从服务端通知改为客户端应答的 RPC
  • session/new 移除了 systemPrompt 参数
  • 更规范的流式传输和错误处理
  • 增强的可扩展性机制

官方提供了完整的 v1 → v2 迁移指南。

Q: codex-acp 支持哪些操作系统？

支持 Linux、macOS（Darwin）、Windows（Win32） 三大平台。npm 包跨平台可用；独立二进制通过 npm run bundle:all（需 bun）构建，发布为各平台 zip 包。Windows 环境下开发需安装 C++ 可再发行组件包。

Q: ACP 协议中的 unstable 特性是什么？

unstable 特性是实验性功能，可能变更或移除，当前包括：终端能力（terminal capability）、会话模式（session modes）、斜杠命令（slash commands）等。使用时需显式 opt-in（如 Rust crate 中 features = ["unstable"]），未来可能晋升为稳定特性。

Y 推荐文献

X 参考文献

posted @ 2026-08-25 10:10  数据知音  阅读(8)  评论(0)    收藏  举报