配置云端运行环境

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、验证输出和未验证项。