Codex 在 Windows 上沙箱初始化失败：四个成因与官方排查顺序

2026-08-09

Codex（OpenAI Codex）在 Windows 上第一次跑起来，最容易卡住的一步不是登录，也不是配模型，而是沙箱初始化。你会发现命令能敲进去，但涉及执行的部分就是不对劲；去搜一圈，搜到的十有八九是 Linux 那套「装 bubblewrap」的答案——而那套答案在 Windows 上一个字都用不上。

先把这件事说清楚：Codex 的沙箱是分平台实现的三套东西。macOS 用系统内置的 Seatbelt 框架；Linux 和 WSL2 需要你用包管理器装 bubblewrap（bwrap）；Windows 则是在 PowerShell 里跑原生 Windows 沙箱，不需要 WSL，也不需要虚拟机。所以在 Windows 上排查沙箱问题，第一件事是确认你到底在哪个环境里——如果你是在 WSL2 的终端里敲的 codex，那你走的其实是 Linux 沙箱实现，该去查 bwrap 装没装；只有在 PowerShell 里跑的才是本文要说的原生路径。这一步分岔搞错，后面所有排查都是白费。

再交代一句标题里「四类成因」是怎么归的，免得你拿本文去和官方文档对照时觉得对不上：官方在 Windows 沙箱页里列的初始化失败常见原因只有三条——拒绝了 UAC 提示、本地用户创建被阻止、防火墙规则被限制；错误 1385 是单列在「已知问题与错误信息」里的一条，并不在那三条常见原因之内。本文把它并进来讲，是因为它在实际排查里出现的位置和那三条一样都在初始化阶段；但你心里要清楚，它在官方文档中是另一个条目，两者的口径别混。

先过两道硬门槛：winget 与系统版本

在开始怀疑权限之前，先把官方写死的两个前置条件确认掉，不然你查再久也没用。

第一，winget 必须可用。 这是官方给 Windows 沙箱标注的硬性要求。在 PowerShell 里直接敲 winget，看它能不能被识别、能不能打印出用法。如果这条命令根本不存在，先解决 winget 本身，再回来看 Codex。

第二，系统版本要在支持范围内。 官方给的支持矩阵只有三行，但这三行决定了你值不值得继续折腾：

Windows 版本	官方支持程度
Windows 11	推荐
较新的 Windows 10（v1809 及以上）	尽力而为（best effort）
更老的 Windows 10	不推荐

「尽力而为」这个措辞值得注意——它意味着在较新的 Windows 10 上初始化失败不一定是你配错了，可能就是这条路本身没被保证。真跑在这类机器上，排查投入要有个止损点。用 winver 或系统设置里的版本信息确认一下，别凭印象。

判定第一步：看 doctor 的 sandbox 那一行

Codex CLI 自带的诊断命令是排查沙箱问题最省事的入口：

codex --version
codex doctor --summary

codex doctor --summary 会按 Environment / Configuration / Updates / Connectivity 等分组打印检查项，其中 Configuration 组里有一行就叫 sandbox。在 codex-cli 0.147.0（Windows 11）上，本机这一行显示的是：

sandbox    restricted fs + restricted network · approval OnRequest

这行文本可以当作基准态来读：restricted fs 表示文件系统边界在生效，restricted network 表示网络边界在生效，后面跟的是当前的审批策略。如果你机器上这一行的内容和这个形态明显不同，或者带着 ⚠ / ✗ 符号，那说明问题确实出在沙箱这一层，可以继续往下查。

顺带记住 doctor 的两个细节。一是它结尾会打一行统计（形如 17 ok · 1 idle · 1 notes · 0 warn · 0 fail），先看有没有 fail，别一上来逐行读。二是 codex doctor --json 的官方说明是 “Emit a redacted machine-readable report”——是脱敏的，所以真要把诊断结果贴给别人或提到工单里，用 --json 这份比截屏安全。

另外先做一个反向排除：如果 doctor 输出里 config 这一项显示的是（本机实测该失败行出现在 Notes 区）

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

那你现在遇到的根本不是沙箱问题，而是 config.toml 压根没加载成功。这一条在 codex-cli 0.147.0（Windows 11）上是实测过的：故意给 -c 传一段语法不合法的 TOML，doctor 命令并不会崩溃退出，照样跑完全程，只是在结果里明确告诉你配置没加载上。所以「我改了配置但沙箱行为没变」这类现象，第一步永远是跑 doctor 看这一行，而不是继续改配置。

成因一：UAC 提示被拒绝

现象：初始化在弹出用户账户控制（UAC）提示之后中断，之后再跑也起不来。

为什么会这样：Windows 沙箱的两种模式里，官方标注为首选的是 elevated。它会使用一个专用的低权限沙箱用户，靠文件系统权限边界加防火墙规则来划界——代价就是它的初始化设置需要管理员批准。你在那个提示上点了「否」，或者提示一闪而过被你忽略掉了，初始化就停在那儿。

