---
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="/zh-Hant/docs/gemini-cli/official/06-security-enterprise" />
  <Card title="Headless mode" description="如果只是指令碼或 CI 自動化，優先看 headless mode。" href="/zh-Hant/docs/gemini-cli/official/07-integrations-automation/72-headless-mode" />
  <Card title="MCP 設定" description="ACP client 暴露 MCP 能力時，仍要遵守 MCP 最小許可權。" href="/zh-Hant/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)
