Codex App 顯示已連上遠端 Mac，但 iOS 建置仍然失敗，或找不到專案。 最快解法：先分開檢查 SSH、專案目錄和 Xcode 建置；修好最早失敗的一層，再驗收模擬器、簽名與上傳。
適合使用 Windows 或 Linux 開發、想透過 Codex App 調度遠端 Mac 的獨立開發者。 若你的小型團隊正排查目錄或命令執行問題，或評估遠端 Mac 能否承接 Xcode 工作，也可依下列證據逐層定位。
最後更新於 2026 年 10 月 7 日；核對依據為Codex App 的 SSH 公開說明及 Apple 的命令列工具文件和Xcode 系統需求。Codex App 的功能狀態與操作入口可能隨版本變動，請以當下官方說明為準。
先定位 Codex App SSH 遠端 Mac 建置失敗的層級
不要只記錄「遠端建置失敗」。先找出第一個不能通過的關卡，再選相應的檢查方式。
| 觀察到的結果 | 優先故障層 | 下一步 |
|---|---|---|
| Codex App 未能辨識或建立遠端連線 | App 功能狀態或連線設定 | 核對目前版本的官方說明，再以獨立 SSH 用戶端測試 |
| 獨立 SSH 用戶端也無法登入 | 網路、帳戶、金鑰或伺服器端權限 | 查看 SSH 錯誤訊息，檢查主機可達性與授權 |
| 可登入，但專案不存在或無法儲存 | 工作目錄、倉庫副本或檔案權限 | 核對實際路徑、登入帳戶及版本控制狀態 |
| 專案可讀寫，建置命令仍失敗 | Xcode 開發者目錄、工具鏈或專案設定 | 查詢目前選用的 Xcode，再查看建置錯誤 |
| 命令列建置成功，但測試或交付失敗 | 模擬器、裝置、簽名或上傳 | 按實際交付目標另做驗收 |
從 SSH 認證確認遠端登入
先在 Codex App 之外，用獨立 SSH 用戶端測試相同主機與登入帳戶。主機位址、帳戶及金鑰路徑都應從你自己的設定取得，分享記錄前先遮蔽：
ssh -v <使用者>@<主機>若這裡也無法登入，檢查網路是否能到達主機、帳戶是否正確、用戶端是否選到預期金鑰，以及伺服器端是否允許該帳戶登入。若獨立測試成功、Codex App 卻失敗，再比對 App 使用的連線設定與登入身分是否一致；不要把兩者的連線成功與失敗混為一談。
不要為了讓連線先通就停用主機身分驗證，也不要擴大登入權限。這類作法會模糊真正原因，還可能讓後續連線落在未預期的主機或帳戶。
確認專案目錄與寫入位置
SSH 成功只表示你能登入主機，不能證明 Codex App 正在操作正確的倉庫，也不能證明 Agent 有權讀寫專案。連線後，先在遠端執行以下檢查：
pwd
git rev-parse --show-toplevel
git status --short --branch
test -w .確認實際使用者、倉庫根目錄、分支，以及目錄是否可寫。若工作目錄不在預期位置，先修正 Codex App 執行任務時使用的專案路徑；若專案中看不到預期修改，檢查你是否登入了另一個帳戶，或開啟了另一份倉庫副本。
以版本控制狀態確認變更的落點，並核對修改是否已儲存到預期工作樹。若 git status 顯示的位置與你實際檢查的專案不符，先停止建置，找出兩者差異；否則即使命令成功，也可能驗收了錯誤副本。
分享錯誤輸出前，請遮蔽使用者名稱、主機位址、倉庫路徑、Bundle ID、Team ID、憑據和可能識別專案的日誌內容。
核對 Xcode 工具鏈與命令列能力
專案可讀寫而建置命令失敗時，先查目前選用的開發者目錄及 Xcode 版本：
xcode-select -p
xcodebuild -versionxcode-select -p 可協助確認目前指向的開發者目錄；xcodebuild -version 則顯示選用工具鏈的版本資訊。將結果與遠端 Mac 的 macOS 版本、專案需求及[官方 Xcode 系統需求](https://developer.apple.com/xcode/system-requirements)對照。若開發者目錄指向不符預期的版本，先修正選擇，再重試原本的建置命令。
| 檢查項目 | 可觀察證據 | 判斷與處理 |
|---|---|---|
| macOS 與 Xcode 相容性 | macOS 版本及 Xcode 系統需求對照 | 不符合該 Xcode 版本要求時，改用相容組合 |
| 開發者目錄 | xcode-select -p 的輸出 | 路徑不符預期時，先選回正確目錄 |
| 建置工具可用性 | xcodebuild -version 與實際命令錯誤 | 若工具不存在或版本不符，檢查安裝與選擇狀態 |
| 命令列工具安裝 | 命令列工具文件與目前安裝情況 | 不要把已安裝命令列工具，直接當成完整 Xcode 環境 |
將建置、測試與交付分開驗收
不要用一次 xcodebuild 成功推定整條 iOS 發布流程已可用。命令列建置、啟動模擬器、測試實體裝置、簽名、封存和上傳，各自有不同前置條件。
| 驗收目標 | 需要確認的條件 | 建置成功以外的檢查 |
|---|---|---|
| 命令列建置 | Xcode、開發者目錄、專案設定與相依性 | 以實際 Scheme 執行並檢查退出結果 |
| 模擬器測試 | 相容的 Xcode、可用的 Simulator Runtime 與執行環境 | 參照[Apple 模擬器與實體裝置執行說明](https://developer.apple.com/documentation/Xcode/running-your-app-on-simulated-or-physical-devices) |
| 實體裝置測試 | 可連接的目標裝置與適用的簽名設定 | 確認遠端工作階段能使用所需裝置與權限 |
| 封存及簽名 | 簽名身分、描述檔和團隊設定相符 | 依[Apple 的簽名憑證共享文件](https://developer.apple.com/documentation/Xcode/sharing-your-teams-signing-certificates)核對憑證管理方式 |
| 註冊裝置分發或上傳 | 交付目標、簽名權限及帳戶存取條件 | 分別依[註冊裝置分發說明](https://developer.apple.com/documentation/xcode/distributing-your-app-to-registered-devices)或[App Store Connect 上傳文件](https://developer.apple.com/help/app-store-connect/manage-builds/upload-builds/)驗收 |
若你已確定工作流程需要遠端 macOS，可以先按專案所需的工具與存取方式，參考 MACGPU 的遠端 Mac 方案評估環境是否合適；不要只因 SSH 登入成功，就假設模擬器或簽名流程也能使用。
依驗收結果選擇排查路徑
- 若獨立 SSH 測試也失敗，先修復網路、帳戶、金鑰或伺服器端登入條件；SSH 尚未通過前，不要改 Xcode。
- 若 SSH 正常、倉庫路徑或寫入檢查失敗，先確認 Codex App 使用的帳戶、工作目錄和專案副本；不要以重新安裝工具鏈代替路徑核對。
- 若專案可讀寫，但工具版本或開發者目錄不符，就按 Apple 官方系統需求修正 Xcode 環境；工具鏈符合後再重跑同一項建置。
- 若命令列建置成功、模擬器未啟動，就轉查 Runtime 與圖形執行環境；若目標是實體裝置，改做裝置測試，不要將建置成功視為模擬器可用。
- 若測試通過但封存或上傳失敗，轉查簽名、憑證權限及交付帳戶；不要回頭把 SSH 認證當成首要故障點。
FAQ：遠端建置排查
Codex App 要怎樣透過 SSH 連線到遠端 Mac？
先確認 Codex App 目前版本是否提供 SSH 遠端開發機功能，再核對主機位址、網路可達性、登入帳戶、私鑰選擇與伺服器端登入權限。用獨立 SSH 用戶端測試同一組連線條件；若獨立登入也失敗，先處理 SSH，不要改專案或 Xcode 設定。登入資訊及除錯記錄應先遮蔽再分享。
SSH 已登入，但 Codex App 找不到 iOS 專案時要查哪裡？
先在遠端主機確認實際登入帳戶、目前工作目錄和倉庫根目錄，再檢查 Codex App 執行任務時使用的專案副本是否相同。以 git status 查看檔案改動落在哪個工作樹，並確認目錄可讀寫；若 App 使用另一份檢出目錄，修正工作目錄後再執行任務，不要先重裝 Xcode。
遠端 Mac 可以建置 Xcode 專案，卻不能啟動模擬器嗎？
可以，命令列建置成功不代表模擬器執行環境已安裝或可用。先核對 Xcode 版本、macOS 相容性與所需 Simulator Runtime，再確認目前登入工作階段能否啟動圖形應用；若任務要求實體裝置測試，也要另外安排可連接的裝置，不能用一般建置結果代替驗收。
Codex App 遠端建置 iOS App 前要確認哪些簽名條件？
先依交付目標確認簽名身分、Provisioning Profile、Bundle ID、Team ID 與憑據存取權限是否一致，並以遮蔽後的資訊核對專案設定。只做不需簽名的建置，與安裝到裝置、封存或上傳，所需條件不同；不要把憑據寫入程式碼或貼到未遮蔽的日誌中。
若 SSH 與專案檢查都已通過，但 Windows／Linux 工作機仍無法原生執行 Xcode，而自備 Mac 又受限於磁碟、常駐時間或共享維護，這些方案便不一定適合持續承接遠端建置。你可再比較 MACGPU 的方案與可選主機，按自己的專案驗收命令列建置、測試與簽名邊界；若需要可持續使用的 Mac 環境，再評估租用是否比添購專用主機更合適。