工具表面與權限：模型到底能碰什麼
免責聲明：本文整理自官方 v2.1.15 的 tool-surface.md 與 setup.md，以社群角度改寫。實作與測試才是權威；細節以你的 app 版本為準。
先講結論：工具面是「當下狀態」的函數
ChatGPT 裡看到的工具清單，不是固定菜單，而是由四個因素共同決定：
- 你連了哪個 connector——Core、Desktop、Plugins 各自獨立（也各自有獨立的 token 路徑）。
- 權限與模式——例如 Read-only 模式會移除實際的寫入／指令／控制權限。
- 作業系統——Desktop 工具只在 Windows／macOS 出現，Linux 一律不提供。
- 當下快照——有些工具是條件式出現的（例如
find只在搜尋開啟、且該快照下不能執行指令時，才作為搜尋後備）。
而且有一個容易誤解的性質：工具在對話中一旦暴露過就不會中途消失（單一 connector 實例內的暴露是單調的），但處理器永遠以當前權限檢查每次呼叫。所以「清單裡還有」不代表「現在還跑得動」——權限改掉了，呼叫就會被拒。
Core connector（全平台）
| 工具 | 一句話 | 值得記住的細節 |
|---|---|---|
read |
讀取核准路徑 | 一次可多路徑、列目錄一層、展開有界 glob、支援行範圍與圖片。單檔預設 256 KB、單次總量 512 KB——官方刻意把「批次讀取、整檔讀取」設成便宜路徑，因為 round trip 比 bytes 貴。 |
view_image |
Codex 相容的專用圖片工具 | 獨立於 read，受 read 權限閘控；傳輸與解碼有界。 |
find |
搜尋後備 | 當搜尋開啟、但快照建立時不能執行指令時使用；檔名／glob 與文字搜尋，不給 shell。 |
apply_patch |
文字修改原語 | V4A patch 信封；多檔 patch 先 preflight 再寫入；create／edit／move／delete 各自獨立檢查權限；目錄刪除與任意二進位寫入不會藏在 patch 裡。 |
exec_command |
在真實 shell 執行 | 不受核准資料夾限制。接受單一 cmd 或最多 20 條 cmds：整批共用一個 shell session，變數、環境與工作目錄跨條目延續；每條有標籤輸出與自己的 exit code，一般非零不會中斷後續（整批 exit code 取第一個非零）。長指令回傳 session_id。 |
write_stdin |
續接或輪詢長指令 | 以 session_id 寫入或輪詢；chars 留空＝poll。空 poll 一旦有新輸出就返回，之後到貨的內容留在緩衝等下一次。 |
update_plan |
更新顯示中的進度計畫 | recording 開啟時可用；替換的正是「呼叫者自己」的計畫，不會執行排隊工作。模型看不到 save_handoff／resume_session——那是 app 層編排。 |
agents |
worker 團隊操作 | multi-agent 模式開啟時可用，四個動作：spawn／message／status／finish。細節見worker 團隊、Goal／Loop 與續航。 |
小抄：全新預設下，Core 會廣告
read、view_image、apply_patch、exec_command、write_stdin、update_plan、agents；find是條件式後備。
Desktop connector（Windows／macOS 限定）
| 工具 | 做什麼 | 重點 |
|---|---|---|
observe |
不搶焦點的桌面狀態讀取：截圖、視窗、snapshot 範圍的 UI 控制資訊 | 視窗擷取先走背景路徑，可能被遮擋時會標示「可見畫面 fallback」；螢幕讀取與滑鼠鍵盤控制是分開的權限。 |
computer |
有界的批次桌面動作 | 動作集：click_ref、set_value、click、double_click、move、drag、scroll、type、keypress、focus、wait、read_clipboard、write_clipboard。每一步都對當前權限檢查；click_ref 會在用物理輸入前重新驗證目標視窗幾何，語意 ref 過期就失敗（不會瞎猜重掃）。可選 verify 後置條件（等前景視窗、視窗開／關、控制項出現／消失）並在同一次呼叫捕捉結果。 |
權限不變量（為什麼這些規則值錢）
- 呼叫期檢查：無論 schema 何時暴露過，每次呼叫都對當前權限檢查。
- 互不轉發：Core 與 Desktop 不代轉、不別名彼此的工具有；一個 connector 的 token 不對另一個 surface 授權。
- Read-only 是真實收斂：移除有效的檔案寫入、指令、桌面控制與剪貼簿寫入權限——但不假裝底層設定被改了。
- 核准資料夾不是沙盒：它約束的是檔案工具箱，
exec_command與桌面控制仍以你的一般使用者權限在整個機器上行動。 - 結果有界：工具結果與驗證錯誤都有上限；大型結構化或二進位 payload 不能無上限成長。
全新安裝的預設值（依 OS 不同）
| 平台 | Core | Desktop | 備註 |
|---|---|---|---|
| Windows | 開啟＋2 個 workers | 開啟 | 預設最寬鬆的組合，請先檢視 |
| macOS | 開啟＋2 個 workers | 關閉（自行開啟） | 開啟時需授權螢幕錄製與輔助使用 |
| Linux | 開啟＋2 個 workers | 遮罩 | 保留你儲存的選擇，但執行期不提供 |
既有安裝升級時會保留你原本的明確選擇；缺少的 legacy 權限不會被默默放寬。
Read-only 模式：什麼時候該用
- 只是要 ChatGPT「看懂專案」——審查、解釋、產生計畫——寫入與指令權限全是風險，不需要。
- 觀察仍可用：Desktop 的
observe可以在 read-only 下保持可用，只有會改變狀態的桌面動作被停。 - 注意：Read-only 會拒絕外掛呼叫（因為無法證明外部程序不會造成變更）。
升級後工具不見了？這是快取問題
舊對話可能保留升級前的 MCP schema 快取。處理順序：
- 在 ChatGPT 中 refresh／review 對應的 CoS app（必要時重建 app）。
- 若 connector 暴露的工具形狀變了，開新對話。
- extension 版本不符時 reload extension，再 refresh ChatGPT 頁面（兩個步驟）。
目前的 companion extension 會自動配對本地 bridge——沒有配對碼要輸入。
下一步
- 逐項參數、錯誤碼與外掛轉發：工具速查
- worker、Goal／Loop 與續航機制：worker 團隊、Goal／Loop 與續航
- 實戰：修一個失敗的測試