---
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="/zh-Hant/docs/codex/official/05-cloud-remote/18-cloud-runtime" />
  <Card title="審批與安全" description="聯網許可權要和 approval、sandbox、network 一起判斷。" href="/zh-Hant/docs/codex/official/02-config-security/07-approval-security" />
  <Card title="網路安全邊界" description="理解為什麼預設關閉網路，以及什麼時候才應該放開。" href="/zh-Hant/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)
