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 代理互動。您可以使用 acpx、OpenClaw 和 Agmente 等工具來傳送提示、管理工作階段、協調代理——全都由與桌面 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 建立的對話出現在側邊欄，反之亦然
- 設定 —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 預設為停用。啟用方式：
- 開啟設定（側邊欄中的齒輪圖示）
- 前往代理
- 切換啟用 ACP
通訊端伺服器立即啟動——無需重新啟動應用程式。當 ACP 啟用時，側邊欄底部會出現綠色的 ACP 指示符。點擊它可開啟設定。
在 ACP 模式下（無頭），bash 指令無需核准即可執行。如有需要，請使用 acpx --deny-all 覆蓋此設定。
前提條件
- CTOR 已啟用 ACP 並正在執行
- BRICKS CLI 已安裝（
bun add -g @anthropic-company/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
基本用法
# 在目前專案中建立工作階段
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 時，任何能連到該介面的用戶端都可以連線，橋接器啟動時也會印出警告。
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"
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 環境變數可更改通訊端位置及所有其他應用程式資料。
