Codex CLI 沙箱模式详解：sandbox_mode 与 approval_policy 怎么配

Codex CLI 的沙箱（sandbox）是一层 OS 级边界：它决定编码 Agent 能往哪儿写文件、能不能出网，与"什么时候停下来等你批准"的 approval_policy 是两条互相独立的轴。很多人把它当成一个开关，结果要么放得太松、要么卡得太死。本文按 Codex 官方源码（codex-rs）里的枚举定义逐项核对，把 sandbox_mode 四档、workspace-write 子选项和 approval_policy 取值讲清楚。

1. sandbox_mode 的四个档位

config.toml 里的 sandbox_mode 对应源码中的 SandboxPolicy 枚举，serde 取值共四个：

# ~/.codex/config.toml
sandbox_mode = "workspace-write"

read-only 不是"什么都不能干"——Codex 仍然读代码、跑只读命令，只是不能落盘；给它 network_access = true 就变成一个能联网查资料的只读审查器。external-sandbox 的语义比较特殊：它声明"磁盘边界由外部环境（容器）保证"，所以磁盘全开，只留下网络这一个声明式开关。

2. workspace-write 的子选项

日常最常用的一档，源码里有四个可配字段：

• writable_roots：除 cwd 与 TMPDIR 之外追加的可写目录列表
• network_access：默认 false，置 true 放开出网
• exclude_tmpdir_env_var：置 true 时不再把用户级 TMPDIR 纳入默认可写根
• exclude_slash_tmp：置 true 时 UNIX 上的 /tmp 不再默认可写

值得单独说的一点：可写根目录（WritableRoot）带一个只读子路径清单——.codex、.git、.git/hooks 这类目录在可写根内部依然只读。源码注释写明了动机：这些目录里的文件可能被用来提升 Agent 权限（比如往 git hooks 里塞命令），所以即便在 workspace-write 里也不放行。

3. approval_policy 是另一条轴

沙箱管"能碰什么"，审批策略管"要不要问你"。approval_policy 当前取值：

• on-request：默认值，模型自己判断何时需要你批准
• on-failure：on-request 的 serde 别名，写到配置里等价
• granular：按命令类别精细控制——某类命令放行、另一类直接拒绝而不是弹批准框
• never：从不询问，失败直接返回给模型自己处理

一个容易踩的坑：老教程里的 untrusted 取值已不再受支持——源码里对该值直接返回 "no longer supported; remove this setting" 错误，升级后配置里有这行要删掉。

4. 组合建议与常见错误

几个常用组合：

# 交互式日常编码（默认形态）
sandbox_mode = "workspace-write"
approval_policy = "on-request"

# CI / 无人值守
sandbox_mode = "workspace-write"
approval_policy = "never"

# 容器里跑（磁盘边界交给外部环境）
sandbox_mode = "external-sandbox"

常见错误有两个：一是把 approval_policy = "never" 当成"更安全"——恰恰相反，它去掉了所有确认环节，要配合收紧的 sandbox 用；二是在 CI 里用 danger-full-access 图省事——CI 正确姿势是 workspace-write（或 external-sandbox）+ never，再加一个独立 git worktree 接 diff。

另外 Windows 平台有独立的 windows_sandbox_mode 选项控制 Windows 沙箱形态，与 sandbox_mode 并存。

5. 下一步

• OpenAI Codex CLI 入门：从零配置到日常编码流 — 还没装好 Codex 的先从这里开始
• Codex CI 集成实战：把 Codex CLI 跑进 GitHub Actions — 无人值守场景的完整落地
• Codex CLI vs IDE 扩展 vs Codex Cloud：三种形态怎么选 — 如果你还在选形态