---
title: "管理 Agent 联网权限"
description: "基于 OpenAI 官方 Agent internet access 文档，学习新手什么时候该给 Codex 联网权限，以及如何降低风险。"
verifiedAt: "2026-05-06"
---

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

Codex 默认会限制 agent 阶段的网络访问。官方这样设计，是为了降低 prompt injection、代码或密钥外传、恶意依赖下载、许可证污染等风险。

新手要先记住一句话：联网权限不是“越开越方便”，而是“任务确实需要时才开，且只开到刚好够用”。

> [!IMPORTANT]
> 依赖安装失败不等于要给 agent 阶段开全网。先区分 setup 阶段、agent 阶段和本地 sandbox，再按日志只放开任务必需的域名和方法。

---

## 先理解两个阶段

在 Codex cloud 里，环境通常有两个阶段：

- setup 阶段：可以联网安装依赖。
- agent 阶段：默认不联网，除非你给环境开启 agent internet access。

这能解决一个常见矛盾：项目构建需要下载依赖，但 agent 实际改代码时不一定需要访问互联网。把两个阶段分开，新手更容易控制风险。

在 Codex app、CLI、IDE extension 里，默认 `workspace-write` sandbox 也会关闭命令的网络访问。需要时可以在配置里显式开启，但不要把它当作默认设置。
---

## 什么时候应该开

可以考虑开启：

- 任务必须读取外部 issue、API 文档或远程资源。
- 测试需要访问明确的内网或测试环境。
- cloud agent 阶段确实需要拉取 setup 后才知道的资源。

不建议开启：

- 只是让 Codex 阅读本地项目。
- 只是修本地测试失败。
- 只是需要安装依赖，setup 阶段已经能完成。
- 你要处理包含密钥、客户数据或未公开代码的仓库。
---

## 新手应该怎么开

优先按环境单独设置，不要做全局放开。官方文档里，Codex cloud 支持 domain allowlist 和 allowed HTTP methods。

推荐顺序：

1. 先保持 Off，看任务是否真的失败。
2. 如果只是依赖下载，优先放在 setup 阶段解决。
3. 如果 agent 阶段必须联网，从空 allowlist 或 Common dependencies 开始。
4. 只加任务需要的域名。
5. HTTP methods 优先限制在 `GET`、`HEAD`、`OPTIONS`。
6. 任务完成后审查 work log、diff 和测试结果。

本地 Codex 如果确实要让 workspace-write 命令联网，可以显式配置：

```toml
[sandbox_workspace_write]
network_access = true
```

这不是新手默认配置。只有在你理解风险、信任仓库、并且知道要访问什么网络资源时再开。
---

## 为什么 POST 更危险

很多外传动作依赖写入型请求，例如 `POST`、`PUT`、`PATCH`、`DELETE`。官方建议把 allowed HTTP methods 限制在 `GET`、`HEAD`、`OPTIONS`，就是为了减少 agent 把本地信息发送出去的机会。

这不能消除所有风险，但能减少一类常见事故。
---

## 新手常见坑

- 看到依赖安装失败，就直接给 agent 阶段开全网。
- 用 All unrestricted 解决一次问题，然后忘记关。
- 把 GitHub issue、README、网页内容当成可信指令。
- 只看任务是否完成，不看 work log 里访问过哪些 URL。
- 允许写入型 HTTP methods，却没有明确理由。
- 在含有 secrets 的仓库里打开高权限联网。
---

## 怎么判断配置正确

成功标准：

- setup 阶段能安装依赖。
- agent 阶段只访问你允许的域名。
- 不需要联网的任务仍然能在离线 agent 阶段完成。
- 被阻止的请求能在日志里看见原因。
- 任务完成后 diff 可审查、测试可复现。
- 没有把网络权限作为永久默认值。

如果你不知道该允许哪个域名，先不要放开全网。让 Codex 报出缺失资源，再按日志逐个加。

## 复查清单

- 是否真的需要 agent 阶段联网，而不是 setup 阶段联网。
- 是否只允许了任务所需域名，而不是 All unrestricted。
- 是否限制了写入型 HTTP methods。
- 是否检查了 work log、diff、测试结果和异常访问记录。
- 是否在任务结束后把临时网络权限恢复到默认状态。

## 接下来去哪

<Cards>
  <Card title="Cloud 运行环境" description="先确认 setup 阶段、agent 阶段和远程环境边界。" href="/docs/codex/official/05-cloud-remote/18-cloud-runtime" />
  <Card title="审批与安全" description="联网权限要和 approval、sandbox、network 一起判断。" href="/docs/codex/official/02-config-security/07-approval-security" />
  <Card title="网络安全边界" description="理解为什么默认关闭网络，以及什么时候才应该放开。" href="/docs/codex/official/02-config-security/50-network-security" />
  <Card title="官方 Agent internet access" description="需要最新 allowlist、method 和 Cloud 设置时回官方核验。" href="https://developers.openai.com/codex/cloud/internet-access" />
</Cards>
---

## 官方资料

- [OpenAI Codex: Agent internet access](https://developers.openai.com/codex/cloud/internet-access)
- [OpenAI Codex: Agent approvals and security](https://developers.openai.com/codex/agent-approvals-security)
