2026 OpenAI Codex CLI Mac 部署安全指南

截至 2026 年 7 月 29 日，OpenAI Codex CLI 官方最新發佈為 0.146.0。這個版本的發佈記錄提到，工作階段在中斷、重播及恢復流程中會保留部分訊息與批准設定，但這不等於你的長任務已經通過實際環境驗收。(官方 GitHub 發佈記錄)

症狀：為了解決一次測試報錯，你給 Codex CLI 開了整台 Mac 的檔案、網路與指令權限。
最快解法：先退回最小工作區、受限憑據與可回滾任務；敏感程式碼、無人值守或長時間執行，改用獨立帳號、備用 Mac 或隔離的雲端 Mac。

這篇文章適合三類人：
獨立開發者，想在個人 Mac 執行 Agent，又怕誤改檔案或讀到敏感設定。
研發團隊，準備把編碼 Agent 引入真實倉庫，需要統一權限與驗收標準。
環境管理員，需要交付可重設、可審查的 macOS 工作環境。

最後更新於 2026 年 8 月 2 日；部署方式、身份驗證、沙箱與設定項目已對照 OpenAI Codex CLI 官方文件、官方程式碼倉庫及最新發佈記錄核實。(OpenAI Codex CLI 官方倉庫)

先分清任務與設備

Codex CLI 在 macOS 上是本機執行的編碼 Agent。官方倉庫列出的安裝方式涵蓋獨立安裝器、npm、Homebrew 及 GitHub Release，也提供適用於 macOS 的執行檔。(官方安裝說明)

但「可以安裝」和「適合放在主力 Mac」是兩件事。部署前先看三個限制：

• 資料邊界：Agent 可能需要讀取程式碼、套件設定與測試輸出；如果工作區旁邊放着 .env、SSH 設定、憑證或個人筆記，錯誤的根目錄設定會擴大暴露範圍。
• 操作邊界：讀取、寫入、執行指令與連線網路不是同一種風險。一次批准安裝套件，可能同時引入外部下載、安裝腳本及額外檔案變更。
• 可用性邊界：主力 Mac 會被合蓋、重啟、睡眠或日常工作打斷。長任務若沒有獨立工作區和明確停止條件，恢復時很難分辨哪些修改已完成。

環境初判

• 低敏感度、短任務、你會即時查看差異：現有 Mac 可用。
• 個人設定與工作專案混在同一帳號：先建立獨立 macOS 使用者帳號。
• 敏感倉庫、多人試點或需要持續執行：使用備用 Mac 或可重設的雲端 Mac。
• 需要物理接口、離線工具或固定本地資料：不要先假設雲端環境適合，改用隔離的實體 Mac。

不要把整個 ~、文件夾或使用者目錄設成預設工作區。先複製一個不含密鑰的測試倉庫，讓 Agent 只處理該目錄。

官方安裝與身份校驗

安裝只採用官方來源。官方倉庫目前列出的 macOS 安裝方式包括：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

也可以使用：

npm install -g @openai/codex

或：

brew install --cask codex

安裝後先記錄來源、時間與版本：

which codex
codex --version

獨立安裝器會從 OpenAI 主機取得發佈檔，必要時才回退到官方 Release。你應保存安裝來源、執行檔位置和版本輸出，方便日後排查版本差異或回滾。

身份驗證分成兩條路徑：

codex login

這會走 ChatGPT 瀏覽器登入流程。另一條是 API 金鑰：

printenv OPENAI_API_KEY | codex login --with-api-key

官方文件將兩者分開說明：ChatGPT 登入受帳號、工作區權限與相關資料政策影響；API 金鑰則按 API 組織的憑據與資料設定處理。(OpenAI 官方身份驗證文件)

首次啟動後不要立即接入生產倉庫。先確認：

codex login status
echo "$CODEX_HOME"
pwd

若沒有設定 CODEX_HOME，預設位置是 ~/.codex。其中可能包含設定、身份驗證、記錄、工作階段與技能資料。需要隔離時，可先建立專用目錄：

