---
title: "理解沙箱邊界"
description: "Sandbox 是讓 Codex 能自主行動、但不獲得機器 unrestricted access 的邊界。"
verifiedAt: "2026-05-06"
---

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

Sandbox 是讓 Codex 能自主行動、但不獲得機器 unrestricted access 的邊界。Approvals 決定越界時是否必須停下來詢問。

> [!IMPORTANT]
> Sandbox 和 approval 是兩層控制：sandbox 定義技術邊界，approval policy 定義什麼時候必須詢問。只改其中一個，風險模型並不完整。

<Cards>
  <Card title="Approvals and security" href="https://developers.openai.com/codex/agent-approvals-security">
    官方 sandbox、approval 和 network access 說明。
  </Card>
  <Card title="Config basics" href="/zh-Hant/docs/codex/official/02-config-security/06-basic-config">
    把預設 sandbox 和 approval 寫進 `config.toml`。
  </Card>
  <Card title="Windows sandbox" href="/zh-Hant/docs/codex/official/01-products/42-windows-app">
    Windows native、fallback 和 WSL2 的邊界不同。
  </Card>
</Cards>

## 兩層模型

```mermaid
flowchart LR
    Task["Codex action"] --> Sandbox["sandbox mode"]
    Sandbox --> Allowed["inside boundary"]
    Sandbox --> Escalate["needs escalation"]
    Escalate --> Approval["approval policy"]
    Approval --> Run["run / deny / ask"]
```

Sandbox 控制：

- 能讀寫哪些檔案。
- 命令是否能使用網路。
- workspace 外操作是否被攔住。
- spawned commands 繼承什麼邊界。

Approval policy 控制：

- 什麼時候詢問你。
- 越界請求是否允許出現。
- 是否允許 Codex 在不打斷你的情況下繼續嘗試。

## 為什麼重要

Sandbox 可以減少 approval fatigue。Codex 不必要求你確認每個低風險 command，而是可以在已批准邊界內 read files、make edits、執行 routine project commands。

它也讓 trust model 更清晰：你不只是相信 agent 的意圖，還能知道 agent 執行在 enforced limits 內。

預設情況下，本地 Codex 通常會把網路訪問關掉，並把寫入限制在 active workspace。Codex cloud 則執行在 OpenAI-managed isolated containers，setup 和 agent phase 的網路與 secret 邊界不同，按 cloud environment 配置處理。

## 常見模式

只讀理解：

```toml
sandbox_mode = "read-only"
approval_policy = "on-request"
```

本地小改動：

```toml
sandbox_mode = "workspace-write"
approval_policy = "on-request"
```

full access：

```toml
sandbox_mode = "danger-full-access"
approval_policy = "never"
```

full access 會移除關鍵邊界，只適合你明確希望 Codex 在可重建環境裡行動。不要把它設成日常預設。

## Network access

workspace-write 預設不等於可以隨便聯網。需要讓 spawned commands 訪問網路時，必須在配置中明確開啟：

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

Web search 和 spawned command network access 不是同一件事。Codex 的 web search 可以走 cached mode，而命令列工具訪問網路受 sandbox network 設定控制。

所有網頁結果都應當作不可信輸入處理，尤其是 live browsing 和外部文件。

## 平臺差異

macOS、Linux、WSL2 和 native Windows 使用不同 platform-native enforcement，但核心思想一致：給 agent 一個受限工作空間，讓 routine tasks 可以在明確限制內自主執行。

Linux / WSL2 需要可用的 bubblewrap。不同發行版和 AppArmor 配置細節會變化，遇到啟動 warning 時，以官方 sandbox 文件和發行版文件為準，不要直接關閉系統級限制。

Windows native 有自己的 sandbox 模式；WSL2 則使用 Linux sandbox implementation。Windows 專案和 WSL 專案的路徑、shell、工具鏈要先對齊。

## 不要濫用例外

如果需要跨多個 directories 工作，優先使用 writable roots 擴充套件可修改位置，而不是完全移除 sandbox。

如果 workflow 只需要某個命令越界，優先用 rules 做 targeted exceptions，讓特定 command prefix allow、prompt 或 forbidden。

Automatic review 可用時，也不會改變 sandbox boundary。它 review approval requests；sandbox 內已允許的 actions 仍會直接執行。

## 常見坑

- 把 `approval_policy = never` 當成安全設定。
- 用 full access 解決所有許可權問題。
- 需要訪問一個額外目錄，卻直接關閉 sandbox。
- 讓網路訪問和 web search 混在一起理解。
- Linux 上看到 bubblewrap warning 後直接關閉系統限制。
- Windows native 和 WSL2 路徑混用，導致 Codex 在錯誤目錄工作。

## 驗收清單

- 當前會話能說清 sandbox mode 和 approval policy。
- workspace 範圍和 writable roots 可解釋。
- 網路訪問預設關閉，只有明確需要才開啟。
- 越界操作會進入 approval 或被 rules 控制。
- full access 只用於可重建、可回復的環境。
- 平臺依賴如 bubblewrap、Windows sandbox、WSL2 路徑都已確認。

## 官方資料

- [Agent approvals and security](https://developers.openai.com/codex/agent-approvals-security)
- [Config basics](https://developers.openai.com/codex/config-basic)
- [Config reference](https://developers.openai.com/codex/config-reference)
- [Windows](https://developers.openai.com/codex/windows)
