`winget` 不可用时，Codex 的 Windows 沙箱为什么起不来

2026-08-09

一、先说现象

在 Windows 上装好 Codex（OpenAI Codex）的命令行工具，第一次要它跑点东西，沙箱初始化就没起来。这时候多数人会去搜「codex sandbox 起不来」，搜到的答案十有八九是「用包管理器装 bubblewrap（bwrap）」。

照着做没用，只会白折腾一圈。

原因在于 Codex 的沙箱根本不是同一套东西。官方《Sandbox》页写得很清楚，三个平台三套实现：

平台	沙箱实现
macOS	系统内置的 Seatbelt 框架
Windows	在 PowerShell 中使用原生 Windows 沙箱
Linux / WSL2	需要用包管理器安装 `bubblewrap`（bwrap）

也就是说，bwrap 那条路只对 Linux 和 WSL2 有意义。如果你是在 Windows 的 PowerShell 里直接跑 Codex CLI，走的是原生 Windows 沙箱这条线，Linux 的排查步骤一条都不适用。官方文档只列了三平台各自的实现，这条排查结论是由它直接推出来的。

原生 Windows 沙箱的好处是它不需要 WSL、也不需要虚拟机，官方说法是它强制一套 “bounded filesystem and network permissions”。代价是它对宿主环境有前置要求，其中最容易缺的一条就是：winget 必须可用。这是《Windows sandbox》页里写死的硬性要求。

二、怎么确认是不是这个问题

先把三件事按顺序确认掉，别跳。

第一步，确认你现在跑的是哪个版本。 特性阶段和默认行为会随版本变，用记忆里的版本号排查等于白排。

codex --version

这一步不是走过场。本机采集素材那天，同一台机器开头执行这条命令得到 codex-cli 0.131.0，十几分钟后再执行同一条命令变成了 codex-cli 0.147.0，而 which -a codex 全程只有一个可执行文件。Codex 有自更新能力（配置里 check_for_update_on_startup 默认 true），所以「昨天和今天版本号不一样」是正常的，排查任何环境问题都必须以当次实时输出为准。本文后面所有标注「本机实测」的结论，都是在 codex-cli 0.147.0（Windows 11）上取到的。

第二步，确认 winget 到底可不可用。 这一步不属于 Codex 文档的内容，只是确认那个前置条件：打开 PowerShell 敲 winget，看它是不是被识别成一条命令。如果系统提示无法识别，那这台机器上的 winget 就是不可用状态，Windows 沙箱的硬性要求没满足。

需要老实说明的是：官方文档只说了「winget 必须可用」，没有给出 winget 缺失时 Codex 具体会打出哪一条错误信息，我们也没有在一台没有 winget 的机器上复现过。所以这里只能给你判定路径，不给你伪造的错误码。看到有文章言之凿凿地贴出一个「winget 缺失专属报错」，那多半是编的。

第三步，跑 doctor 看沙箱那一行。

codex doctor --summary

它的输出按 Notes / Environment / Configuration / Updates / Connectivity / Background Server 分组，你要看的是 Configuration 组里的 sandbox 行。本机实测这一行显示的是 restricted fs + restricted network · approval OnRequest，也就是文件系统和网络两侧边界都在、审批策略是 on-request。

顺带看同一组的 config 行。本机实测有一条很有价值的结论：故意用 codex -c 'features=[unclosed' doctor --summary 传一段语法不合法的 TOML，doctor 没有崩溃退出，照常跑完，但会明确打出一行：

✗ config       config could not be loaded - Fix the reported config error, then rerun codex doctor.

所以「我明明改了配置，怎么一点效果没有」这类问题，第一步就该跑 doctor 看这一行，而不是反复重启。配置压根没加载成功，你在 windows.sandbox 上写什么都不会生效。

第四步，翻沙箱日志。 官方指明日志位于 CODEX_HOME/.sandbox/sandbox.log。本机实测 ~/.codex/ 下确实存在 .sandbox/、.sandbox-bin/、.sandbox-secrets/ 三个目录，和文档说法对得上。这个日志是判断「初始化到底卡在哪一步」的唯一一手材料，比任何猜测都靠谱。

三、官方给出的处置

《Windows sandbox》页列了初始化失败的几个常见原因：拒绝了 UAC 提示、本地用户创建被阻止、防火墙规则被限制。这三条加上 winget 不可用，基本覆盖了「起不来」的主要面。

官方给的排查顺序是固定的四步：

重启 Codex；
重试 elevated 初始化；
需要时回退到 unelevated；
发送诊断，日志在 CODEX_HOME/.sandbox/sandbox.log。

这四步之外的做法——改注册表、调组策略、动本地安全策略——官方一个字都没给，本文也不会替你编。这类操作在企业机器上一旦搞错，代价比沙箱起不来大得多。

