Codex 沙箱模式全解：三种权限级别配置实战

为什么沙箱配置是 Codex 使用的「生死线」？

很多新手第一次用 Codex 时直接开干——结果不是被频繁弹窗打断，就是误改了系统文件。根本原因只有一个：没有理解沙箱的作用。

Codex 的沙箱不是"建议"，是内核级别的强制隔离。macOS 用 Seatbelt，Linux 用 Landlock + bubblewrap，Windows 用原生沙箱。每次 Codex 执行命令之前，都会经过这层过滤。

搞清楚沙箱的三种模式，是你安全使用 Codex 的第一步。

一、三种沙箱模式全解

1. read-only：只读模式

能做什么： 读取文件、执行只读命令（ls、cat、grep）。 不能做什么： 写任何文件、修改项目、执行有副作用的命令。

适用场景： - 代码库探索：快速了解项目结构 - 架构分析：梳理模块关系 - 漏洞排查：只读诊断，不改代码

启动方式：

codex --sandbox read-only --ask-for-approval on-request
复制

在 config.toml 中持久化：

[sandbox]
sandbox_mode = "read-only"
approval_policy = "untrusted"
复制

2. workspace-write：工作区读写（日常开发首选）

能做什么： 读取整个文件系统，但写入仅限当前工作目录（含临时目录 /tmp）。网络访问默认禁止。 不能做什么： 修改项目外的文件、访问外部网络、执行高危系统命令。

适用场景： - 日常编码开发 - 批量修改项目文件 - 运行测试、Lint、构建

这是官方推荐的默认模式。

启动方式：

codex --sandbox workspace-write --ask-for-approval on-request
复制

在 config.toml 中持久化：

[sandbox]
sandbox_mode = "workspace-write"
approval_policy = "on-request"

# 可选：允许工作区内网络访问（比如需要安装依赖）
[sandbox_workspace_write]
network_access = true
复制

注意： 官方已废弃 --full-auto 参数，统一用 --sandbox workspace-write 替代。

3. danger-full-access：完全访问模式

能做什么： 无限制读写任何文件、访问网络、执行任意系统命令。 不能做什么： 没什么不能做的——这正是它的危险之处。

适用场景： - 容器化环境（Docker 内作为隔离边界） - 完全可信的一次性任务

启动方式：

codex --sandbox danger-full-access --ask-for-approval never
复制

⚠️ 强烈不建议日常使用。 除非你清楚自己在做什么，否则不要轻易开这个模式。

二、配置方式：命令行 vs config.toml

命令行方式（临时生效）

# 交互式会话，workspace-write 模式
codex --sandbox workspace-write

# 非交互执行，不请求审批
codex exec "修复 README 拼写错误" \
  --sandbox workspace-write \
  --ask-for-approval never
复制

config.toml 方式（持久配置）

全局配置路径：~/.codex/config.toml

# 推荐：日常开发配置
approval_policy = "on-request"
sandbox_mode = "workspace-write"

# 可选：保存为 profile，一键切换
[profiles.full_auto]
approval_policy = "on-request"
sandbox_mode = "workspace-write"

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

切换 profile：

codex --profile full_auto
codex --profile readonly_quiet
复制

三、Linux/WSL2 下的沙箱故障排查

如果你在使用 Linux 或 WSL2 时遇到沙箱报错，常见原因和解决方式：

故障 1：缺少 bubblewrap

Linux 沙箱依赖 bubblewrap 工具。检查并安装：

# Debian/Ubuntu
sudo apt update
sudo apt install -y bubblewrap
bwrap --version
复制

故障 2：项目未被标记为「可信」

Codex 只在受信任的项目中加载项目级 .codex/config.toml。检查并设置信任：

codex trust status    # 查看状态
codex trust add .     # 将当前目录标记为可信
复制

故障 3：WSL2 内核版本过旧

确保 WSL2 内核已更新：

wsl --update
复制

四、真实案例：如何正确配置一个 Python 项目

假设你在开发一个 Flask API 项目，需要 Codex 帮你加单元测试。推荐配置：

1. 初始化项目级配置

cd ~/projects/my-flask-api
codex trust add .
复制

2. 创建 .codex/config.toml

[sandbox]
sandbox_mode = "workspace-write"
approval_policy = "on-request"

[sandbox_workspace_write]
network_access = false  # 不需要网络，禁止访问

[model]
model = "gpt-5.2-codex"
model_reasoning_effort = "medium"
复制

3. 启动 Codex

codex
复制

4. 输入任务

请在 tests/ 目录下为 src/api/routes.py 中的所有路由函数生成 pytest 测试用例
复制

五、安全最佳实践总结

几条红线： 1. 永远不要在日常开发中用 danger-full-access 2. 不要随意关闭审批（approval_policy = "never"），除非你在 CI/CD 环境中 3. 工作区内写文件前，养成 git diff 确认的习惯 4. 敏感密钥（DB 密码、API Key）加入 .gitignore，不要让 Codex 读到

来源： 本文根据社区 Codex 沙箱配置实战内容整理改写，核心配置参考官方 GitHub 仓库 openai/codex 及多位开发者的实践经验。

资料最后核对日期：2026-09-16 · 内容整理自 CodexGuide 社区公开教程