配置雲端執行環境

Cloud environments 用來控制 Codex 在執行 cloud tasks 時安裝什麼、執行什麼、能訪問哪些網路和 secrets。它決定雲端任務能否穩定復現本地開發環境。

Setup script 和 agent phase 不是同一個階段：setup 有網路，agent 預設無網路；secrets 只給 setup script，agent phase 前會被移除。

Cloud environments

官方 cloud environment 配置說明。

Internet access

單獨理解 setup、agent 和 proxy 的網路邊界。

Cloud overview

先判斷任務是否真的適合 Cloud。

Cloud task 流程

flowchart LR
    Start["submit task"] --> Checkout["checkout branch / SHA"]
    Checkout --> Setup["setup script"]
    Setup --> Network["internet settings"]
    Network --> Agent["agent loop"]
    Agent --> Diff["answer + diff"]

提交 cloud task 後，Codex 通常會：

建立 container，並 checkout 你選擇的 branch 或 commit SHA。
執行 setup script；恢復 cached container 時可執行 maintenance script。
應用 internet access settings。
Agent 進入迴圈，編輯程式碼、執行檢查、嘗試驗證。
結束後展示最終回答和被修改檔案的 diff。

如果 repo 裡有 AGENTS.md，agent 會用它找到專案專屬 lint 和 test commands。

Default universal image

Codex agent 預設執行在 universal container image 中，預裝常見 languages、packages 和 tools。

在 environment settings 裡，可以固定 Python、Node.js 和其他 runtimes 的版本。需要確認具體預裝內容時，看 openai/codex-universal 的 reference Dockerfile 和可本地測試映象。

預設映象是為了速度和便利。專案需要額外 packages 時，用 setup script 安裝。

Environment variables 和 secrets

Environment variables 在整個 task 生命週期內可用，包括 setup scripts 和 agent phase。

Secrets 類似 environment variables，但有兩個關鍵區別：

儲存時有額外 encryption。
只對 setup scripts 可用，agent phase 開始前會被移除。

這意味著：安裝私有依賴、拉私有包、下載內部資源，應該放在 setup script 階段完成。不要指望 agent 階段還能讀取 secrets。

自動和手動設定

常見 package managers 下，Codex 可以自動安裝 dependencies 和 tools：

npm
yarn
pnpm
pip
pipenv
poetry

複雜專案用 custom setup script：

# Install type checker
pip install pyright

# Install dependencies
poetry install --with test
pnpm install

setup scripts 和 agent 使用不同 Bash session。export 這類命令不會自動延續到 agent phase。需要持久環境變數時，寫入 ~/.bashrc 或在 environment settings 中配置。

Container caching

Codex 會快取 container state，用來加速新任務和 follow-ups。官方當前說明快取最長 12 小時；具體行為以 cloud environment 頁為準。

快取環境建立時：

clone repository。
checkout default branch。
執行 setup script。
快取生成後的 container state。

恢復 cached container 時：

checkout 本任務指定 branch。
可執行 maintenance script。

setup script、maintenance script、environment variables 或 secrets 改變時，cache 會自動失效。如果 repo 變化導致 cached state 不相容，在 environment page 手動 Reset cache。

Business 和 Enterprise 場景裡，cache 可能在有許可權訪問該 environment 的使用者之間共享。失效 cache 會影響 workspace 內其他使用者。

網路訪問

Setup script 階段可以訪問 internet，用來安裝 dependencies。

Agent phase 預設關閉 internet access。需要時可以配置 limited 或 unrestricted access。

Environments 會執行在 HTTP/HTTPS network proxy 後面。所有 outbound internet traffic 都經過這個 proxy。

不要把 agent 網路開啟當成預設。能在 setup 階段完成的下載、安裝、認證，就不要留給 agent 階段。

驗收清單

branch 或 commit SHA 明確。
setup script 能獨立重複執行。
secrets 只用於 setup 階段，沒有在 agent phase 依賴。
runtime 版本已固定或可解釋。
cache 失效和 Reset cache 策略清楚。
agent phase 網路訪問預設關閉，只有必要時開啟。
任務結束後有 diff、驗證輸出和未驗證項。