理解沙箱边界

Sandbox 是让 Codex 能自主行动、但不获得机器 unrestricted access 的边界。

当 Codex 在 Codex App、IDE extension 或 CLI 中运行 local commands 时，这些 commands 默认不会以 full access 直接运行，而是在受约束的 environment 中运行。

这个 environment 定义 Codex 可以自己做什么，例如：

能修改哪些 files。
commands 是否可以使用 network。

任务留在这些边界内时，Codex 可以持续推进，不需要停下来确认。需要越界时，Codex 会回到 approval flow。

Sandboxing 和 approvals 是协同工作的两种控制。sandbox 定义技术边界；approval policy 决定 Codex 什么时候必须停下来询问。

沙箱会做什么

sandbox 不只适用于 Codex built-in file operations，也适用于 spawned commands。

如果 Codex 运行 git、package managers 或 test runners，这些 commands 会继承同样的 sandbox boundaries。

Codex 在每个 OS 上使用 platform-native enforcement。macOS、Linux、WSL2 和 native Windows 的实现不同，但核心思想一致：给 agent 一个受限工作空间，让 routine tasks 可以在明确限制内自主运行。

为什么重要

Sandbox 可以减少 approval fatigue。Codex 不必要求你确认每个低风险 command，而是可以在你已批准的边界内 read files、make edits、运行 routine project commands。

它也让 agentic work 的 trust model 更清晰：你不只是相信 agent 的意图，还能相信 agent 运行在 enforced limits 内。这样你更容易让 Codex 独立工作，同时知道它什么时候会停下来请求帮助。

开始使用

使用 default permissions mode 时，Codex 会自动应用 sandboxing。

前置要求

平台前置条件：

平台	Sandbox 支持
macOS	开箱即用，使用 built-in Seatbelt framework。
Windows	在 PowerShell 中运行时使用 native Windows sandbox；在 WSL2 中运行时使用 Linux sandbox implementation。
Linux / WSL2	先用 package manager 安装 `bubblewrap`。

Ubuntu / Debian：

sudo apt install bubblewrap

Fedora：

sudo dnf install bubblewrap

Codex 会使用 PATH 上找到的第一个 bwrap executable。如果没有可用 bwrap executable，Codex 会 fallback 到 bundled helper，但这个 helper 需要支持 unprivileged user namespace creation。

安装 distribution package 提供的 bwrap，通常更可靠。

当 bwrap 缺失，或 helper 无法创建所需 user namespace 时，Codex 会在 startup 显示 warning。对限制这个 AppArmor setting 的 distributions，建议加载 bwrap AppArmor profile，让 bwrap 正常工作，而不是全局关闭 restriction。

Ubuntu AppArmor note：

Ubuntu 25.04：从 Ubuntu package repository 安装 bubblewrap 通常不需要额外 AppArmor setup。bwrap-userns-restrict profile 位于 apparmor package 中，路径是 /etc/apparmor.d/bwrap-userns-restrict。
Ubuntu 24.04：安装 bubblewrap 后，Codex 仍可能提示不能创建所需 user namespace。可以复制并加载额外 profile。

Ubuntu 24.04 处理命令：

sudo apt update
sudo apt install apparmor-profiles apparmor-utils
sudo install -m 0644 \
  /usr/share/apparmor/extra-profiles/bwrap-userns-restrict \
  /etc/apparmor.d/bwrap-userns-restrict
sudo apparmor_parser -r /etc/apparmor.d/bwrap-userns-restrict

apparmor_parser -r 会把 profile 加载进 kernel，不需要 reboot。

也可以 reload 全部 AppArmor profiles：

sudo systemctl reload apparmor.service

如果该 profile 不可用，或不能解决问题，可以关闭 AppArmor 的 unprivileged user namespace restriction：

sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0

如何控制沙箱

大多数用户从产品里的 permissions controls 开始。

在 Codex App 和 IDE 中，composer 或 chat input 下方有 permissions selector。它允许你：

使用 Codex default permissions。
切换到 full access。
使用 custom configuration。

官方截图：

https://developers.openai.com/images/codex/app/permissions-selector-light.webp

在 CLI 中，用 /permissions 在 session 中切换 modes。

配置默认行为

如果你希望 Codex 每次启动都使用同样行为，使用 custom configuration。

Codex 会把这些 defaults 存在 local settings file，也就是 config.toml 中。

相关文档：

Config basics：https://developers.openai.com/codex/config-basic
Configuration reference：https://developers.openai.com/codex/config-reference

关键 keys：

sandbox_mode
approval_policy
sandbox_workspace_write.writable_roots

它们决定：

Codex 默认有多大 autonomy。
Codex 可以写哪些 directories。
Codex 什么时候应该暂停并请求 approval。

常见 sandbox modes：

Mode	说明
`read-only`	Codex 可以 inspect files，但不能 edit files，也不能在没有 approval 的情况下运行 commands。
`workspace-write`	Codex 可以 read files，在 workspace 内 edit，并在该边界内运行 routine local commands。这是 local work 的 default low-friction mode。
`danger-full-access`	Codex 在没有 sandbox restrictions 的情况下运行。它会移除 filesystem 和 network boundaries，只应在你明确希望 Codex full access 行动时使用。

常见 approval policies：

Policy	说明
`untrusted`	Codex 在运行不属于 trusted set 的 commands 前会询问。
`on-request`	Codex 默认在 sandbox 内工作，需要越界时询问。
`never`	Codex 不会为 approval prompts 停下。

Full access 指同时设置：

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

相对低风险的 local automation preset 是：

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

对应 CLI flags：

--sandbox workspace-write --ask-for-approval on-request

如果你需要 Codex 跨多个 directories 工作，使用 writable roots 扩展可修改位置，而不是完全移除 sandbox。

如果你需要更宽或更窄的 trust boundary，调整 default sandbox mode 和 approval policy，不要依赖一次性 exceptions。

Reusable permission sets：

设置 default_permissions 指向一个 named profile。
定义 [permissions.<name>.filesystem] 或 [permissions.<name>.network]。
managed network profiles 使用 [permissions.<name>.network.domains] 和 [permissions.<name>.network.unix_sockets] 这类 map tables，管理 domain 和 socket rules。
filesystem profiles 可以通过把 exact paths 或 glob patterns 设置为 "none" 来 deny reads，用于让 local secrets 在不关闭 workspace writes 的情况下不可读。

当 workflow 需要特定 exception，使用 rules。Rules 可以让你在 sandbox 外 allow、prompt 或 forbid command prefixes，通常比大范围扩大 access 更合适。

更多入口：

Codex App approvals and sandboxing：https://developers.openai.com/codex/app/features#approvals-and-sandboxing
Codex IDE extension settings：https://developers.openai.com/codex/ide/settings

Automatic review 可用时，不会改变 sandbox boundary。它 review approval requests，例如 sandbox escalations 或 network access；sandbox 内已允许的 actions 仍会直接运行，不会额外 review。

Automatic approval reviews：

https://developers.openai.com/codex/agent-approvals-security#automatic-approval-reviews

平台细节见对应文档：

Native Windows setup、behavior、troubleshooting：https://developers.openai.com/codex/windows
Admin requirements 和 organization-level sandbox/approval constraints：https://developers.openai.com/codex/agent-approvals-security