理解第 2、3 步，得先知道 Windows 沙箱有两种模式：

模式	官方描述
`elevated`（官方标注为首选）	使用专用的低权限沙箱用户；文件系统权限边界 + 防火墙规则；需要管理员批准的初始化设置
`unelevated`（回退）	用「从当前用户派生的受限 Windows token」运行命令；基于 ACL 的文件系统边界；用环境级离线控制替代防火墙规则；保护更弱

「需要管理员批准的初始化设置」这句是重点。你在公司电脑上没有管理员权限、或者当时手快点了 UAC 的「否」，elevated 就起不来。这时候第 3 步的回退才有意义。

对应的配置键在《Configuration Reference》里：

键	类型	默认	说明
`windows.sandbox`	string	—	原生沙箱模式：`unelevated` 或 `elevated`
`windows.sandbox_private_desktop`	boolean	`true`	默认在私有桌面上运行沙箱子进程

写进 ~/.codex/config.toml 是这样：

[windows]
sandbox = "unelevated"

想先不改文件、只在这一次会话里试，用顶层的 -c。它用点号路径表示嵌套，值按 TOML 解析，解析失败就按字面字符串处理：

codex -c windows.sandbox="unelevated"

以上为按官方文档键位组合的示例，未逐项实测，以官方文档为准。本机 config.toml 里实际是 [windows] sandbox = "elevated"。

回退之前请先接受一件事：官方自己对 unelevated 写的就是「保护更弱」。它是拿不到管理员批准时的可用选项，不是等价替代品。谁跟你说切过去「一样安全」，那是他在替厂商说话，厂商自己都没这么说。

四、处置之后怎么验证

改完别急着上真活儿，跑两步验收。

验收一，再跑一次 codex doctor --summary，确认 Configuration 组的 sandbox 行有正常的边界描述（本机实测的正常形态是 restricted fs + restricted network · approval OnRequest），并且 config 行不是 ✗。

验收二，用 codex sandbox 跑一条无害命令，看边界是不是真的在。 这个子命令的位置参数官方说明就是 “Full command args to run under Windows restricted token sandbox”。本机实测过一条：在沙箱里执行

codex sandbox cmd /c "echo hi > <你的仓库路径>\__sbtest.txt"

命令返回之后去看目标文件，它不存在（ls 报 No such file or directory）。这说明默认沙箱状态下对该路径的写入没有落盘——边界确实生效。反过来，如果你这样试完文件真的躺在那儿了，那就得回头查你的沙箱模式和权限档是不是被放开了。

这里补一个容易踩的坑：--sandbox-state-disable-network 这类 --sandbox-state-* 选项是一组的，必须先有 --sandbox-state-json。本机实测单独给前者会直接报参数缺失：

error: the following required arguments were not provided:
  --sandbox-state-json <JSON>

五、什么情况说明不是这个原因

排查最怕一条道走到黑。下面这几种，方向都不在 winget 上：

看到错误 1385。 官方原文是 “Windows is denying the logon type the sandbox user needs.”，含义是沙箱用户已经创建出来了，但策略不允许它执行命令。这是登录类型策略的问题，不是 winget 缺失。官方对它给的处置就是上面那四步，没有更细的解法，别去找注册表偏方。

报的是取值非法。 本机实测 codex -s bogus-mode 的报错是：

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

这只是你把三个合法值之一拼错了，跟沙箱能不能初始化毫无关系。

你其实在 WSL2 里。 WSL2 走的是 Linux 沙箱实现，那才该去查 bubblewrap 装没装。同一台 Windows 机器上，PowerShell 里和 WSL2 里是两套机制，别混着排。

Codex 提示某个目录「writable by Everyone」。 官方说法是目录对所有人可写时 Codex 会告警，提示 Windows 权限过宽。这是在提醒你目录 ACL 有问题，不是沙箱起不来。

任务莫名其妙没网。 官方明说某些任务会故意在无出网的状态下运行，取决于权限模式；workspace-write 下是否出网由 sandbox_workspace_write.network_access 控制。先确认是不是这两条，再怀疑沙箱。

系统版本本身就不在推荐范围内。 官方给的支持矩阵是：Windows 11 推荐，较新的 Windows 10（v1809+）尽力而为（best effort），更老的 Windows 10 不推荐。如果你在一台很老的 Windows 10 上折腾，把 winget 修好也未必能解决。

最后提醒一句关于 --strict-config：它不是万能的拼写检查。本机实测执行 codex -c model_reasoning_effortt=high --strict-config exec --help，正常打印了 help，没有报未知字段错误。说明它的校验发生在真正加载配置去跑会话的时候，--help 这类不进入会话的路径不触发。别指望它在任何情况下都能替你拦住配置里的错别字。