Codex 在 Linux/WSL2 上沙箱不可用，先查 bubblewrap 装没装

2026-08-09

在 Linux 或 WSL2 里用 Codex（OpenAI Codex）的命令行，如果沙箱这一层起不来，症状往往不是一个醒目的报错，而是一种”说不上哪里不对”的别扭感。这篇只讲一件事：怎么判断这是不是缺 bubblewrap 造成的，以及确认之后该怎么办。

一、先把现象说清楚

Codex CLI 的沙箱不是一个可选的装饰件，它是执行命令这条链路的地基。官方对默认模式 workspace-write 的原话是”The agent can read files, edit within the workspace, and run routine local commands inside that boundary”——注意最后半句，本地命令是”在这个边界内”跑的。边界这层东西如果在你的系统上根本建不起来，那么”跑命令”和”改文件”这两件事就会同时变得不可靠。

所以典型的可疑信号是这几类：沙箱相关的启动检查过不去；本该被限制住的操作表现异常；或者反过来，明明只想让它读点东西，结果它连基本动作都做不成。这里我不去替你描述具体的报错文案——我们的实测环境是 Windows 11，Linux 侧的错误文案没有实测过，编一条给你反而会把你带偏。判断该走本文这条线，靠的是环境特征，不是靠对着某句错误提示猜。

二、关键前提：Linux 和 WSL2 是同一套，Windows 原生是另一套

这是整件事最容易搞混的地方，先把它钉死。官方文档写明了沙箱实现是分平台的：

运行环境	沙箱实现
macOS	系统内置的 Seatbelt 框架
Windows（PowerShell 中）	原生 Windows 沙箱
WSL2	Linux 沙箱实现
Linux	需要用包管理器安装 `bubblewrap`（bwrap）

看第三行和第四行。WSL2 虽然跑在 Windows 上，走的却是 Linux 那套沙箱实现，所以它的排查路径跟 Linux 完全一致，跟 Windows 原生那套没有半点关系。很多人卡住就卡在这儿：宿主是 Windows 11，于是本能地去翻 Windows 沙箱的资料、去折腾管理员权限，结果方向从第一步就错了。

反过来也一样：如果你是在 PowerShell 里直接跑 Codex CLI，那你用的是原生 Windows 沙箱，那是另一套完全不同的机制。官方文档把它分成 elevated 和 unelevated 两种模式（elevated 被官方标注为首选）：elevated 使用专用的低权限沙箱用户，边界由文件系统权限加防火墙规则构成，代价是需要管理员批准的初始化设置；unelevated 是拿不到管理员批准时的回退，用”从当前用户派生的受限 Windows token”运行命令，文件系统边界基于 ACL，并用环境级的离线控制替代防火墙规则，官方明说它保护更弱。这两种模式的细节该看 Windows 沙箱那条线，不在本文范围内——你只需要记住一点：不管它走哪种模式，装一百遍 bubblewrap 也不会有任何变化。

需要说明的是，“Linux 查 bwrap、Windows 另走一路”这条判断路径并不是官方文档的原话，官方在这件事上写下的只有那张分平台实现表；判断路径是顺着这张表往下推出来的：既然 Linux / WSL2 的沙箱明确依赖包管理器安装的 bubblewrap，那么在这两个环境里遇到沙箱起不来，第一件事自然是查 bwrap 装没装；而 Windows 原生那套跟 bubblewrap 毫无关系，把 Linux 的排查步骤照搬过去只会白费工夫。

三、怎么确认是这个问题

按下面的顺序走，三步之内就能定性。全部是只读操作，不会改你的任何东西。

第 1 步：确认你到底在哪个环境里。

先分清自己是在 WSL2 的发行版里敲命令，还是在 PowerShell 里敲。这一步听着像废话，但在同一台 Windows 机器上开着两个终端来回切的人非常多。判断标准很简单：命令提示符所在的 shell 是 Linux 发行版的，就按本文往下走；是 PowerShell，就该去看原生 Windows 沙箱那条线（windows.sandbox 的 elevated / unelevated 两种模式、错误 1385、日志在 CODEX_HOME/.sandbox/sandbox.log），本文帮不上忙。

第 2 步：查 bwrap 这个可执行文件在不在。

command -v bwrap

这条不是 Codex 的命令，是通用的 shell 查法：它在 PATH 里找名为 bwrap 的可执行文件，找到就打印路径，找不到就什么都不输出、返回非零退出码。什么都没打出来，基本就锁定了——Linux/WSL2 上的沙箱依赖它，它不在，沙箱自然没得建。

第 3 步：跑一次 codex doctor，看沙箱那一行。

codex doctor --summary

doctor 的官方定位是”Diagnose local Codex installation, config, auth, and runtime health”。它的输出按组呈现，其中 Configuration 组里有一项就叫 sandbox，这是整份诊断里唯一直接对应沙箱的检查项。在 codex-cli 0.147.0（Windows 11）上，我们实测这一行显示的是 restricted fs + restricted network · approval OnRequest，行首状态符号为 ✓。Linux 上这一行会显示什么文案我们没有实测过，但检查项名字和状态符号体系是一致的：✓ ok、○ idle、⚠ notes/warn、✗ fail。你要看的就是这一行是不是绿的。

