> ## 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.

# ACP（Agent Client Protocol）

> 將外部工具連接到 CTOR 的 AI 代理

ACP 讓外部工具可以透過 [Agent Client Protocol](https://agentclientprotocol.org) 與 CTOR 代理互動。您可以使用 [acpx](https://github.com/openclaw/acpx)、[OpenClaw](https://openclaw.ai) 和 [Agmente](https://apps.apple.com/us/app/agmente/id6756249477) 等工具來傳送提示、管理工作階段、協調代理——全都由與桌面 GUI 相同的代理、設定和 MCP 工具驅動。

## 運作原理

桌面應用程式在 Electron 主程序中執行 Unix 通訊端伺服器。橋接 CLI（`bricks desktop-acp-bridge`）在標準輸入輸出和通訊端之間傳遞 ACP JSON-RPC 訊息，讓任何 ACP 用戶端都可以連線。

```
ACP client (acpx, OpenClaw, etc.)
  └─ spawns ─▶ bricks desktop-acp-bridge
                  └─ connects ─▶ Unix socket (~/.bricks-project-desktop/acp.sock)
                                    └─ CTOR (shared agent)
```

由於通訊端伺服器在應用程式內執行，ACP 工作階段與 GUI 共享所有資源：

* **工作階段** —透過 ACP 建立的對話出現在側邊欄，反之亦然
* **設定** —API 金鑰、預設模型和服務商設定來自應用程式
* **MCP 工具** —專案中 `.mcp.json` 設定的工具均可使用
* **技能** —全域和專案技能均已載入

### Session APIs

除了 `session/new` 和 `session/prompt` 之外，橋接還支援：

* `session/list` ——列出磁碟上的工作階段，可依專案 cwd 篩選
* `session/load` 與 `session/resume` ——重新開啟既有工作階段，並串流完整的工具呼叫與訊息時間軸，讓用戶端在重新整理或重新啟動後仍可重建狀態
* `session/set_mode` ——切換思考等級（`off`、`minimal`、`low`、`medium`、`high`、`xhigh`）
* `session/set_model` 與 `session/set_config_option` ——使用桌面 GUI 公開的相同 `provider::name` 識別碼，在工作階段中途切換模型

工作階段啟用期間，所有連線的用戶端都會收到相同的事件串流——從 GUI 發起的提示會即時鏡射到 ACP 用戶端，而 ACP 提示也會在 GUI 中同步顯示。

## 啟用 ACP

ACP 預設為停用。啟用方式：

1. 開啟**設定**（側邊欄中的齒輪圖示）
2. 前往**代理**
3. 切換**啟用 ACP**

通訊端伺服器立即啟動——無需重新啟動應用程式。當 ACP 啟用時，側邊欄底部會出現綠色的 **ACP** 指示符。點擊它可開啟設定。

<Warning>
  在 ACP 模式下（無頭），bash 指令無需核准即可執行。如有需要，請使用 `acpx --deny-all` 覆蓋此設定。
</Warning>

## 前提條件

* [CTOR](/zh-Hant/ctor) 已啟用 ACP 並正在執行
* [BRICKS CLI](/zh-Hant/cli) 已安裝（`bun add -g @anthropic-company/bricks-cli`）
* 工作目錄是 BRICKS 專案（包含 `application.json`）

## 驗證連線

測試橋接是否可以連線到桌面應用程式：

```bash theme={null}
echo '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":1,"clientCapabilities":{},"clientInfo":{"name":"test"}}}' \
  | bricks desktop-acp-bridge
```

若您看到 `Cannot connect to CTOR`，請確保應用程式正在執行且已在設定中啟用 ACP。

## 與 acpx 搭配使用

[acpx](https://github.com/openclaw/acpx) 是 Agent Client Protocol 的無頭 CLI 用戶端。它管理工作階段、排隊提示並串流代理輸出。

### 安裝 acpx

```bash theme={null}
npm install -g acpx
```

### 基本用法

```bash theme={null}
# 在目前專案中建立工作階段
acpx --agent 'bricks desktop-acp-bridge' sessions new

# 發送提示
acpx --agent 'bricks desktop-acp-bridge' "list all files and summarize the project"

# 自動核准所有工具呼叫
acpx --agent 'bricks desktop-acp-bridge' --approve-all "fix the linting errors"

# 靜默模式（僅輸出最終結果）
acpx --agent 'bricks desktop-acp-bridge' --format quiet "what does this project do?"

# 用於自動化的 JSON 輸出
acpx --agent 'bricks desktop-acp-bridge' --format json "run the tests"
```

### 持久設定

將代理新增至 `~/.acpx/config.json` 以避免重複輸入 `--agent`：

```json theme={null}
{
  "agents": {
    "bricks": {
      "command": "bricks desktop-acp-bridge"
    }
  }
}
```

然後使用簡短形式：

```bash theme={null}
acpx bricks sessions new
acpx bricks "refactor the auth module"
acpx bricks sessions list
acpx bricks sessions close
```

## 與 OpenClaw 搭配使用

[OpenClaw](https://openclaw.ai) 透過 acpx 支援 ACP。在 `~/.acpx/config.json` 中設定好 `bricks` 代理後（見上方），OpenClaw 可以連線到桌面應用程式的代理進行多代理協調。

## WebSocket 橋接

對於使用 WebSocket 而非 stdio 的 ACP 用戶端——包含瀏覽器型用戶端與 Agmente iOS app——請以 `--ws` 模式執行橋接器。每個 WebSocket 用戶端都會獲得自己專屬的 ACP Unix socket 連線；一個 WebSocket 文字訊框對應一筆 JSON-RPC 訊息。

```bash theme={null}
# 暴露在 LAN 上（預設）並要求 token——建議做法
bricks desktop-acp-bridge --ws --port 8765 --auth-token "$ACP_TOKEN"

# token 也可以從環境變數帶入
BRICKS_DESKTOP_ACP_BRIDGE_TOKEN="$ACP_TOKEN" bricks desktop-acp-bridge --ws

# 限制為本機
bricks desktop-acp-bridge --ws --host 127.0.0.1 --port 8765
```

<Warning>
  預設綁定主機為 `0.0.0.0`——`--ws` 設計用於 LAN 暴露。請務必設定 `--auth-token` 並僅於受信任網路上執行。未設定 token 時，任何能連到該介面的用戶端都可以連線，橋接器啟動時也會印出警告。
</Warning>

從瀏覽器型用戶端連線時，請在 upgrade 請求中帶入 token：

```js theme={null}
const ws = new WebSocket('ws://127.0.0.1:8765', [], {
  headers: { Authorization: `Bearer ${token}` },
})
ws.onmessage = (e) => console.log('from acp:', e.data)
ws.send(JSON.stringify({ jsonrpc: '2.0', id: 0, method: 'initialize', params: { /* ... */ } }))
```

## 與 Agmente 搭配使用

[Agmente](https://apps.apple.com/us/app/agmente/id6756249477) 是一款 iOS ACP 用戶端，可讓您從 iPhone 或 iPad 與 CTOR 代理對話。它透過 WebSocket 連線，請使用上方的 [WebSocket 橋接](#websocket-橋接)將 ACP socket 暴露於 LAN：

```bash theme={null}
bricks desktop-acp-bridge --ws --port 8765 --auth-token "$ACP_TOKEN"
```

在 Agmente 中將代理連線指向 `ws://<your-mac-ip>:8765` 並提供 token。手機與執行 CTOR 的 Mac 必須位於同一網路——或可透過 VPN、[Tailscale](https://tailscale.com) 之類的通道連線。

連線後，Agmente 會使用上述 [Session APIs](#session-apis) 來列出過往工作階段、繼續使用，並在執行中切換模型或思考等級。您從 Agmente 傳送的提示也會串流至桌面 GUI，反之亦然。

## 複製專案路徑

使用**操作**（右上角下拉選單）> **複製專案路徑**，快速複製目前專案的路徑供外部工具使用。

## 資料

| 項目    | 位置                                   |
| ----- | ------------------------------------ |
| 通訊端檔案 | `~/.bricks-project-desktop/acp.sock` |

<Tip>
  設定 `BRICKS_PROJECT_DESKTOP_DATA_DIR` 環境變數可更改通訊端位置及所有其他應用程式資料。
</Tip>