判斷｜適合按授權層逐項排查；節點在線只表示連線狀態正常，並不代表命令已獲准。先確認命令面與各層授權，再用同一條無破壞性命令及實際 Xcode 建置確認執行位置與結果。
維護 OpenClaw 與 macOS 執行節點的工程師，可用本文定位 Agent 連得上、卻無法執行命令的情況。
負責 Apple 平台 CI 的開發者，可據此確認遠端命令是否真的在目標 Mac 上執行。
管理 Agent 權限與節點策略的 DevOps 工程師，可用檢查清單建立可稽核、避免過度授權的復原流程。
最後更新於 2026 年 10 月 27 日；核對 OpenClaw 官方節點排障、配對、命令策略與執行審批文件，以及官方 Xcode 命令列工具說明。
00先區分連線正常與命令獲准
OpenClaw 遠端 Mac 命令執行失敗時，先不要假定是網路或 Xcode 問題。節點狀態、節點配對、命令面是否可用、Gateway 策略、節點本機執行審批，以及 Agent 選擇的執行目標，分別代表不同檢查邊界；其中一層通過，不會自動讓其他層也通過。OpenClaw 官方文件將節點排障、配對、命令策略與執行審批分開說明，可先依照對應狀態及日誌定位拒絕發生的位置：節點排障說明。
這也是「節點顯示已連線，但 Agent 不能執行命令」最常見的判讀誤區：連線成功只能證明節點能與系統通訊，不能證明 system.run 已被允許，也不能證明該命令已送到預期的 Mac。
01從節點配對與命令面找出缺口
節點配對確認的是節點身分及其配對狀態，不等同於批准節點上的命令執行。請先查看節點目前的配對狀態、待處理的核准請求，以及節點描述中的可用命令；若 system.run 未列為可用命令，應先處理命令面狀態，不要直接放寬 Gateway 或節點本機權限。配對狀態與請求的處理方式，請對照官方節點配對文件。
接著確認 Agent 送出的操作是否確實使用 OpenClaw system.run，並檢查實際回應屬於「命令不可用」、「等待審批」還是「執行遭拒」。這些訊息指向不同層級；只看節點在線圖示，無法判定是哪一層拒絕了命令。
02依拒絕訊息檢查 Gateway 與節點本機授權
如果命令面已可用，下一步就檢查 Gateway 對節點命令的 allow／deny 策略。核對策略中使用的命令識別、套用的規則及相關記錄，並確認是否由全域設定阻擋，或是節點未宣告該命令。不要以「先全部放行」作為排錯方法：這會把授權問題藏起來，卻無法證明實際工作流程只使用了必要權限。策略判讀應依據官方節點命令策略文件。
若回應包含 approval required 或 allowlist miss，再檢查節點本機的執行審批、命令允許清單及人工確認流程。節點本機審批與節點配對紀錄不是同一項狀態；配對已完成，仍可能因命令未通過本機政策而無法執行。審批行為及設定邊界應對照官方執行審批文件，而不是在排障時改成不受限執行。
| 錯誤表象或證據 | 優先檢查位置 | 可支持的判斷 |
|---|---|---|
| 節點未配對或有待處理請求 | 配對狀態與核准請求 | 先確認節點身分與配對流程，不先改命令政策 |
system.run 不在可用命令中 |
節點命令面與節點描述 | 命令面尚未具備，或節點沒有宣告該命令 |
| Gateway 記錄顯示拒絕 | Gateway 節點命令策略 | 核對實際命令識別及套用的 allow／deny 規則 |
approval required 或 allowlist miss |
節點本機審批與允許清單 | 命令到達節點，但需要審批或未符合本機規則 |
| 命令成功，但輸出與預期環境不符 | Agent 目標、遠端帳戶與工具鏈 | 可能執行在其他節點、其他帳戶或不同專案目錄 |
表格中的線索是排查起點，不是單憑錯誤字串即可定案的保證。應把 Gateway 記錄、節點回應與實際執行結果對照，並以官方節點命令執行說明確認命令如何送往節點。
03確認 Agent 實際呼叫哪一台 Mac
當命令已獲准卻仍「沒有在 Mac 上執行」，要先核對 Agent 的 exec 是否明確指定預期節點。環境中若有多個可執行節點，僅憑命令成功回應，不能證明它是在指定主機上完成。檢查請求中的目標、節點描述與執行記錄是否一致，再於目標 Mac 上執行不會修改專案或系統的查詢命令，例如：
id -un
pwd
這兩項輸出可協助確認遠端命令使用的帳戶與工作目錄；但仍應與節點識別及執行記錄一起判讀，不能把目錄名稱或帳戶名稱當成主機身分的唯一證據。若遠端帳戶沒有預期的工作區存取權，或工作目錄不正確，應先修正 Agent 的目標與工作目錄設定，而非更動命令審批。
04用 Xcode 命令列建置驗證工具鏈
確認命令執行在目標 Mac 後，才檢查 Xcode 命令列工具與專案路徑。先取得活動開發者目錄及 Xcode 版本：
xcode-select -p
xcodebuild -version
若輸出的開發者目錄不是預期的 Xcode 安裝位置，或 xcodebuild 無法使用，應檢查目標 Mac 是否已安裝 Xcode，以及活動開發者目錄是否指向預期工具鏈。官方說明指出，使用 Xcode 命令列工具前需要安裝 Xcode，並將其設定為活動開發者目錄；可依官方 Xcode 命令列工具安裝說明核對，不要只憑本機開發機的工具鏈狀態推定遠端也相同。
確認工具鏈後，再從專案目錄查詢專案或工作區可用的建置目標，並以團隊原本使用的 scheme、destination 與建置設定執行最小建置。驗收時記錄實際命令、執行節點、帳戶、工作目錄及建置輸出。這一步回答的是「遠端 Mac 能否使用預期 Xcode 建置該專案」，而不是替代完整的簽署、測試或發布驗證。
05用可勾選清單完成修復驗收
每次只修正一個被證據指向的邊界，再重跑同一項無破壞性命令；若一次同時放寬多層政策，就難以追溯哪項調整真正有效，也無法確認是否額外擴大了權限。
- [ ] 記錄節點狀態、節點識別與配對請求，確認配對流程沒有待處理項目。
- [ ] 核對節點描述與可用命令，確認
system.run可用，而非只確認節點在線。 - [ ] 查閱 Gateway 策略與相關記錄，確認實際命令識別沒有被拒絕。
- [ ] 對照節點本機審批及允許清單，保留必要的人工確認，不改成不受限制執行。
- [ ] 確認 Agent
exec指向預期節點，並用帳戶與工作目錄查詢命令核對執行位置。 - [ ] 在目標 Mac 查詢活動 Xcode 工具鏈，執行實際專案的最小建置並留存結果。
- [ ] 以修復前失敗的原始任務復測，記錄仍保留的限制、人工審批需求與回退方式。
若同一條查詢命令已能在指定節點回傳預期帳戶與工作目錄，但 Xcode 建置仍失敗，問題便更可能落在工具鏈、專案路徑或建置設定，而不是節點連線或命令授權。反過來說，若命令未到達目標節點，應回到節點目標、Gateway 政策或本機審批層，依新出現的證據繼續排查。
長期依賴 Linux 工作站或本機電腦，可能遇到沒有 macOS 專屬工具鏈、工作站關機後任務中斷，以及不同操作者環境不一致等限制；自購 Mac 則需要承擔硬體採購與維護。若團隊已確認需要可持續存取的 macOS 執行節點，遠端 Mac 可作為另一種方案，但不適合所有工作：需要實體介面或長期固定重負載的情況，仍應評估自有設備。可先閱讀 NUKCLOUD 的遠端 Mac 使用與連線說明，再查看 NUKCLOUD 的服務資訊，依實際工作流程確認接入與命令驗收方式是否符合需求。