Appearance
配置 Codex Cloud 环境，决定 AI Agent 在云端任务里能调用哪些工具、访问哪些依赖。通过 Setup 脚本安装依赖和工具，环境变量在整个任务期间可用，而 Secrets 只在 Setup 阶段可用（Agent 执行前自动移除）。容器缓存最长 12 小时，大幅提速重复任务。
Codex Cloud 环境配置
云端环境决定 Codex 在执行任务时拥有什么工具、什么依赖、什么权限。在 Codex Settings - Environments 里配置。
任务执行流程
提交任务后，Codex 按以下步骤运行：
1. 创建容器，checkout 指定分支/commit
2. 运行 Setup 脚本（有网络访问）
3. （如果是缓存恢复）运行 Maintenance 脚本（可选）
4. 应用网络访问设置（Agent 阶段默认关闭网络）
5. Agent 循环执行：编辑代码 → 运行检查 → 验证工作
6. 完成后展示 diff，可开 PR 或继续追问如果仓库里有 AGENTS.md，Agent 会从里面读取项目专属的 lint 和测试命令。
默认容器镜像
Codex 使用 universal 镜像，预装了常见语言和工具（Python、Node.js 等）。
在 Environment Settings 里点击 Set package versions 可以固定 Python、Node.js 等版本。
参考 Dockerfile：openai/codex-universal（可以本地拉取测试环境行为）
环境变量与 Secrets
环境变量
整个任务生命周期都可用（包括 Setup 和 Agent 阶段）。适合：API 端点配置、构建参数、Feature Flag 等。
Secrets
有额外加密层，只在 Setup 阶段可用，Agent 执行前自动移除。适合：私钥、数据库密码等敏感凭证——确保 Agent 在执行代码时无法访问这些值。
Setup 脚本
自动检测（简单项目）
对于使用 npm、yarn、pnpm、pip、pipenv、poetry 的项目，Codex 会自动安装依赖，无需手动写 Setup 脚本。
手动 Setup 脚本
复杂项目可以提供自定义 bash 脚本：
bash
# 安装额外工具
pip install pyright
# 安装全量依赖（含测试）
poetry install --with test
pnpm install注意：Setup 脚本在独立的 Bash session 里运行，
export的环境变量不会传递到 Agent 阶段。需要持久化的变量要：
- 写入
~/.bashrc- 或者在 Environment Settings 里配置环境变量
Maintenance 脚本（可选）
在缓存容器被恢复时运行（Setup 脚本已经跑过，但 commit 可能更新了），适合增量安装新依赖：
bash
# 仅重新安装（比完整 Setup 更快）
pnpm install --frozen-lockfile容器缓存
Codex 缓存容器状态，最长 12 小时，大幅减少重复安装时间。
缓存命中时的流程
- Checkout 任务指定的分支
- 运行 Maintenance 脚本（可选）
- 直接进入 Agent 阶段
何时自动失效
- 修改了 Setup 脚本
- 修改了 Maintenance 脚本
- 修改了环境变量
- 修改了 Secrets
手动失效：在 Environment 页面点击 Reset cache
Enterprise 注意：Business/Enterprise 用户的缓存在工作区内共享。重置缓存影响所有有访问权限的用户。
网络访问
| 阶段 | 网络访问 |
|---|---|
| Setup 脚本 | 有（用于安装依赖） |
| Agent 执行 | 默认关闭（可在 Settings 里开启） |
所有对外流量通过 HTTP/HTTPS 代理（安全和滥用防护目的）。
开启 Agent 阶段网络访问参考：网络访问控制
最佳实践
- 用 Setup 脚本而不是 AGENTS.md 安装依赖：AGENTS.md 里的内容每次任务都会传给 Agent，有 token 开销；Setup 脚本只在环境初始化时运行一次
- 固定依赖版本：在 Setup 脚本里用
--frozen-lockfile或pip install -r requirements.txt，保证可重现 - Secrets 而不是环境变量存凭证：即使你相信 Agent 行为，Secrets 也提供额外一层保护
- 善用 Maintenance 脚本：在缓存命中场景里增量更新，比完整重跑 Setup 快得多
常见问题
Q: Setup 脚本里设置的环境变量为什么 Agent 阶段用不了？
A: Setup 脚本在独立的 Bash session 里运行，export 不会跨 session 传递。解决方法：在 Environment Settings 里直接配置环境变量，或者在 Setup 脚本里把值写入 ~/.bashrc。
Q: 容器缓存对开发流程有什么影响？
A: 缓存最长 12 小时。如果你在这段时间里频繁提交任务，第二次起几乎不需要等待 Setup。Maintenance 脚本让你可以在命中缓存时只增量更新，进一步提速。
Q: codex-universal 镜像里没有我需要的工具怎么办？
A: 在 Setup 脚本里安装——镜像只是起点，你可以用 apt/pip/npm 等安装任何东西（Setup 阶段有完整网络访问）。