先確認 OpenCode 的工作區和終端工具實際位於哪台主機；SSH 能登入遠端 Mac，不代表 Agent 的檔案操作與指令已自動切換到遠端。若你用 Windows 或 Linux 開發，應先決定讓工作區直接位於遠端 Mac，或由 OpenCode 明確透過 SSH 呼叫遠端命令，再分別驗證檔案修改、xcodebuild 建置與測試結果。OpenCode 的版本資訊請以官方變更記錄為準。

本週建議：先用同一個提交識別本機與遠端專案，再執行最小建置和測試，逐段記錄執行主機及產物位置。

適合以 Windows 或 Linux 為主力開發機、需要建置 iOS/macOS 專案的工程師。
維護遠端 Mac CI 的 DevOps 工程師，可用本文釐清 Agent 工作區與建置節點的責任邊界。
正在接入 Apple 工具鏈的技術負責人，可用本文規劃權限範圍與驗收證據。

最後更新於 2026-10-24；版本與指令說明核對自 OpenCode 官方文件及 Apple 的 Xcode 命令列工具文件。

01

OpenCode 的 Bash 指令在哪裡執行？

OpenCode 的 Bash 工具會在專案執行環境中執行；SSH 連線成功，只能證明你可以登入遠端主機，不能證明 Agent 的工具呼叫會經過 SSH 轉送。先確認 OpenCode 程式、目前工作目錄和實際執行命令的主機，再判斷 Xcode 是否可用。這是OpenCode 工具文件描述的執行邊界，不應靠「SSH 已連上」推定。

排查時，在 OpenCode 終端工具執行環境和 SSH 登入的遠端 Shell 各自檢查主機名稱、目前目錄及專案狀態。兩邊結果不同，就代表你正在比較兩個執行環境，而不是同一個遠端工作階段。

讓 OpenCode 使用遠端 Mac 的專案目錄

有兩種常見安排：把 OpenCode 工作區和終端執行環境都放在遠端 Mac；或保留本機 Agent，但明確透過 SSH 在遠端執行建置命令。不要只在本機 Shell 登入遠端，再把這條連線當成 Agent 已切換環境。

執行安排 檔案修改位置 Xcode 命令位置 主要風險 適合情況
OpenCode 與工作區都在遠端 Mac 遠端專案副本 遠端 Mac 需確認遠端帳戶及工作區權限 開發與建置都需依賴 macOS
OpenCode 在本機，透過 SSH 呼叫遠端 可能是本機副本；需明確同步或指向遠端 只有透過 SSH 呼叫的命令在遠端 Agent 編輯的檔案與建置的檔案可能不是同一份 已有清楚的遠端命令調度流程
OpenCode 與工作區都在本機 本機專案副本 本機環境 遠端 SSH 不會補上本機缺少的 Xcode 工具鏈 不需要在遠端建置

如果專案由遠端 Mac 建置，建議讓工作區也落在遠端，減少雙份專案不同步的可能。若架構要求保留本機 Agent，就要把檔案同步、遠端命令和產物回收設計成明確步驟，不能把它們視為同一項操作。

02

專案副本錯位時，先核對工作目錄與提交

OpenCode 能讀寫專案，不等於它讀寫的是遠端 Mac 上供建置使用的那份專案。工作目錄不同、Git 倉庫位置不同，或本機尚有未提交修改，都可能令 Agent 改了檔案，遠端卻仍在建置另一個版本。

用以下流程確認讀寫對象：

  1. 在 OpenCode 執行環境記錄目前目錄，確認它是否位於預期倉庫。
  2. 在本機和遠端分別檢查 Git 根目錄、分支與提交識別資訊。
  3. 挑選一個預期由 Agent 修改的檔案，比對修改內容及 Git 變更記錄。
  4. 確認 xcodebuild 使用的專案或工作區路徑，與已核對的倉庫位置一致。
  5. 以同一提交在預期主機重新執行建置，保存完整命令與退出狀態。

範例中的主機、帳戶和路徑請替換為你的環境：

ssh <REMOTE_USER>@<REMOTE_HOST> 'cd <REMOTE_PROJECT_PATH> && pwd && git rev-parse HEAD && git status --short'

此命令只檢查 SSH 指定的遠端 Shell；它不會改變 OpenCode 自身工作目錄。你仍要在 OpenCode 的終端工具中確認它看到的目錄與提交。若兩者不同，先修正工作區或同步方式，再繼續排查工具鏈，否則後續建置結果無法代表 Agent 修改過的專案。

03

遠端找不到 xcodebuild：核對活動工具鏈

本機找得到 xcodebuild，不能證明遠端 Mac 上也有該命令。Apple 說明，Xcode 命令列工具包含 xcodebuild；因此要在實際執行建置的遠端帳戶下確認工具是否可用，並核對活動開發者目錄是否指向預期安裝。Apple 的安裝文件與命令列工具參考可用來確認命令用途及工具鏈設定。

在遠端執行環境檢查：

