ACP（Agent Client Protocol）模式通过 gemini --acp 启动，为 IDE 等工具提供标准化的程序化接入接口——使用 stdio 上的 JSON-RPC 2.0 协议。支持 initialize 握手（含 MCP 服务器注册）、newSession/loadSession 会话管理、prompt 发送和 cancel 中止。文件读写通过客户端代理执行，确保权限隔离。

ACP 模式技术参考

ACP（Agent Client Protocol）模式是 Gemini CLI 为 IDE 和开发工具集成提供的程序化接口，使用 JSON-RPC 2.0 协议通过标准输入输出（stdio）通信。

启动方式

gemini --acp

ACP 协议简介

ACP 是一个开放协议，解决 AI 编码代理的分发碎片化问题——代理只需实现一次 ACP，就可以与所有支持 ACP 的编辑器/IDE 集成，无需为每个 IDE 单独开发适配。

Gemini CLI 已注册为 ACP 兼容代理，支持与 JetBrains、Zed 等 IDE 集成。

通信架构

IDE（客户端）  ←→  stdio JSON-RPC 2.0  ←→  Gemini CLI（服务端）

• 客户端职责：发送请求（如 Prompt）、处理响应和通知
• 服务端职责：监听 JSON-RPC 请求，处理后返回结果

核心方法

方法	说明
initialize	建立初始连接，允许客户端注册其 MCP 服务器
authenticate	对用户进行认证
newSession	开始新的聊天会话
loadSession	加载已有会话
prompt	向代理发送提示词
cancel	取消正在进行的 prompt 请求

会话控制方法

方法	说明
setSessionMode	修改工具调用的批准级别（如切换为 auto-approve）
unstable_setSessionModel	切换当前会话的模型

ACP + MCP 组合

ACP 支持与 MCP 协议结合，让 IDE 可以把自身功能（文件操作、调试器等）作为工具暴露给 Gemini 模型：

1. 客户端实现一个 MCP 服务器，声明可用工具
2. 在 initialize 握手阶段，客户端提供其 MCP 服务器的连接地址
3. Gemini CLI 连接该 MCP 服务器，发现并注册工具
4. 模型需要使用这些工具时，Gemini CLI 向 MCP 服务器发起工具调用

这实现了双向集成：AI 既能利用 IDE 的能力，IDE 也能控制 AI 的行为。

文件系统代理（安全机制）

在 ACP 模式下，代理读写文件时通过客户端（IDE）的文件系统代理执行，确保只能访问用户明确授权的文件——与直接文件系统访问相比，安全边界更清晰。

调试与遥测

开启调试日志：

gemini --acp --debug

详细遥测日志（写入文件）：

GEMINI_TELEMETRY_ENABLED=true \
GEMINI_TELEMETRY_TARGET=local \
GEMINI_TELEMETRY_OUTFILE=/path/to/log.json \
gemini --acp

日志文件包含所有事件（ACP 请求/响应、工具调用、模型输出）的 JSON 记录，适合调试 IDE 集成问题。

常见问题

Q: ACP 模式和无头模式（-p 标志）有什么区别？

A: 无头模式是简单的单次提示词→输出模式，适合脚本和 CI/CD；ACP 模式是持续运行的 JSON-RPC 服务，适合需要交互式、双向通信的 IDE 集成场景。

Q: 普通用户需要了解 ACP 模式吗？

A: 通常不需要。ACP 模式主要面向工具开发者（IDE 插件、编辑器集成）。普通用户通过 IDE 安装 Gemini CLI 插件后，IDE 会自动在后台使用 ACP 模式，无需手动操作。

Q: 哪些 IDE 已经支持 ACP？

A: 目前已知支持的包括 JetBrains 系列（GoLand、IntelliJ 等）和 Zed 编辑器。更多信息见 ACP Agent Registry。