怎么确认：看 ~/.codex/config.toml 里 [windows] 段的 sandbox 取值。在 codex-cli 0.147.0（Windows 11）上，本机这项是 sandbox = "elevated"。如果你的配置也是 elevated，而你确实没给过管理员批准，那这条基本就对上了。

官方给的处置：官方对 Windows 沙箱初始化失败给出的排查顺序是固定的四步——① 重启 Codex；② 重试 elevated 初始化；③ 需要时回退到 unelevated；④ 发送诊断，日志位于 CODEX_HOME/.sandbox/sandbox.log。UAC 被拒这一类，走的就是①和②：重启 Codex，让初始化重新触发，这次在提示上给批准。

处置后怎么验证：重新跑 codex doctor --summary，确认 sandbox 那一行回到带 restricted fs + restricted network 的形态。

成因二：本地用户创建被阻止

现象：给了管理员批准，UAC 也过了，elevated 初始化还是不成。

为什么会这样：elevated 模式的核心就是那个专用的低权限沙箱用户。托管设备上，本地账户的创建往往是被环境策略拦住的——批准 UAC 和「允许建一个本地用户」是两回事，前者过了不代表后者能过。

怎么确认：这一步别靠猜，去看日志。官方指明的日志路径是 CODEX_HOME/.sandbox/sandbox.log，默认即 ~/.codex/.sandbox/sandbox.log。在 codex-cli 0.147.0（Windows 11）上，本机 ~/.codex/ 下确实存在 .sandbox/、.sandbox-bin/、.sandbox-secrets/ 三个目录，路径是对得上的。

官方给的处置：走四步里的第③步——回退到 unelevated。这是官方明确给出的回退路径，适用于「拿不到管理员批准」的场景。配置键是 windows.sandbox：

[windows]
sandbox = "unelevated"

也可以用命令行覆盖当次运行（-c 用点号路径表示嵌套）：

codex -c windows.sandbox=unelevated

以上为按官方文档键位组合的示例，未逐项实测，以官方文档为准。

这里必须把代价说清楚：unelevated 是回退方案，不是等价方案。它用「从当前用户派生的受限 Windows token」来跑命令，文件系统边界基于 ACL，防火墙规则被换成了环境级的离线控制。官方自己对它的定性就是保护更弱。所以它的适用场景是「暂时拿不到管理员批准，先把活干起来」，不是「反正都能跑，就用这个吧」。别把这层区别抹掉。

处置后怎么验证：跑 codex doctor --summary 看 sandbox 行，再用 codex sandbox 子命令跑一条无害命令确认边界确实在。这个子命令的位置参数官方说明就是 “Full command args to run under Windows restricted token sandbox”。在 codex-cli 0.147.0（Windows 11）上实测过一个很直观的验证法：在沙箱里往仓库路径写一个文件，命令返回后目标文件并不存在——写入没有落盘，说明文件系统边界是真的在起作用。

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

跑完去看那个文件在不在。不在，就说明边界生效了。

成因三：防火墙规则被限制

现象：初始化流程走到网络这一环卡住，或者沙箱起来了但网络行为跟预期对不上。

为什么会这样：elevated 模式的边界由两部分组成——文件系统权限边界加防火墙规则。防火墙规则那一半如果被环境策略限制住，初始化自然不完整。

怎么确认：还是查 ~/.codex/.sandbox/sandbox.log。另外这里有个官方专门提示过的易误判点：某些任务会故意在无出网的状态下运行，具体取决于权限模式。也就是说，「沙箱里连不上网」本身不必然是故障，可能就是设计如此。判断之前先分清你观察到的是「初始化没完成」还是「初始化完成了但这次任务本来就不出网」。

官方给的处置：仍然是那四步。防火墙这一路如果在 elevated 下过不去，第③步回退 unelevated 是官方给的路径——它用环境级离线控制替代防火墙规则，绕开了这个依赖，但同样要接受「保护更弱」这个前提。

处置后怎么验证：codex doctor --summary 的 sandbox 行里 restricted network 是否还在，是最直接的观察点。想更细地控制网络，官方侧的键是 sandbox_workspace_write.network_access（控制 workspace-write 模式下是否出网），域名级控制走 permissions.<name>.network.domains.<pattern> 的 allow / deny（支持通配）。还有一个 features.network_proxy——注意它处于 experimental 阶段，在 codex-cli 0.147.0（Windows 11）上本机 codex features list 观测到它的阶段是 experimental、生效值为 false，不要当稳定功能用。

成因四：错误 1385

现象：初始化过程报出错误 1385。

这条的含义官方写得很明确，原文是 “Windows is denying the logon type the sandbox user needs.”——沙箱用户已经创建出来了，但策略不允许它以所需的登录类型执行命令。