顺便说一句：codex doctor --json 的官方说明是 “Emit a redacted machine-readable report”——是脱敏后的报告，所以要贴给同事或提 issue 时用这个格式相对稳妥，比截一张整屏终端要干净。

四、官方给出的处置

官方文档在这件事上给的就是一句话：Linux / WSL2 需要用包管理器安装 bubblewrap（bwrap）。

我这里不给你一条具体的 sudo xxx install 命令。原因很实在：官方文档没有给出具体到某个发行版的安装命令，而各发行版的包管理器和包名策略并不统一，我随手编一条出来，对不上的人反而要多绕一圈。用你所在发行版惯用的包管理器，安装名为 bubblewrap 的包，这就是官方口径的全部。

另外提醒一句，别去 features 列表里找”替代开关”当解法。在 codex-cli 0.147.0 上执行 codex features list，能看到 use_legacy_landlock 这一项，阶段标注为 deprecated、生效值 false。我们没有验证过它的实际作用，它带着 deprecated 标签，不该被当成缺 bwrap 时的绕行方案。

五、装完之后怎么验证

别装完就直接去跑正经任务，先做两步确认，省得白高兴。

第一步，还是那条查法：

command -v bwrap

这次应该打出一个路径。如果还是空的，常见的方向有两个：可执行文件不在当前 shell 的 PATH 里，或者当前这个会话的环境是装包之前就起好的、没刷新过，新开一个终端再试一次。需要声明的是，这一步的解读同样属于通用的 shell 排查思路，不是 Codex 官方文档的内容——口径和上面第 2 步一致，官方在这件事上只交代了”要装 bubblewrap”，没有交代装完怎么查。

第二步，重新跑一次诊断，并且盯住版本号：

codex --version
codex doctor --summary

codex --version 不是走过场。我们在同一台机器上采集数据时遇到过一件事：开头执行 codex --version 得到 codex-cli 0.131.0，十几分钟后再执行同一条命令得到 codex-cli 0.147.0，而 which -a codex 全程只有一个可执行文件。Codex 具备自更新能力（配置里 check_for_update_on_startup 默认为 true），所以”我记得我装的是某个版本”这种记忆完全靠不住。排查沙箱这类跟平台实现强相关的问题，一律以当次 codex --version 的实时输出为准。

然后回到 doctor 的 Configuration 组，看 sandbox 那一行的状态符号有没有从异常变成 ✓。

还想再确认一层的话，可以用 codex sandbox 子命令在沙箱里跑一条无害命令看看行为。这里有个细节值得说：在 codex-cli 0.147.0（Windows 11）上，codex sandbox --help 里位置参数的官方说明是 “Full command args to run under Windows restricted token sandbox”——这句 help 文案里直接带着 Windows 字样，恰好印证了沙箱实现是随平台走的，Linux 上的 help 文案我们没有实测，请以你机器上 codex sandbox --help 的实际输出为准。

六、这些情况说明不是 bwrap 的锅

排查最怕一条道走到黑。下面几种症状看着像沙箱问题，实际另有出处，对照着排除掉：

参数写错了。 在 codex-cli 0.147.0（Windows 11）上执行 codex -s bogus-mode，得到的是：

error: invalid value 'bogus-mode' for '--sandbox <SANDBOX_MODE>'
  [possible values: read-only, workspace-write, danger-full-access]

看到这种 invalid value 就别往 bwrap 上想了，纯粹是取值拼错，合法值就是括号里那三个。

配置文件根本没加载成功。 在 codex-cli 0.147.0（Windows 11）上，我们故意给 -c 传了一段语法不合法的 TOML，doctor 没有崩溃退出，照常跑完，但输出里出现了 ✗ config config could not be loaded。所以”我明明在 config.toml 里配了 sandbox_mode，怎么一点用没有”——第一步该跑 doctor 看 config 这一行，而不是怀疑沙箱本身。

症状是”问不问你”而不是”能不能做”。 每次都弹审批、或者从来不弹，那是 approval_policy 的三档（untrusted / on-request / never）在起作用，跟 bwrap 无关。这里有个高频误解要点出来：never 不等于”放开权限”，它改变的只是”要不要问你”，沙箱边界还在，执行失败会直接回传给模型。真正撤掉边界的是 danger-full-access 或 --dangerously-bypass-approvals-and-sandbox（官方原文是 “EXTREMELY DANGEROUS. Intended solely for running in environments that are externally sandboxed”）。

症状是能改文件但出不了网。 那是 workspace-write 下的 sandbox_workspace_write.network_access 在管，更细的域名级控制走 permissions.<name>.network.domains.<pattern>（allow / deny，支持通配）。还有一个 features.network_proxy，它的阶段标注是 experimental，别当稳定能力依赖。

症状是写不进工作区之外的目录。 那是 workspace-write 的边界本身在正常工作，不是故障。要在不撤掉沙箱的前提下扩可写范围，用 sandbox_workspace_write.writable_roots，或者 CLI 侧的 --add-dir。

你在 macOS 上。 macOS 用的是系统内置的 Seatbelt 框架，不是 bubblewrap，本文整条路径都不适用。

最后交代一句边界：沙箱能建起来不等于万事大吉。官方自己在讲 Windows 那套的 unelevated 模式时都明确写了”保护更弱”，任何一层沙箱都只是收窄了影响范围，不是安全承诺。装上 bubblewrap 让边界能建起来，和这个边界拦得住什么，是两个问题。