維運同學常在安靜的安全修補後把鍋甩給「OpenClaw 壞了」，而真正的問題往往是透明同意與控制（TCC）悄悄收回了你上個月搬過路徑的閘道二進位的螢幕錄製或輔助使用。本 playbook 把症狀對應到權限面，給出兩張決策矩陣（先開哪個面板、何時優先 VNC 而非 SSH），七條與 JSON-LD 對齊的 HowTo 步驟，以及可貼進事故單的 FAQ；並鏈到 doctor 與完整安裝指南。把「批准了哪個二進位」寫進 Git，比事後猜路徑可靠得多。
症狀與 TCC 桶對應
- 截圖或串流 UI 的工具呼叫瞬間失敗，日誌含權利錯誤 → 螢幕錄製。
- AppleScript 或 AX 自動化回傳空樹，閘道程序仍存活 → 輔助使用。
- 系統升級後某些 Library 路徑讀取突然拒絕 → 給精確輔助二進位完整磁碟取用，而非僅啟動它的 shell。
建議為每類症狀維護「首屏截圖」範本：事故單裡直接貼系統設定列表與二進位全路徑，減少二次溝通。對多區域機群，把 macOS 建置號與閘道版本號並排紀錄，避免「香港機壞了日本沒事」這類無法重現的敘述掩蓋真實差異。
矩陣 A — 應先打開哪個設定面板
| 主訊號 | 第一面板 | 第二面板 | 應收集證據 |
|---|---|---|---|
| 像素緩衝 API 失敗 | 螢幕錄製 | 檔案與檔案夾 | 主控台過濾近一小時 tccd 拒絕 |
| AXUIElementCopyAttributeValues 錯誤 | 輔助使用 | 自動化 | 取樣 3 條失敗 AX 查詢並帶時間戳 |
| 受保護路徑 EPERM | 完整磁碟取用 | 本機網路 | 精確 POSIX 被拒路徑，勿用脫敏摘要 |
矩陣 B — 修復通道與風險
| 通道 | 可點 TCC 彈窗 | 利於稽核 | 何時優先 |
|---|---|---|---|
| 僅 SSH | ✗ | ✓ | 彈窗已清除後的日誌追蹤與 plist 編輯 |
| VNC 圖形工作階段 | ✓ | ✓ | 升級後首次恢復；參見 VNC 指南 |
| MDM 宣告的 PPPC 負載 | 不適用 | 最佳 | 企業整機隊；金絲雀仍應用 doctor 驗證 |
展開七步 HowTo 的維運細節
第一步應先跑 doctor 診斷，避免盲改設定。第二步務必讀出系統列表裡的精確二進位名：Homebrew 升級常搬二進位，而 LaunchAgent 仍指向舊路徑，導致 TCC 開關看似開著卻不生效。
第三步是乏味的開關舞：刪陳舊項目、互動式啟動新二進位一次、再授權，然後把 plist 路徑鎖進 Git。第四步在升級後首次恢復時不可省——SSH 點不了「打開系統設定」表單。第五步重跑 doctor，把 JSON 輸出與 macOS 建置號一併歸檔給稽核。
第六步優先 launchctl bootout 再 bootstrap，少用 kill -9，以免 TCC 狀態與 Mach 服務不一致。第七步呼叫先前失敗的無害工具：不要只用聊天延遲判斷，因為聊天成功時工具管線仍可能被擋。
首次安裝請對照 macOS 完整安裝與部署，避免批准錯誤的輔助二進位。對多閘道拓撲，在 runbook 裡畫清「哪個 LaunchAgent 拉起哪個 Node 二進位」，否則容易出現「CLI 已授權、Agent 未授權」的分裂。
若你在 NodeMac 獨佔機上使用自訂前置詞安裝，請在內部 wiki 寫明「批准路徑」與「實際執行路徑」對照表；新人 onboarding 時做一次 VNC 錄影存檔，能顯著降低週末值班的電話量。把 TCC 變更與發布列車綁定，而不是與「某人記得點一下」綁定。
為何「昨天還行」幾乎總是路徑不一致
macOS 將 TCC 授權綁定到 inode 與 Team ID 等，而非行銷名。brew 升級搬動通用二進位後，舊開關可能仍顯示勾選，而執行中的程序其實是另一個從未獲批的檔案。所以要關掉再開：強制設定 UI 綁定到你剛從 /opt/homebrew 或 NodeMac 自訂前置詞啟動的現路徑。
同時紀錄閘道可執行檔與任何執行特權讀取的輔助程序。團隊常批准 CLI 包裝器，而 LaunchAgent 使用仍缺輔助使用的巢狀 Node——doctor 可能仍綠，因為它探測的路徑與生產流量不同。
量化護欄（常被遺忘）
- 重批 SLA：任何 macOS 安全回應發布後 24 小時內完成 TCC 冒煙。
- 證據包：每張事故單至少附 2 段主控台摘錄與一份 doctor JSON。
- 金絲雀機：每區域保留 1 台 staging Mac mini，提前二十四小時接修補。
提示：紀錄閘道建置與程式碼簽署 Team ID 的對應，避免安全審閱把開發者簽名的夜間建置與發布簽名的生產二進位混淆。
FAQ
重置隱私權項目會弄壞其他 App 嗎？
只影響你刪除的項目。若合規要求可回復，按類別漸進操作並在變更前拍照設定。
NodeMac 區域會改變 TCC 行為嗎？
不會——港、日、韓、新、美主機跑同一 macOS 建置；差異主要在延遲影響你用 VNC 點提示的速度，以及服務看門狗是否搶先重啟。
新手應先讀哪裡？
先看 說明中心 的 SSH 基礎，再在首次升級週末回到本頁。
落地清單（可貼進 wiki）
把下列檢查項做成可複製清單：① 紀錄閘道 plist 與二進位 sha256；② 升級前後各跑一次 doctor 並 diff；③ 在 VNC 工作階段中完成首屏授權並錄影；④ 將 LaunchAgent 變更走 code review；⑤ 金絲雀通過後滾動到生產。對受監管客戶，把「誰點了哪個系統設定開關」對應到變更單號，而不是散落在個人聊天紀錄裡。把本頁與 launchd 重啟 runbook 交叉連結，可在閘道抖動時快速判斷是 TCC 還是服務生命週期問題。
當團隊從筆電試驗遷到雲端獨佔機時，最容易忽略的是「個人 Apple ID 與機群帳戶」混用導致的鑰匙圈與隱私權列表污染。統一使用服務帳戶登入圖形工作階段完成一次性授權，再把日常自動化切回 SSH，可把此類問題一次性根治。
TCC 衛生是把每台 Mac mini M4 當作嚴肅自動化節點的一部分：Apple Silicon 並不會讓蘋果隱私權模型失效。原生 macOS 閘道需要 SSH 做可重複修復，也需要 VNC 讓人類確認必須點掉的同意框。在香港、日本、韓國、新加坡或美國 租用專用 Mac mini M4 可取得隔離機器，避免與個人筆電組態互相污染。升級來臨，可預測硬體 加文件化矩陣勝過玄學——若要按區域拆分金絲雀與生產機隊，請打開 定價 比對方案。