Codex CLI 遠端 Mac CI 怎麼配置？2026 實戰指南

先分清楚三件事：Codex CLI 接收並執行 Agent 任務；遠端 Mac 上的 Xcode 工具鏈負責建置與測試；GitHub Actions 則排程工作流程並交付記錄。三者可以接在同一條流水線裡，但一個環節成功，不代表其他環節也已通過。

codex exec 是 Codex CLI 的非互動式執行方式，適合由腳本或 CI 傳入任務，不需像互動式工作階段一樣由人員逐步操作。它能看到哪些檔案、可執行哪些工具，取決於任務所在的 Mac、工作目錄及授予的權限；官方用法與選項應以 Codex 非互動模式文件及命令參考為準。

遠端 Mac 上常同時存在手動測試用副本、CI checkout 目錄和暫存工作區。若只確認「Codex 有回覆」，卻沒有核對執行目錄與提交，可能會把另一份副本的修改誤認為 CI 產物。開始設定前，先確定工作流程 checkout 的來源與觸發事件，再將 Agent 和 Xcode 步驟指向同一份專案副本。

逐項核對以下資料，缺少任一必要項目時先不要讓任務接觸憑據：

• [ ] 記錄工作流程觸發來源及其信任狀態，例如內部分支或外部 PR。
• [ ] 確認 checkout 的儲存庫、分支或提交識別，以及遠端 Mac 上的專案路徑。
• [ ] 確定 Agent 任務輸入、允許修改的檔案範圍及預期輸出。
• [ ] 列出建置和測試所需的 Xcode、命令列工具及其他依賴，並按 Apple 的 Xcode 系統需求核對 macOS 與工具鏈相容性。
• [ ] 確認日誌、測試結果與產物存放位置，以及哪些步驟可以讀取 Secret。

如果要由 GitHub Actions 呼叫自託管 Mac Runner，工作流程可透過 runs-on 指定 Runner 標籤；實際標籤須與節點設定一致，使用方式參照 GitHub 自託管 Runner 工作流程文件。這個標籤只用於選擇 Runner，不等於安全隔離或權限控管。

在遠端 Mac CI 中，先把任務分成唯讀分析與工作區修改，再選取相符的沙箱策略。Codex CLI 的非互動模式及命令列選項依前文所列官方文件設定；不要因為工作流程必須無人值守，就直接取消審批或放寬沙箱。

命令可按實際安裝版本及官方文件調整，以下使用佔位任務與路徑：

cd "<PROJECT_WORKSPACE>"
codex exec --sandbox read-only "檢查專案結構並列出建置前置條件，不修改檔案"

受控修改時，將沙箱改為工作區寫入，並按團隊政策保留審批；執行前再次核對當前目錄和提交。不同版本的旗標支援與行為以先前引用的命令參考為準，不要把高權限執行或停用審批當成無人值守 CI 的通用解法。

首次接入不要直接用發布分支和簽署憑據做端到端測試。先在可信任的測試分支上跑唯讀任務，再以刻意限定的修改任務確認寫入邊界。以下是團隊驗證建議，不是 Codex 官方保證的隔離機制。

pwd
git rev-parse HEAD
git status --short
codex exec --sandbox read-only "檢視指定模組，提出檢查結果，不修改檔案"
printf 'codex exit=%s\n' "$?"
git status --short

將輸出記錄到 CI 日誌時，確保任務退出狀態沒有被後續命令覆蓋；在正式腳本中應明確保存 Codex 命令的退出碼，再繼續執行診斷或上傳作業。受控修改試跑後，對照前後差異，確認沒有觸及工作區外檔案，且 Agent 執行位置、提交識別與工作流程記錄一致。

常見部署問題

獨立 FAQ 放在這裡，先釐清執行方式與權限，再進入建置驗收。

