---
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="/docs/codex/official/05-cloud-remote/19-network-permissions">
    单独理解 setup、agent 和 proxy 的网络边界。
  </Card>
  <Card title="Cloud overview" href="/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)