这一点值得单独强调，因为它决定了你该往哪儿使劲：1385 不是「用户没建成」，而是「用户建成了但登录被拒」。所以你去反复重试创建、去检查账户是不是存在，方向就偏了。它和成因二是两个不同的阶段。

官方给的处置：这里要如实说清楚——官方对 1385 只给出了含义说明（沙箱用户已经创建、登录类型被拒），截至 2026-08-09，没有给出针对 1385 的专门修复方案。你能参考的只有 Windows 沙箱页单独列出的那套通用四步排查顺序：重启 Codex、重试 elevated 初始化、需要时回退 unelevated、发送诊断（日志在 CODEX_HOME/.sandbox/sandbox.log）。注意这四步是官方针对「初始化失败」给的通用顺序，并不是官方为 1385 单开的处方，别把它当成「照着走就能解决 1385」。官方也没有给出针对 1385 的注册表或组策略层面的具体改法，本文同样不会替它编一个。你在别处看到的那类「改某个策略项就好了」的说法，请自行判断来源，至少它不在官方文档里。

在受管控的公司设备上，1385 更可能是 IT 策略的既定结果而不是你机器的故障。这种情况下务实的做法是：先按第③步回退到 unelevated 把工作接上，同时把 sandbox.log 交给管理员去看登录类型这一层，而不是自己在本机反复试。

还有一类告警：目录对所有人可写

这一条不算初始化失败，但排查时经常撞上：如果某个目录是 “writable by Everyone”（对所有人可写），Codex 会给出告警，提示 Windows 权限过宽。

它提示的是你机器上目录 ACL 本身太松，而不是 Codex 出了问题。基于 ACL 的文件系统边界，前提是 ACL 本身有意义；一个所有人都能写的目录，画不出有效边界。看到这个告警，该处理的是那个目录的权限，不是去调 Codex 的配置。

什么情况说明不是沙箱初始化的问题

排查最怕一条道走到黑，这里列几条反向信号：

你在 WSL2 里跑：那走的是 Linux 沙箱实现，该查 bubblewrap 装没装，本文这套 Windows 原生路径完全不适用。macOS 那边是 Seatbelt，又是第三套，同样别混。
doctor 的 config 行报了 config could not be loaded：先修配置。配置没加载成功的情况下，你对沙箱做的任何配置改动都不会生效，改到天亮也没用。
codex login status 不正常：登录和沙箱是两条独立链路。在 codex-cli 0.147.0（Windows 11）上，本机 codex login status 输出的是一行 Logged in using ChatGPT。凭据这一层没通，表现出来的症状可能很像「跑不起来」，但跟沙箱无关。
你以为改审批策略能绕过沙箱：这是最常见的一个误解。approval_policy 的三档 untrusted / on-request / never 改变的是要不要问你，不是边界本身。never 的官方释义是「从不询问，执行失败直接回传模型」——沙箱边界照样在，失败照样失败。真正撤掉边界的是 danger-full-access 模式，或者 --dangerously-bypass-approvals-and-sandbox（官方对后者的原文措辞是 “EXTREMELY DANGEROUS. Intended solely for running in environments that are externally sandboxed”）。用它去「解决」初始化失败，等于把门拆了说门锁修好了。
版本号跟你记忆里的对不上：这很正常。在同一台机器上采集这批数据时，开头执行 codex --version 拿到的是 codex-cli 0.131.0，十几分钟后再执行同一命令得到的是 codex-cli 0.147.0，而 which -a codex 全程只有一个可执行文件。Codex 具备自更新能力，所以排查任何版本相关的问题，都要以当次 codex --version 的实时输出为准，别用记忆里的版本号去对照文档。

一张收口的顺序表

把上面的东西压成一条执行链，遇到 Windows 沙箱初始化失败就按这个顺序走：

确认自己在 PowerShell 而不是 WSL2；
确认 winget 可用、系统版本在支持矩阵内；
跑 codex --version 和 codex doctor --summary，先看 config 行有没有 fail，再看 sandbox 行的形态；
按官方四步走：重启 Codex → 重试 elevated 初始化 → 需要时回退 unelevated（接受「保护更弱」）→ 发送诊断，日志在 CODEX_HOME/.sandbox/sandbox.log；
处置完用 codex doctor --summary 复核 sandbox 行，再用 codex sandbox 跑一条无害写入命令，确认文件确实没落盘；
如果日志指向错误 1385，把日志交给能改策略的人，别在本机死磕。

这套顺序不长，但每一步都对应一个明确的判断点。Windows 这边的沙箱机制和 Linux 差得远，能把「先分平台、再看 doctor、最后读 sandbox.log」这三层顺序固化下来，大部分时间就不会浪费在搜错方向的答案上了。