• GitHub Actions macOS CI 是否能執行 Codex CLI？ 可以由 macOS 工作流程呼叫 codex exec，但 Runner 必須能提供所需的 macOS 工具與專案目錄。將 Agent 命令放在明確的工作目錄中，並以可信任分支先測試；自託管標籤只負責選節點，不會自動限制 Secret、檔案或網路存取。
• 如何指定遠端 Mac 工作區與執行權限？ 由工作流程明確設定專案路徑，再依任務選擇唯讀或工作區寫入沙箱。先執行不修改檔案的任務，記錄實際路徑與提交；需要修改時再驗證差異範圍。具體 CLI 旗標需依目前安裝版本核對官方參考文件。
• Agent 修改程式後，Xcode 結果如何驗收？ 另行執行專案既定的 Xcode 建置或測試工作，不能把 Agent 摘要當成通過證明。保存命令與退出狀態、測試記錄及產物位置，並將它們對應至同一提交；只有工作流程的獨立驗收步驟成功，才能判定 Apple 工具鏈驗證完成。
• 如何避免任務碰到不必要的憑據或網路資源？ 將 Secret 限定在確實需要它的工作流程步驟，不要把部署或簽署憑據交給一般 Agent 任務。對外部 PR 採用隔離節點及受限權限，並按工作需要限制網路可達性；清除工作目錄或要求人工審批，均不能單獨取代 Runner 隔離。

Codex CLI 完成修改後，CI 必須另行執行專案既定的 Xcode 建置或測試命令。這才是遠端 Mac Xcode 建置是否成功的依據；Agent 對程式碼的說明、摘要或建議，不能代替 Xcode 工具鏈的退出狀態及測試結果。

cd "<PROJECT_WORKSPACE>"
xcodebuild <PROJECT_SPECIFIC_BUILD_OR_TEST_ARGUMENTS>

以上參數是佔位符，應由專案維護者依實際 scheme、destination 和測試方式填入，不能直接當成通用建置命令。記錄提交識別、Xcode 與 macOS 版本、實際執行的命令、退出狀態、測試結果及產物位置；發佈或變更工具鏈前，另按 Apple 的 Xcode 系統需求及 Xcode 27 發行說明核對相容性與版本差異。

若專案使用簽署或發佈憑據，應將簽署步驟與一般 Agent 修改分開授權，並在工作流程中明確記錄憑據由哪一個步驟使用。這樣即使 Agent 任務成功，也不會被誤讀成已完成簽署、測試或交付驗收。

GitHub 的安全文件提醒，自託管 Runner 可能保留環境與本機存取風險；工作目錄清理不能證明 Runner 已隔離，審批機制也不能取代憑據最小化與節點存取控制。尤其外部 PR 的程式碼不應在持有部署金鑰、簽署資料或其他長期憑據的持久 Mac 上執行。可參照前文 GitHub 安全使用建議，以及安全使用 pull_request_target 的說明，為不同信任來源設定獨立流程。

可按以下條件決定是否擴大使用：

• 試跑：任務來自可信任分支，使用受限工作區與最小必要權限，建置、測試及日誌均可獨立核對。
• 限制使用：Runner 需要長期在線，但任務來源混合；先分離可信任工作流程與外部 PR，並限制 Secret、網路及可存取資源。
• 暫緩上線：無法確認工作流程的程式碼來源、Runner 權限或憑據用途，或無法把 Agent 修改對應到獨立的 Xcode 驗收結果。

實際選擇節點時，也要比較自購 Mac、共用自託管主機與按需遠端 Mac：自購設備需要自行承擔硬體投入及維護；共用主機若信任邊界不清，會增加工作流程與憑據管理風險；遠端 Mac 則仍須按團隊需求核對存取方式、環境控制及節點交付條件。若需要短期建立獨立 macOS CI 環境，可先查看 NUKCLOUD 遠端 Mac 服務資訊及使用說明，再依工作週期評估是否需要獨立節點；若已確定持續執行 Codex CLI 與 Xcode 任務，可進一步查看遠端 Mac 方案。