---
title: "云端与远程环境"
description: "基于官方 Codex 教程，帮新手分清 Cloud、联网权限和远程开发环境各自解决什么问题。"
verifiedAt: "2026-05-07"
---

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

这一组不是在讲“怎么让 Codex 变强”，而是在讲 Codex 到底在哪里运行、能不能联网、能不能碰你的真实开发环境。

> [!IMPORTANT]
> 运行环境决定 Codex 能看到什么；联网权限决定它能访问什么外部站点；远程开发决定命令在哪台机器上执行。

<Cards>
  <Card title="Cloud runtime" href="/docs/codex/official/05-cloud-remote/18-cloud-runtime">
    配置云端依赖、环境变量、secrets、cache 和 setup script。
  </Card>
  <Card title="Network permissions" href="/docs/codex/official/05-cloud-remote/19-network-permissions">
    控制 setup 阶段和 agent 阶段能访问哪些外部网络。
  </Card>
  <Card title="Remote development" href="/docs/codex/official/05-cloud-remote/70-remote-dev">
    把本地交互体验连接到远程开发机。
  </Card>
</Cards>

## 三种问题

```mermaid
flowchart LR
    Task["Codex task"] --> Runtime["where it runs"]
    Task --> Network["what it can access"]
    Task --> Remote["where commands execute"]
```

想让 Codex 在云端隔离环境里做长任务，看 Cloud runtime。你要关心依赖安装、仓库准备、环境变量和任务能否复现。

想控制 Codex 能不能访问外网，看 Network permissions。你要关心 setup 阶段和 agent 阶段的域名白名单，不要为了省事直接全放开。

想在远程开发机上使用本地交互体验，看 Remote development。你要关心代码、凭据和命令到底在哪台机器上执行。

## 怎么选

刚开始学 Codex，先用本地 CLI 或 IDE。等你已经知道 Codex 会改哪些文件、会跑哪些命令，再进入云端或远程环境。

任务耗时长、依赖复杂、适合异步处理，用 Codex Cloud。它适合“交给 Codex 跑一段时间，稍后看结果”的任务。

任务需要访问公司内网、私有服务、本机密钥或特定机器环境，用远程开发机。重点不是“云”，而是执行环境和权限边界。

任务需要下载依赖、查官方文档或访问 API，单独配置联网权限。联网不是默认越大越好，应该按任务需要逐步放开。

## 三者边界表

| 能力 | 解决的问题 | 默认风险 |
| --- | --- | --- |
| Cloud runtime | 在隔离容器里 clone repo、安装依赖、运行长任务并产出 diff | 环境不可复现、setup script 缺依赖、secrets 误用。 |
| Network permissions | 控制 agent 阶段是否能访问外部网络、哪些域名和 HTTP method 可用 | prompt injection、代码或 secrets 外泄、下载不可信依赖。 |
| Remote development | 通过 SSH 把 Codex app/本地体验连接到远程主机项目 | 远程账号权限过大、PATH 不一致、误把生产环境当开发环境。 |

官方 Cloud environments 文档里，云端任务的顺序是：创建 container、checkout repo、运行 setup script、应用 internet access 设置、agent 循环运行命令和编辑文件、最后展示 answer 和 diff。这个顺序决定了排障方法：先查 repo/branch，再查 setup，再查联网，再查 agent 阶段日志。

## 环境变量和 secrets 的区别

Cloud environments 里有两个容易混淆的配置：

- Environment variables：整个 task 期间可用，包括 setup scripts 和 agent phase。
- Secrets：加密存储，只在 setup scripts 中解密可用；出于安全原因，agent phase 开始前会移除。

如果某个 token 只用于安装私有依赖，应该放 secrets，而不是让 agent phase 长期持有。需要 agent 运行期间访问的变量才放 environment variables，并且要确认任务确实需要。

## 联网权限最小化

Agent phase 默认不联网。需要打开时先选最小权限：

1. 优先 off。
2. 必须下载或查资料时，选择 allowlist。
3. HTTP method 优先限制到 `GET`、`HEAD`、`OPTIONS`。
4. 只有非常明确的隔离任务才考虑 unrestricted。

不要把“setup 能联网”和“agent 能联网”混为一谈。setup 阶段联网是为了安装依赖；agent 阶段联网会让模型读到外部内容，也会引入 prompt injection 和数据外泄风险。

## 常见坑

- 以为 Cloud 就等于能联网。
- 以为远程开发只是换个终端。
- 把安装依赖和 agent 自主联网混在一起。
- 没有记录环境变量和 secrets。
- 直接开放所有域名。
- 任务失败时不知道查本地、Cloud 还是远程主机。

## 学习顺序

1. 读 Cloud runtime，理解云端任务为什么需要可复现环境。
2. 读 Network permissions，理解“让 Codex 联网”是在做权限设计。
3. 读 Remote development，理解代码和凭据在远程机器上时，执行边界在远程主机。

## 读完后应能回答

- 任务应该在本地、Cloud，还是远程开发机上跑？
- Codex 需要哪些依赖、环境变量和凭据？
- 哪些外部域名必须开放，哪些不该开放？
- 命令失败时该查本地机器、Cloud 环境，还是远程主机？
- 任务完成后，如何确认改动、日志和敏感信息没有越界？
- 如果 Cloud setup 成功但 agent 失败，下一步该查 agent phase 网络、权限还是仓库说明？
- 如果远程连接失败，是否已经在远端 login shell 下确认 `codex` 在 `PATH`？

## 配套阅读

- [App、IDE、CLI、Cloud 怎么选](/docs/codex/understanding/cli-app-ide-cloud)

## 官方资料

- [Codex Web environments](https://developers.openai.com/codex/cloud/environments)
- [Codex internet access](https://developers.openai.com/codex/cloud/internet-access)
- [Codex remote connections](https://developers.openai.com/codex/remote-connections)