mkdir -p "$HOME/codex-isolated"
export CODEX_HOME="$HOME/codex-isolated"

不要把 auth.json 複製到共享硬碟或提交到 Git。檔案式憑據含有存取權杖，應視同密碼處理；可考慮使用 macOS 的憑據儲存機制，並在試點結束後執行登出或撤銷。(Codex 設定與環境變數說明)

第一小時的沙箱基線

Codex 的沙箱和批准機制是兩層控制。沙箱決定技術邊界；批准策略決定何時必須停下來詢問。macOS 使用內建 Seatbelt 框架，受限指令與檔案操作會在限定環境中執行。(OpenAI Codex 安全與批准說明)

三個模式先這樣理解：

• read-only：可檢查檔案，但不能直接修改；執行指令通常需要批准。
• workspace-write：可讀取檔案、修改工作區內內容及執行一般本地指令；超出工作區或需要網路時再詢問。
• danger-full-access：移除檔案與網路邊界。官方明確將它列為高風險模式，不應用來解決一般權限錯誤。

第一小時建議使用：

codex --sandbox workspace-write --ask-for-approval on-request

若只做檢查：

codex --sandbox read-only --ask-for-approval on-request

測試倉庫要刻意放入幾個可觀察項目：

1. 一個普通程式碼檔案。
2. 一個預期不能修改的檔案。
3. 一個假密鑰，例如 example.env，但不可放入真實權杖。
4. 一個會觸發套件下載的測試指令。
5. 一個可快速回復的 Git 初始提交。

驗證時記錄四類證據：

• Agent 實際讀取了哪些目錄。
• 寫入是否只發生在授權工作區。
• 網路請求是否先出現批准。
• 被拒絕後是否清楚回報，而不是靜默繼續。

如果只是因為某個 Permission denied 就切到 danger-full-access，先停下來。錯誤可能來自錯誤工作目錄、檔案擁有者、工具自身的路徑需求或設定檔位置，不代表整台 Mac 都應該開放。

首個真實任務的隔離方式

第一個真實任務不要選生產部署、資料庫遷移或大規模重構。選一個可以在數個回合內完成、容易回滾、結果能人工檢查的小修正。

建議流程：

1. 建立專用分支或複本。
2. 先保存乾淨的 Git 狀態。
3. 移除 .env、憑證、個人設定與不必要的測試資料。
4. 啟動 workspace-write，保留 on-request 批准。
5. 讓 Agent 只處理一個明確問題。
6. 用 git diff、測試結果與檔案時間戳檢查變更。
7. 確認沒有工作區外寫入，再決定是否合併。

API 金鑰不要寫進提示詞、專案檔案或 Agent 可讀取的測試資料。若必須使用憑據，採用任務專用、權限最小、可撤銷的金鑰；任務完成後立即撤銷或更換。

網路依賴要分開記錄。套件安裝、外部工具、Git 遠端及測試服務，批准原因並不相同。不要因為批准一次套件下載，就把網路權限長期寫入全域設定。工作區可寫入範圍、網路存取與環境變數排除項，都應按工作流逐項配置，而不是使用一個大而全的預設設定。

長任務與恢復鏈路

短任務和無人值守任務要分開管理。互動式任務有人在終端機前，可以逐次批准；無人值守任務則需要獨立工作區、穩定連線、可撤銷憑據與停止條件。

先做四個故障演練：

• 暫時關閉終端機。
• 模擬網路短暫中斷。
• 讓 Mac 進入睡眠或合蓋。
• 在中途手動終止一個測試流程。

每次演練都記錄：

• 工作階段是否仍可找到。
• 工作樹是否留下未完成修改。
• 最後一個成功指令是否可識別。
• 重新啟動後是否會重複執行副作用指令。
• 是否能靠 Git 差異和執行記錄完成人工復核。

官方發佈記錄提到，更新後會改善中斷、重播及分支工作階段中的訊息和批准設定保存；這是版本行為說明，不是你本身環境的穩定性保證。你仍要在自己的 macOS、終端機、網路和工作區上重做測試。

