---
title: "ACP mode"
description: "Gemini CLI ACP mode 的定位：实验性 agent/editor 协议模式、适用场景和风险边界。"
verifiedAt: "2026-05-09"
---

ACP mode 是 Gemini CLI 面向 IDE 和开发者工具集成的协议模式。官方文档使用 `--acp` 启动，底层通过 stdio 上的 JSON-RPC 2.0 让外部 client 控制 Gemini CLI agent。

它建立的是 client-server 关系：IDE 或自研工具是 client，Gemini CLI 是 server。所有通信走 stdin/stdout，而不是普通交互式 TUI。

> [!NOTE]
> ACP mode 面向 IDE / client 集成开发者，不是普通用户日常启动方式。日常自动化优先看 headless mode。

## 使用方式

```bash
gemini --acp
```

## 适合场景

- 编辑器集成测试。
- agent protocol 实验。
- 工具链开发者。
- 自研 client 需要通过标准协议控制 Gemini CLI。
- IDE 想通过自己的 MCP server 暴露工具给 Gemini CLI。

## 不适合场景

- 第一次上手 Gemini CLI。
- 课程教程的默认路径。
- 团队稳定生产流程。

## 协议机制

ACP 建立的是 client-server 关系：你的 IDE 或工具是 client，Gemini CLI 是 server。client 发送 `initialize`、`authenticate`、`newSession`、`prompt`、`cancel` 等 JSON-RPC 请求；Gemini CLI 处理后返回结果或通知。

ACP 可以和 MCP 配合：ACP client 在初始化时提供 MCP server 连接信息，Gemini CLI 连接这个 MCP server 后，把 IDE 暴露的能力当作工具给模型使用。这样 IDE 既能控制 agent，也能把自己的文件、编辑、诊断能力暴露给 agent。

## 安全边界

ACP 包含 proxied file system service。也就是说，agent 读写文件时通过 ACP client 代理执行，访问范围应由 client 和用户明确授权。工具链开发者不能把它当成本机无限制文件访问。

| 能力 | ACP 中的边界 |
| --- | --- |
| 文件读写 | 通过 client 代理，client 应控制范围 |
| Session | client 创建、加载、取消会话 |
| 模型 | session 内可切换，但仍受账号可用性影响 |
| MCP | client 可在 initialize 时提供 MCP server |
| Telemetry | 本地日志可能包含协议消息和路径 |

## 调试方式

普通协议调试可以加 `--debug`：

```bash
gemini --acp --debug
```

这类调试日志可能包含协议消息、文件路径和会话状态。真实项目排障时要先确认日志保存位置和脱敏方式，不要把 ACP debug 日志直接贴到公开 issue。

需要记录详细事件时，可以开启本地 telemetry：

```text
GEMINI_TELEMETRY_ENABLED=true
GEMINI_TELEMETRY_TARGET=local
GEMINI_TELEMETRY_OUTFILE=/path/to/acp-log.json
```

## 验收方式

先用最小 client 完成 `initialize` 和一轮 `prompt`，再测试 `cancel`、session mode 和文件系统代理。不要一开始接入真实 IDE 写操作；先用只读目录和临时测试项目验证协议消息、权限边界和日志。

## 最小测试顺序

ACP 集成不要一开始接入完整 IDE。建议按这个顺序推进：

1. `gemini --acp --debug` 能稳定启动。
2. client 能完成 `initialize`。
3. client 能发起一个只读 `prompt`。
4. `cancel` 能中止长任务。
5. 文件系统代理只允许测试目录。
6. telemetry 日志不包含 token、私有路径或客户数据。

这条路径能先验证协议，再验证权限，最后才验证真实编辑器体验。

## 不要用 ACP 解决什么

如果只是想在脚本里调用 Gemini CLI，用 headless mode；如果只是想接外部服务，用 MCP；如果只是想让 IDE 打开终端执行命令，用普通 CLI 就够。ACP 的价值在于让 client 通过协议控制会话、权限和文件代理，不是替代所有自动化入口。

因此教程里的推荐顺序应该是：普通 CLI、headless、MCP、IDE integration，最后才是 ACP。只有当你要开发 editor/client 集成时，ACP 才是主角。

## 接下来去哪

<Cards>
  <Card title="安全与企业" description="模型运行时结束后，继续看 sandbox、policy、enterprise config 和隐私边界。" href="/docs/gemini-cli/official/06-security-enterprise" />
  <Card title="Headless mode" description="如果只是脚本或 CI 自动化，优先看 headless mode。" href="/docs/gemini-cli/official/07-integrations-automation/72-headless-mode" />
  <Card title="MCP 设置" description="ACP client 暴露 MCP 能力时，仍要遵守 MCP 最小权限。" href="/docs/gemini-cli/official/03-tools-mcp/35-mcp-setup" />
</Cards>

## 官方来源

- [Gemini CLI ACP mode](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/acp-mode.md)
- [Agent Client Protocol](https://agentclientprotocol.com/get-started/introduction)
