---
title: "配置雲端執行環境"
description: "Cloud environments 用來控制 Codex 在執行 cloud tasks 時安裝什麼、執行什麼、能訪問哪些網路和 secrets。"
verifiedAt: "2026-05-06"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

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

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

<Cards>
  <Card title="Cloud environments" href="https://developers.openai.com/codex/cloud/environments">
    官方 cloud environment 配置說明。
  </Card>
  <Card title="Internet access" href="/zh-Hant/docs/codex/official/05-cloud-remote/19-network-permissions">
    單獨理解 setup、agent 和 proxy 的網路邊界。
  </Card>
  <Card title="Cloud overview" href="/zh-Hant/docs/codex/official/05-cloud-remote">
    先判斷任務是否真的適合 Cloud。
  </Card>
</Cards>

## Cloud task 流程

```mermaid
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 通常會：

1. 建立 container，並 checkout 你選擇的 branch 或 commit SHA。
2. 執行 setup script；恢復 cached container 時可執行 maintenance script。
3. 應用 internet access settings。
4. Agent 進入迴圈，編輯程式碼、執行檢查、嘗試驗證。
5. 結束後展示最終回答和被修改檔案的 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：

```bash
# 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、驗證輸出和未驗證項。

## 官方資料

- [Cloud environments](https://developers.openai.com/codex/cloud/environments)
- [Agent internet access](https://developers.openai.com/codex/cloud/internet-access)
- [openai/codex-universal](https://github.com/openai/codex-universal)