command -v xcodebuild
xcodebuild -version
xcode-select -p

若命令不存在，或活動目錄不是預期的 Xcode 安裝位置，先處理遠端工具鏈安裝或選取問題。若命令可用但版本資訊與專案要求不符，記錄實際版本後再判斷是否需要切換。不要只查看登入帳戶的設定：Agent、SSH 工作階段與 CI 服務帳戶可能使用不同的 Shell 設定、環境變數或權限。

注意：只要錯誤訊息來自遠端命令，就以遠端執行帳戶的輸出為準。本機的 PATH、Xcode 安裝狀態和模擬器清單都不能代替遠端證據。

04

依錯誤位置選擇修復方向

建置失敗不一定是 OpenCode 工具呼叫問題。先按觀察到的現象分類，再處理最接近錯誤來源的一層。

  • SSH 可登入，但工具找不到 xcodebuild：檢查遠端安裝、活動開發者目錄及執行帳戶的 PATH。
  • 命令有執行，檔案卻沒改到預期位置：核對工作目錄、倉庫副本與提交，不要先重裝 Xcode。
  • 專案可讀，但私有依賴無法取得：區分倉庫讀取權、套件或依賴憑據，以及 Agent 編輯檔案的權限。
  • 建置失敗並提到簽署：確認簽名材料在實際建置帳戶下可用，避免為了排查而擴大整個帳戶的存取權。
  • 建置成功，測試目標不可用：檢查 scheme、destination 與所需 Simulator 執行環境是否相符。Apple 的模擬器與實體裝置執行文件可協助核對目標設定。

OpenCode 的工具授權也要獨立檢查。檔案修改權限不會自動授予私有依賴憑據或簽名材料的存取權；應先依日誌找出缺少的能力，再按最小必要範圍調整OpenCode 權限設定。不要用放寬整個專案或帳戶權限的方式掩蓋執行環境錯位。

若你的 macOS CI 需要穩定的 Apple 工具鏈節點，可先看VpsMesh 的 Mac mini 雲端方案說明，再確認工作負載、權限模型與接入方式是否符合需要；服務方案不能取代對專案及測試產物的驗收。

05

建置通過後，仍要驗證 Simulator 與測試結果

xcodebuild 建置成功，只代表該次建置命令通過，不等於測試已啟動，更不等於結果包已保存。Apple 的測試文件說明，Xcode 測試結果可透過結果包檢視；執行時應為結果包指定可辨識的位置，並在任務完成後確認檔案確實存在。Apple 測試執行與結果解讀文件提供結果檢視說明。

先確認 scheme 與 destination 對應測試目標，再在遠端檢查可用的 Simulator 裝置。若裝置清單沒有目標，應判斷所需執行環境是否存在、目的地設定是否正確，而不是直接認定 Agent 沒有執行命令。Apple 亦將模擬器和實體裝置列為不同的執行目標，不能把其中一種的可用性推定為另一種已就緒。

可將實際參數與路徑替換到以下命令範例：

xcodebuild \
  -scheme <SCHEME> \
  -destination '<DESTINATION>' \
  -resultBundlePath <RESULT_BUNDLE_PATH> \
  test

執行後一併留存命令、退出狀態、建置日誌及結果包路徑。之後在遠端確認結果包存在，並透過 Xcode 開啟檢視測試紀錄。若工作流程有產物收集步驟，也要確認它收集的是同一遠端路徑，而非本機上同名但內容過期的檔案。

06

用可複核證據決定修復、重跑或調整架構

把排查結果整理成以下驗收記錄，能避免「命令似乎跑過」被誤當成測試完成：

  • 執行位置：記下 OpenCode 工作區所在主機，以及 xcodebuild 實際執行所在主機。
  • 專案識別：記錄倉庫位置、提交識別資訊及 Agent 修改的檔案。
  • 工具鏈：保存遠端 xcodebuild 版本資訊與活動開發者目錄。
  • 測試目標：記錄 scheme、destination，以及遠端可用的對應執行環境。
  • 測試證據：保存退出狀態、完整日誌、結果包路徑及產物收集狀態。

用同一提交再跑一次，並比較修改內容、退出狀態和結果包。若遠端工具鏈正常、專案識別一致，且結果包可開啟，就可以把問題縮小到原先失敗的任務設定或測試目標；若工作區與建置節點長期分離、檔案同步和憑據交接反覆出錯，則應重新設計執行架構，而非只增加重試。

對照自身 macOS CI 的方案時，本機 Windows/Linux 缺少 Apple 工具鏈、SSH 只解決登入而不負責工作區同步、分散的憑據與產物也提高驗收難度。若問題確認來自主力機無法提供 macOS 執行環境，可先評估VpsMesh Mac mini 租用方案，再按專案所需工具鏈與存取方式判斷是否合適。需要臨時建置或獨立測試環境時，租用遠端 Mac 可作為自購設備之外的選項；若你需要長期固定負載或必須直接使用本地實體介面，則應先比較自建節點與本機 Mac 的管理需求。