如果主力 Mac 會被你頻繁使用、合蓋或重啟，長任務不要依賴人工守候。沒有備用設備時，可以評估 MacHTML 的雲端 Mac 方案 作為隔離試點；但仍要先確認工作區交付、重設方式、連線與資料清理流程。

Codex CLI 權限與長尾問題

Codex CLI 在 Mac 上的權限邊界

先使用 read-only 或 workspace-write，不要一開始啟用 danger-full-access。一般測試可讓它讀取指定工作區，必要時在工作區內寫入；網路、工作區外檔案與高風險指令則保留人工批准。只有在已隔離的設備或測試環境中，才考慮更高權限。

本地倉庫的授權範圍

Codex CLI 可以讀取指定工作區內的完整倉庫，但不代表應把整個使用者目錄或多個專案根目錄設為工作區。較穩妥的做法是建立專用複本，移除環境檔、憑證與個人設定，再以 workspace-write 限定可寫入路徑，完成差異檢查後才合併。

API 金鑰與設定檔隔離

可用獨立 macOS 使用者帳號，並為該帳號設定專用 CODEX_HOME。身份檔案、記錄和設定不要放入共享資料夾，也不要提交到版本庫。若團隊要交付環境，應在文件中記錄登入方式、撤銷方式和重設步驟，而不是只交付一個已登入的帳號。

長任務的設備選擇

短時間、需要你即時批准的任務可留在主力 Mac。若工作會持續執行、需要無人值守，或主力 Mac 會合蓋、重啟及被日常工作佔用，應改用獨立帳號、備用 Mac 或可重設的雲端 Mac，並先測試中斷後的恢復流程。

第一週驗收清單

以下清單不要只勾「已安裝」。每一項都要留下證據。

• [ ] 已記錄官方安裝來源、執行檔位置與目前版本。
• [ ] 已確認 codex login status 顯示正確身份。
• [ ] 已確認 CODEX_HOME 的位置與權限。
• [ ] 已用不含密鑰的測試倉庫完成首次執行。
• [ ] 已驗證 read-only 不會直接寫入檔案。
• [ ] 已驗證 workspace-write 只可修改授權工作區。
• [ ] 已確認工作區外寫入會要求批准或被拒絕。
• [ ] 已確認網路依賴會留下批准理由。
• [ ] 已使用任務專用、可撤銷的憑據。
• [ ] 已完成一次錯誤寫入或權限越界演練。
• [ ] 已保存 Git 回滾指令與乾淨基線。
• [ ] 已完成終端機斷線、睡眠或網路波動測試。
• [ ] 已確認中斷後不會無意重複副作用指令。
• [ ] 已輸出安裝來源、設定基線、批准規則與交付記錄。

若權限越界、密鑰撤銷、任務恢復或結果複查其中一項沒有證據，就不要把環境交給團隊使用。

三種環境的取捨

權限模式的實際差異

方案成本與交付考量

MacHTML 的 方案與支援入口 可作為評估雲端 Mac 交付流程的起點；實際選擇前，仍應先核對你的工作區是否能安全搬移，以及任務是否需要本地硬體接口。

最終環境結論

如果你只是讓 Codex CLI 檢查低敏感度專案，主力 Mac 配合 read-only 或 workspace-write 已經足夠。若任務會接觸私人設定、企業程式碼、部署憑據或長時間執行，直接使用主力 Mac 的缺點很明顯：資料邊界混雜、日常操作會中斷任務，而且一旦開啟高權限，回滾責任仍落在你身上。

相較之下，隔離的 Mac 環境或雲端 Mac 能把工作區、身份、憑據與交付週期分開管理。它不會自動替你完成安全驗收，但更適合建立可重設、可審查的試點。你可以先保存這份 Mac 編碼 Agent 權限驗收方向，在非生產倉庫完成權限、回滾和中斷恢復測試；沒有備用設備，或需要持續在線環境時，再評估租用 MacHTML 的雲端 Mac。

常見問題