ACP（Agent Client Protocol）

ACP 讓外部工具可以透過 Agent Client Protocol 與 CTOR 代理互動。您可以使用 acpx、OpenClaw 和 Agmente 等工具來傳送提示、管理工作階段、協調代理——全都由與桌面 GUI 相同的代理、設定和 MCP 工具驅動。

本頁涵蓋外部工具連線進入 CTOR 內建代理的情境。至於反過來——由 CTOR 驅動 Claude Code、Codex、Pi 或 Cursor Agent 作為聊天背後的代理——請參閱 CLI 代理。由 CLI 代理提供支援的聊天無法透過此橋接驅動，請參閱同時使用兩種 ACP 功能。

運作原理

桌面應用程式在 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、max）
session/set_model 與 session/set_config_option ——使用桌面 GUI 公開的相同 provider::name 識別碼，在工作階段中途切換模型

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

啟用 ACP

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

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

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

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

前提條件

CTOR 已啟用 ACP 並正在執行
BRICKS CLI 已安裝（bun add -g @fugood/bricks-cli）
工作目錄是 BRICKS 專案（包含 application.json）

驗證連線

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

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 是 Agent Client Protocol 的無頭 CLI 用戶端。它管理工作階段、排隊提示並串流代理輸出。

安裝 acpx

npm install -g acpx

基本用法

# 在目前專案中建立工作階段
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：

{
  "agents": {
    "bricks": {
      "command": "bricks desktop-acp-bridge"
    }
  }
}

然後使用簡短形式：

acpx bricks sessions new
acpx bricks "refactor the auth module"
acpx bricks sessions list
acpx bricks sessions close

與 OpenClaw 搭配使用

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

WebSocket 橋接

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

# 暴露在 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

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

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

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 是一款 iOS ACP 用戶端，可讓您從 iPhone 或 iPad 與 CTOR 代理對話。它透過 WebSocket 連線，請使用上方的 WebSocket 橋接將 ACP socket 暴露於 LAN：

bricks desktop-acp-bridge --ws --port 8765 --auth-token "$ACP_TOKEN"

在 Agmente 中將代理連線指向 ws://<your-mac-ip>:8765 並提供 token。手機與執行 CTOR 的 Mac 必須位於同一網路——或可透過 VPN、Tailscale 之類的通道連線。連線後，Agmente 會使用上述 Session APIs 來列出過往工作階段、繼續使用，並在執行中切換模型或思考等級。您從 Agmente 傳送的提示也會串流至桌面 GUI，反之亦然。

複製專案路徑

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

資料

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

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

入門指南

專案開發

發佈應用

參考

更新日誌

ACP（Agent Client Protocol）

運作原理

Session APIs

啟用 ACP

前提條件

驗證連線

與 acpx 搭配使用

安裝 acpx

基本用法

持久設定

與 OpenClaw 搭配使用

WebSocket 橋接

與 Agmente 搭配使用

複製專案路徑

資料

​運作原理

​Session APIs

​啟用 ACP

​前提條件

​驗證連線

​與 acpx 搭配使用

​安裝 acpx

​基本用法

​持久設定

​與 OpenClaw 搭配使用

​WebSocket 橋接

​與 Agmente 搭配使用

​複製專案路徑

​資料

運作原理

Session APIs

啟用 ACP

前提條件

驗證連線

與 acpx 搭配使用

安裝 acpx

基本用法

持久設定

與 OpenClaw 搭配使用

WebSocket 橋接

與 Agmente 搭配使用

複製專案路徑

資料