> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bricks.tools/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI 代理

> 透過 ACP，以本機 CLI 程式碼代理（Claude Code、Codex、Pi 或 Cursor Agent）驅動聊天

聊天工作階段可以改由本機 CLI 程式碼代理提供支援，而非使用 CTOR 自身內建的代理。CTOR 會啟動該 CLI，並以 [ACP（Agent Client Protocol）](/zh-Hant/ctor/reference/acp)與其溝通，因此能以驅動自身代理的相同方式驅動它——傳送提示、顯示工具呼叫，並將回應呈現在您的聊天中。

<Info>
  CLI 代理是 **Preview** 功能。
</Info>

<Note>
  這與 [ACP](/zh-Hant/ctor/reference/acp) 的方向相反：該頁面涵蓋*外部*工具連線進入 CTOR 內建代理的情境。CLI 代理則是讓 CTOR 本身成為 ACP 用戶端，驅動 Claude Code、Codex、Pi 或 Cursor Agent 作為個別的 CLI 工具。這兩者無法串接在一起——請參閱[同時使用兩種 ACP 功能](#同時使用兩種-acp-功能)。
</Note>

## 選擇引擎

全新的空白聊天會在模型選擇器旁顯示一個**引擎**標籤。點選即可選擇後端：

* **內建代理** —CTOR 自身的代理，除非您另行選擇，否則為每個聊天的預設值
* 每個 CLI 引擎各佔一個項目——**Claude Code**、**Codex**、**Pi**、**Cursor Agent**——列於 **CLI 代理 (Preview)** 標題之下，並各自顯示偵測到的版本

無法使用的引擎仍會顯示，但會停用，並標示為**尚未安裝**或**需要更新——此版本不支援 ACP**。

<Warning>
  聊天一旦有訊息，引擎的選擇就會鎖定。之後無法切換聊天的引擎——請開新聊天以使用不同的引擎。
</Warning>

工作階段所使用的引擎，也會以小圖示顯示在側邊欄中其標題旁。

## CLI 引擎

| 引擎               | 安裝                                                                         | 最低版本                | 驗證                              |
| ---------------- | -------------------------------------------------------------------------- | ------------------- | ------------------------------- |
| **Claude Code**  | 隨 CTOR 內建——無需另外安裝。若偵測到系統安裝版本，會優先使用。                                        | 2.1.0（僅限系統安裝版本）     | 您現有的 Claude Code 登入             |
| **Codex**        | 隨 CTOR 內建——無需另外安裝。若偵測到系統安裝版本，會優先使用。                                        | 0.144.0（僅限系統安裝版本）   | 您現有的 Codex 登入（ChatGPT 或 API 金鑰） |
| **Pi**           | CTOR 內建連接器；需要在您的 `PATH` 中另行安裝 [`pi`](https://github.com/earendil-works/pi) | 未強制要求——偵測到的任何版本皆可使用 | 在終端機執行 `pi` 以登入並設定供應商           |
| **Cursor Agent** | 需要在您的 `PATH` 中另行安裝 [`cursor-agent`](https://cursor.com/docs/cli)           | 2026.01             | 您現有的 Cursor Agent 登入            |

Claude Code 與 Codex 開箱即用——CTOR 已內建連接器與 CLI 本身，無需另外安裝。Pi 與 Cursor Agent 則不然：CTOR 內建了 Pi 的連接器，但 `pi` 與 `cursor-agent` 執行檔本身都需要您自行安裝，因此兩者都只有在您自行安裝後才會顯示為選項（Cursor Agent 則還需要是 2026 年以後的版本——較舊版本不支援 ACP）。

若 CLI 代理尚未登入，CTOR 會顯示通知——*「{engine} 尚未登入。請在終端機執行下方指令後再重新送出訊息。」*——並提供登入指令的**複製**按鈕。執行後再重新送出您的訊息。

## 啟用與設定

開啟**設定 > 代理 > CLI 代理 (Preview)**：

* **CLI 代理**開關 —開啟或關閉此功能，預設為啟用。
* 為每個引擎（`claude`、`codex`、`pi`、`cursor-agent`）提供路徑覆寫 —指定 CTOR 使用特定執行檔，而非自動偵測到的版本。留空則自動偵測。設定您自己的安裝版本，可讓您透過 `claude update` / `codex update` 自行保持最新，並使用您自己的外掛與技能，而不必依賴 CTOR 內建的版本。

每一列也會顯示偵測到的版本，以及該版本是您的系統安裝版本，還是 CTOR 內建的版本。

<Note>
  關閉此開關並不會將引擎選擇器從新聊天中移除——只會在您嘗試於 CLI 代理聊天中送出訊息時加以封鎖。請在以 CLI 引擎開始聊天之前關閉，而不是事後才關閉。
</Note>

## 模型、模式與推理強度

CLI 代理聊天中的模型、模式，以及（若支援）推理強度選擇器，都直接來自該 CLI 本身——CTOR 不會篩選或新增項目。各引擎可用的項目不盡相同：

* **Claude Code** —模型與模式來自您自己的 Claude Code 設定與訂閱方案，因此確切清單因人而異。支援的模型會顯示推理強度選擇器。
* **Codex** —推理強度已內建於模型本身，因此沒有獨立的強度選擇器；模式範圍從唯讀到完整寫入權限都有。在支援的版本上，Codex 工作階段會改為提供 **Normal / Fast** 速度切換。
* **Pi** —模型來自您自己的 Pi 設定。Pi 將其工作階段模式與推理強度視為同一項底層設定，因此 CTOR 只會顯示強度選擇器——不提供獨立的模式選擇器——其層級比 Claude Code 更多，最高可達 **Max**。
* **Cursor Agent** —模型與模式來自您的 Cursor Agent 安裝；沒有強度選擇器。

<Note>
  CLI 引擎自身提供的「Plan」模式（如果有的話），是比 CTOR 自身的[計畫模式](/zh-Hant/ctor/reference/plan-mode)功能更輕量的機制。CTOR 的計畫模式無法在 CLI 代理聊天中使用——只能使用該 CLI 自身的模式選項。
</Note>

## 工具核准

當 CLI 代理想要執行尚未取得允許的指令或工具時，CTOR 會顯示核准卡片，列出該動作以及該 CLI 提供的確切回應選項——這些選項依引擎略有不同，但一律包含某種形式的僅允許一次、一律允許與拒絕。「一律允許」的選擇會由該 CLI 自身記住，使用您在 CTOR 之外已為它設定好的信任設定。

<Warning>
  Pi 是例外：無論是自身的工具，還是透過 CTOR 橋接提供的 MCP 工具，Pi 都不會向 CTOR 傳送核准請求。Pi 的每一次工具呼叫——包括檔案編輯與 shell 指令——都會立即以您的作業系統使用者權限執行，沒有 CTOR 核准卡片可加以管控。
</Warning>

<Warning>
  CLI 代理工作階段完全在 BRICKS 的[沙箱](/zh-Hant/ctor/reference/sandbox)之外執行。該 CLI 擁有與您在終端機中相同的檔案與 shell 存取權限，僅受其自身的許可權系統管控——不受 BRICKS 的沙箱設定、網路核准或危險指令偵測約束。
</Warning>

## 代理在您的專案中可以做什麼

為專案聊天提供支援的 CLI 代理，擁有與內建代理相同的兩項處理您應用程式的能力：

* **操作執行中的[模擬器](/zh-Hant/ctor/reference/simulator)** —開啟模擬器、對執行中的應用程式進行操作，並擷取會直接顯示於聊天中的螢幕截圖。
* **透過[編輯器](/zh-Hant/ctor/reference/editor)進行結構化編輯** —而不必直接手動編輯設定檔。

對於[主聊天](/zh-Hant/ctor/guide/main-chat)工作階段，則改為擁有對等的協調能力——建立、列出並管理其他工作階段。

若代理需要向您詢問澄清問題，會以卡片形式顯示在輸入列附近，與內建代理的澄清問題相同。

您的[全域與專案技能](/zh-Hant/ctor/reference/skills)仍然可用——CTOR 會告訴 CLI 代理去哪裡找到每一項技能，當任務需要時，它會像讀取其他檔案一樣讀取其中的指示內容。

您專案自身的 [MCP 伺服器](/zh-Hant/ctor/reference/mcp)在不同引擎上提供的方式也不同：Claude Code 會自行讀取您專案的 `.mcp.json`；Cursor Agent 會從 CTOR 取得您專案的伺服器與繼承的伺服器，並為每一個顯示自己的核准提示；Pi 並不原生支援 MCP 伺服器，因此 CTOR 會改為透過與其自身桌面工具相同的橋接來代理這些伺服器，以一般工具的形式提供給 Pi，且不會有獨立的核准步驟（見上方警告）；Codex 工作階段目前無法存取您專案設定的 MCP 伺服器。

## 工作階段行為

CTOR 大部分的工作階段功能，在 CLI 代理聊天中運作方式相同——分支對話、編輯並重新傳送訊息，以及 `/undo` 都能正常使用。由於 CLI 自身的對話無法直接編輯，這些操作會與該 CLI 開啟一段全新的對話，並以歷史紀錄的摘要作為開頭以提供脈絡；您在 CTOR 中看到的聊天記錄則完全不受影響。在非常長的對話中，該摘要可能不如該 CLI 自身的原生記憶來得完整。

重新開啟 CLI 代理聊天會立即顯示完整的歷史紀錄，不需要重新連線。若 CTOR 無法在背景中恢復該 CLI 自身的工作階段（例如長時間未使用，或 CLI 已更新），您會看到拋棄式的通知——*「CLI 代理工作階段已重新啟動——先前的內容已為代理整理成摘要，上方的完整歷史紀錄則維持不變。」*——接著對話會正常繼續。

有幾項內建代理的功能，在 CLI 代理聊天中無法使用：

* [`/goal`](/zh-Hant/ctor/reference/commands#goal) 與 [`/compact`](/zh-Hant/ctor/reference/commands#compact) —CLI 自行管理其上下文，因此不提供這兩個指令。
* 回合中途引導 —在 CLI 執行時傳送的訊息會先排入佇列，待目前回合結束後才以後續訊息的形式送出，而不會立即重新導向。
* 自訂 [hooks](/zh-Hant/ctor/reference/hooks) 不會針對該 CLI 自身的工具呼叫觸發。

上下文長度指標會顯示於 Claude Code 與 Codex 工作階段中（Codex 還會顯示費用估算），但不會顯示於 Pi 或 Cursor Agent，因為兩者都不會回報用量。

## 主聊天中的 CLI 代理

當[主聊天](/zh-Hant/ctor/guide/main-chat)產生新的專案工作階段時，預設會使用主聊天自身所執行的相同 CLI 引擎。若您希望該工作階段改用內建代理執行，請直接要求代理即可。

## 同時使用兩種 ACP 功能

由 CLI 引擎提供支援的聊天，無法由外部 ACP 用戶端驅動（請參閱 [ACP](/zh-Hant/ctor/reference/acp)）——它仍會出現在該用戶端的工作階段清單中，但從 CTOR 外部嘗試載入、繼續、重新設定或提示該工作階段，都會被乾淨地拒絕而不會出錯。CLI 代理工作階段請使用 CTOR 自身的聊天介面。

## 後續步驟

<CardGroup cols={2}>
  <Card title="ACP" icon="plug" href="/zh-Hant/ctor/reference/acp">
    將外部工具連接到 CTOR 的內建代理。
  </Card>

  <Card title="沙箱" icon="shield-halved" href="/zh-Hant/ctor/reference/sandbox">
    了解 CLI 代理工作階段在其之外執行的沙箱。
  </Card>
</CardGroup>