---
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="/docs/codex/official/02-config-security/06-basic-config">
    把默认 sandbox 和 approval 写进 `config.toml`。
  </Card>
  <Card title="Windows sandbox" href="/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)
