沙箱（Sandbox）是让 Codex 能自主工作的同时，限制它能触碰哪些文件和网络的边界层。默认情况下 Codex 只能读写当前工作目录，网络访问关闭，需要超出这个范围时才会弹出审批请求。本文解释沙箱和审批策略的区别、三种模式的实际效果，以及如何在 config.toml 里自定义。

Codex 沙箱：Agent 执行边界

沙箱是 Codex 自主工作的安全前提——它在保证你不用每次都点"确认"的同时，限制了 Agent 能触碰的范围。

沙箱 vs 审批策略，这两个概念不一样：

• 沙箱模式：技术边界，定义 Codex "能做什么"（可以写哪些目录、能否访问网络）
• 审批策略：决策节点，定义 Codex "什么时候需要停下来问你"

---

为什么需要沙箱

没有沙箱，你需要对 Agent 每个操作都手动确认，工作效率大打折扣。有了沙箱，Codex 可以在你批准的范围内自主运行——读文件、改代码、跑测试——只有需要超出这个范围时才弹出审批。

沙箱不只限制 Codex 的内置操作，还约束它通过 Bash 运行的所有外部命令（git、包管理器、测试框架等），它们都继承同样的边界。

---

三种沙箱模式

read-only

Codex 只读，不写文件，不执行命令（除非你手动批准每一步）。适合：咨询模式、只想让 AI 解释代码但不改动任何东西。

workspace-write（默认）

Codex 可以读文件、编辑工作目录内的文件、运行常见的本地命令。网络访问默认关闭。这是日常本地工作的最佳平衡点。

.git、.agents、.codex 目录在这个模式下依然是只读保护的，Codex 无法修改版本控制元数据和配置文件。

danger-full-access

完全无限制，包括网络访问。只在你明确需要且信任当前任务时才使用，配合容器化环境更安全。

---

如何控制沙箱

在 App 和 IDE 里

在输入框下方的权限选择器里选择：

• Default permissions（workspace-write）
• Full access（danger-full-access）
• Custom（读取 config.toml 配置）

在 CLI 里

启动时指定：

codex --sandbox workspace-write   # 默认模式
codex --sandbox read-only         # 只读咨询
codex --full-auto                 # workspace-write + on-request 审批（快捷组合）

会话中用 /permissions 实时切换。

---

审批策略

策略	说明
on-request（默认）	在沙箱内自动执行，需要超出边界时才问
untrusted	只对已知安全的只读操作自动执行，其他命令都要确认
never	从不弹出审批提示（在 Auto 模式下使用，配合沙箱保护）

常用组合：

场景	命令
日常开发（推荐）	codex --full-auto
只读咨询	codex --sandbox read-only --ask-for-approval on-request
CI/只读脚本	codex --sandbox read-only --ask-for-approval never
危险完全访问	codex --dangerously-bypass-approvals-and-sandbox（--yolo）

---

在 config.toml 里配置

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

# 开启网络访问（在 workspace-write 模式下）
[sandbox_workspace_write]
network_access = true

可以配置 Profile 快速切换：

[profiles.full_auto]
approval_policy = "on-request"
sandbox_mode    = "workspace-write"

[profiles.readonly_quiet]
approval_policy = "never"
sandbox_mode    = "read-only"

使用时：codex --profile full_auto

---

平台实现

平台	实现方式
macOS	Seatbelt（sandbox-exec），内置，无需安装额外工具
Linux / WSL2	bubblewrap（bwrap）+ seccomp
Windows 原生	Windows Sandbox
Windows WSL2	使用 Linux 沙箱实现

Linux 用户需要先安装 bubblewrap：

# Ubuntu/Debian
sudo apt install bubblewrap

# Fedora
sudo dnf install bubblewrap

在 Docker 容器里运行时，如果 Landlock/seccomp 不可用，可以让 Docker 提供隔离，然后在容器内用 --sandbox danger-full-access 运行 Codex。

---

测试沙箱行为

用 codex sandbox 在沙箱里运行任意命令，验证限制是否按预期工作：

# macOS
codex sandbox macos --full-auto [命令]

# Linux
codex sandbox linux --full-auto [命令]

---

常见问题

Q: 沙箱能彻底保护我的系统不被 Codex 意外破坏吗？

A: 沙箱提供了显著的保护，但不是万能的。workspace-write 模式下 Codex 仍然可以修改工作目录里的所有文件。最佳实践是：在 Git 仓库里工作，保持干净的 working tree，这样 Codex 的任何改动都可以用 git diff 查看和 git checkout 回退。

Q: 需要开启网络才能安装依赖怎么办？

A: 在 config.toml 里的 [sandbox_workspace_write] 块里设置 network_access = true，或者用 --sandbox danger-full-access。注意开启网络访问后要警惕 prompt injection 风险（AI 被诱导访问恶意 URL）。

Q: CI 环境里如何运行 Codex？

A: 用 codex --sandbox read-only --ask-for-approval never 做只读分析，或者在容器里用 --sandbox danger-full-access 配合完整工作流。详见 非交互模式。