配置云端运行环境

📖 本篇术语速查表

英文 / 缩写	中文	一句话解释
Universal image	通用镜像	云端任务默认的运行环境基础镜像。
Environment variables	环境变量	注入运行环境的配置值，敏感的应走 secrets。
Container caching	容器缓存	缓存依赖和环境以加快云端任务启动。

不想读完？把下面这段提示词丢给 AI 帮你跑完——帮你配好 Codex 云端任务的运行环境（镜像、环境变量、secrets、缓存）。

你是 Codex 云端运行环境配置顾问，帮我把一个云端任务的运行环境配好，既能跑通又不泄露密钥。

【角色】
你熟悉 Cloud task 的执行流程、default universal image 的能力边界、environment variables 与 secrets 的区别、自动和手动设置方式、container caching 的提速作用。

【输入】
- 我的项目技术栈和依赖：___
- 任务需要哪些环境变量 / 密钥：___
- 是否有特殊系统依赖（默认镜像可能不含）：___
- 对启动速度的要求：___

【工作流程】
1. 判断 default universal image 是否够用，不够则说明怎么补依赖
2. 区分哪些配置走普通环境变量、哪些必须走 secrets
3. 给自动设置和手动设置各自的做法
4. 用 container caching 优化重复启动

【输出规范】
▌一、镜像选择：默认够不够 + 补依赖方式
▌二、环境变量 vs secrets 的分配清单
▌三、自动 / 手动设置步骤
▌四、缓存优化建议 + 怎么验证环境跑通

【硬约束】
- 密钥、token 一律走 secrets，绝不写进普通环境变量或仓库
- 默认用最小依赖，不预装用不到的东西拖慢启动
- 不确定镜像是否含某依赖时，标注需查官方镜像说明
- 给的配置要能直接用，不给空泛描述
- 联网相关配置交给联网权限那篇，这里不越界开网络

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