这周二（2026年10月8日）上午，我原本计划用Codex把那个长期搁置的模块重构收尾，结果刚跑到第二轮任务，工作流就卡死了。窗口里先是弹出沙箱初始化失败的报错，然后整个Codex会话直接中断，重试、重启、换任务都没有用，前后折腾了将近半天才恢复。回头整理这篇复盘时，我意识到这类“沙箱起不来”的问题在Windows平台上远比想象中常见，而且大多数人遇到后的第一反应都是瞎重启，浪费大量时间。所以把这次故障从现象到根因、从排查到修复的完整过程记录下来，给同样在Windows上跑Codex或类似AI编程代理的人做个参考。
先说结论：这次故障的根子不在Codex本身，而在它依赖的WSL2虚拟磁盘文件膨胀到了失控状态，把磁盘空间和沙箱后端的启动路径全部堵死。你可能觉得虚拟磁盘膨胀是个慢变量，不至于突然引发故障，但实际连坐效应比想象中猛得多。下面对这次复盘做详细的拆解。
1. 故障背景：Codex在Windows上的沙箱执行机制
1.1 沙箱在Codex工作流里扮演什么角色
Codex这类AI编程代理，核心工作方式是“理解任务、改代码、执行命令、观察结果、继续迭代”。这个闭环里最危险的一环就是“执行命令”。因为模型生成的命令不可预知，也许是读取某个目录，也许是安装依赖，也许是直接动全局配置，如果没有隔离机制，一次失控的命令就能把整个开发环境搅成一锅粥。
沙箱的作用就是把这一步圈起来——Codex所有需要执行的操作都被放进一个独立的环境里，这个环境有独立的文件系统、独立的进程空间、独立的网络策略，任务结束就销毁。好处很明显：模型犯错了不会波及宿主机，恶意命令被拦截，多任务并行时互不干扰。缺点是沙箱本身是一个复杂的运行时系统，它挂掉的时候，整个Codex工作流也就瘫了。
我在Windows上用的是Codex的沙箱模式，它依赖的是WSL2加容器化的组合方案。简单理解，WSL2提供一个轻量的Linux虚拟机作为底层运行环境，在这个环境里再跑容器，每个Codex任务对应一个临时容器。执行命令、跑测试、检查语法都在容器内完成。
1.2 Windows沙箱技术栈的依赖链条
Windows平台跑Codex沙箱，涉及的技术栈比Linux或macOS要复杂一些。后端依赖链条大致是：
Codex客户端 -> Docker Engine（容器管理） -> WSL2（Linux虚拟机） -> Hyper-V虚拟化平台 -> 物理CPU虚拟化能力 + 磁盘资源这条链路上的每一环，都必须在正常工作状态。哪一环出问题都能导致“沙箱初始化失败”，但报错往往是最后一段才露出来——你只看到Codex告诉你沙箱起不来，事实上后面可能断了不止一处。
除此之外，Windows沙箱还有一个容易被忽视的依赖：临时目录和用户配置文件路径。Codex在Windows上初始化沙箱时，会向WSL2的某个发行版写入大量文件，包括构建镜像的缓存、临时容器层、项目文件的挂载副本。如果这些目标路径所在的分区没有足够空间，初始化过程会直接失败。
另一个值得关注的点是Windows更新的影响。Windows功能更新往往会调整虚拟化相关的服务设置、Hyper-V组件的启用状态、WSL内核的注册配置。如果更新刚好改动了这些配置，沙箱就可能出现问题。我在这次排查过程中就发现，这台机器最近确实安装过一轮系统更新，虽然不是直接根因，但确实给排查增加了很多干扰项。
2. 故障现象与第一反应
2.1 最初看到的报错和表现
10月8日当天，我启动Codex后先让它继续之前的一个任务，大概两分钟后它开始执行一段需要运行测试的命令，紧接着Chat界面里出现了这样一段报错：
Sandbox initialization failed: cannot connect to sandbox backend. Task aborted. Please check your sandbox service and retry.这个报错信息本身其实很泛，只说“连不上沙箱后端”，没有更多上下文。我注意到Codex的任务进程其实是正常启动的，读文件、改代码都没问题，问题只出在“需要真正执行命令”那一瞬间。也就是说，前端逻辑是好的，后端执行通道断了。
随后我第一时间尝试直接手动跑到沙箱环境里看看能不能执行命令，发现WSL里也进不去，或者进去了之后非常卡。这时候基本可以确定问题在沙箱后端这一层，而不是Codex自身。
系统事件日志里也有一些线索。打开事件查看器，在“系统”日志下能看到多条来自Hyper-V和WSL服务的警告，其中有一条明确指出“虚拟磁盘空间不足，无法完成操作”。我承认，当时我瞟了一眼没当回事，只想着先重启试试再说——这是这次复盘里最值得反省的一个操作习惯。
2.2 快速恢复尝试为何全部失败
遇到这种故障，我通常的应急动作是三个：重启Codex客户端、重启Docker Desktop、重启整机。这次三个全试了，结果一个都没奏效。
先重启Codex客户端，重新发起任务，报错原样出现。这说明不是客户端内部的状态错乱。接着重启Docker Desktop，它启动后自己都报“引擎异常”，但没给出进一步提示。到这里已经能判断问题在Docker引擎所依赖的下层环境。最后重启整机，开机后满怀期待再试，依然失败——这就彻底排除了临时性故障，说明某个持久化状态已经损坏或不可用。
连重启整机都没解决，往往意味着问题出在磁盘或虚拟化配置层面，而不是简单的服务状态。那会儿我才冷静下来，开始按链条逐层排查。
结合这次经历，我建议你遇到类似问题先别急着重启——这不是说重启无用，而是你要在重启之前先收集一轮状态信息。至少要看一眼磁盘剩余空间、服务状态、事件日志这三个维度的数据再动手。否则重启完了信息全丢了，只能干瞪眼。
3. 逐层排查：从Codex日志到根因定位
3.1 第一层：追踪Codex自身日志文件
排查任何故障，第一步永远是从离故障最近的日志入手。Codex在Windows上的日志默认写在用户目录下的一个隐藏目录里，具体位置会因安装方式和版本有所不同，最常出现在：
C:\Users\<用户名>\AppData\Local\Codex\logs\我打开当天最新的日志文件，看到里面的错误信息比界面报错详细了一截。日志里反复出现如下几行：
[error] failed to create sandbox: error during connect: Post "http://localhost:2375/...": dial tcp: connect: connection refused [error] sandbox backend not ready after 120s [info] retry sandbox init, attempt 2... [error] docker engine not reachable, check docker service status这几行日志的关键意义在于：把问题指向了Docker引擎本身。第一行报错是Codex尝试连接Docker引擎的API端口（默认2375），连接被拒绝，说明引擎没有在监听；第二行显示它等了120秒还没就绪；第三行是重试记录；第四行直接给出了排查方向。
这里有个Windows平台特有的细节值得提一下：Codex在Windows上连接Docker引擎时，通常不会直接暴露2375端口，而是通过命名管道（named pipe）通信。日志里的“localhost:2375”是编程层面的代理地址，实际连接路径更复杂。但不管怎样，docker engine not reachable已经足够把矛头指向引擎了。
我随手跑了一下docker info命令，输出却是连接失败。这就很奇怪了——Docker Desktop界面明明显示启动了，怎么引擎连不上？结合之前判断，问题基本确定在了Docker引擎所依赖的WSL2层。
3.2 第二层：检查虚拟化能力和WSL2状态
既然Docker引擎连不上，下一步就是检查WSL2的状态。在Windows上，Docker Desktop默认使用WSL2作为后端，WSL2起不来，Docker引擎就算安装得再好也跑不起来。
先看WSL的整体状态：
wsl --status输出显示“默认版本：2”，这说明WSL2本身是启用的。接着再列出所有发行版的状态：
wsl --list --verbose输出如下：
NAME STATE VERSION * Ubuntu Stopped 2所有发行版都处于停止状态。这本身不算异常——如果任务没跑，发行版就是停止的。关键是要尝试启动它，于是继续执行：
wsl ~结果终端卡了很久，最后返回一个非常坑人的提示：这个发行版没有可用的、有效的配置文件，或者虚拟磁盘存在问题。我尝试了几次都是类似结果，偶尔会直接返回“系统找不到指定的文件”之类的通用错误。
与此同时，我检查了机器是否具备虚拟化能力：
systeminfo输出里“Hyper-V要求”一栏显示“已检测到虚拟机监控程序。将不显示Hyper-V所需的功能。”——这至少说明虚拟化本身是开着的，Hyper-V组件也在工作。那问题就只剩下磁盘这一层了。
这个时候我突然想起事件日志里那条“虚拟磁盘空间不足”的警告，于是直接查看磁盘空间：
Get-PSDrive C结果让我倒吸一口凉气：C盘剩余空间已经从几天前的几十GB掉到了不到2GB。系统盘被塞满了，所有依赖写入的操作都会失败。
3.3 第三层：找到虚拟磁盘膨胀的元凶
系统盘空间满了，那么什么在占空间？打开资源管理器后，我一眼看到用户目录下面AppData\Local\Packages里的某个目录体积惊人，对应的正是一个WSL发行版的LocalState文件夹。
这个文件夹里放的就是WSL2虚拟机的磁盘镜像文件ext4.vhdx。属性显示整个文件接近230GB，而之前明明记得这台机器的整个C盘也就500多GB，一个虚拟磁盘文件就占了近一半。虚拟磁盘膨胀到这种程度，物理分区剩余空间自然被挤干。
ext4.vhdx是WSL2发行版使用的虚拟磁盘文件，它的工作机制是动态扩展——文件本身会随着写入逐渐变大，但在正常使用中只会膨胀不会自动收缩。日常开发时，Docker拉镜像、容器写临时数据、编译缓存、日志堆积，这些内容都写在虚拟磁盘里，写了之后即使删除，虚拟磁盘文件也不会把空间还给物理分区。
我进到发行版里看了看更直观的情况。启动WSL后执行：
df -h /显示根文件系统用了不到30GB，但物理磁盘上的ext4.vhdx已经有230GB——这中间差了200GB，全是动态扩展加删除后留下的“空洞”。在虚拟机镜像的世界里，这种空洞就是磁盘碎片，文件不会自动回收。
到这里，根因已经很清楚了：WSL2虚拟磁盘失控膨胀，把系统盘剩余空间压到极低，导致Docker引擎、WSL进程、沙箱服务全部无法写入磁盘，沙箱初始化自然就失败了。
4. 根因确认与修复全流程
4.1 虚拟磁盘膨胀为何会连坐沙箱后端
按常理说，虚拟磁盘膨胀是个渐进过程，它不一定马上导致故障。但问题在于它达到临界点后引发的连锁反应是毁灭性的。
Codex初始化沙箱的过程涉及多个写操作：启动WSL虚拟机时需要写入会话配置、启动Docker引擎时需要写日志和状态文件、构建容器镜像时需要大量临时写入、挂载项目目录时还需要为文件系统准备元数据空间。任何一个环节因为磁盘满而失败，整个初始化链路都会中止。
而且Windows对系统盘剩余空间的保护逻辑也会雪上加霜。当系统盘空间低于一定阈值后，Windows会主动限制一些服务的行为，包括暂停一些后台虚拟化组件的写操作。这就导致即便你重启、重试，只要磁盘空间没有释放出来，所有依赖写盘的操作都会持续失败。
这次的情况就是如此：C盘剩余不到2GB时，WSL2已经无法正常启动虚拟磁盘，Docker引擎因此在启动过程中超时挂掉，Codex也就压根连接不到沙箱后端。三个故障现象，一个根因。
4.2 清理与压缩虚拟磁盘的完整操作
修复思路分两步走：先释放系统盘空间让WSL能启动，再对ext4.vhdx做压缩处理，从根本上把那个230GB的大文件缩小。
首先释放空间。我直接用了Windows自带的磁盘清理工具，选择清理系统文件，把Windows更新缓存、临时文件、旧日志清了一轮，大概释放出25GB左右的可用空间。这一步虽然不解决根本问题，但为后续操作留出了喘息空间。
接着关闭所有WSL实例，确保虚拟磁盘没有被占用：
wsl --shutdown然后通过diskpart对虚拟磁盘文件进行压缩。先挂载这个vhdx，再执行compact操作：
diskpart进入diskpart交互界面后依次执行：
select vdisk file="C:\Users\<用户名>\AppData\Local\Packages\<发行版包名>\LocalState\ext4.vhdx" attach vdisk readonly compact vdisk detach vdisk exit这里有一个非常关键的细节：compact vdisk之前必须以只读方式附着虚拟磁盘（readonly模式）。如果直接以读写方式附着再压缩，diskpart会拒绝执行，报“虚拟磁盘正在使用中”之类的错误。
压缩过程其实就是遍历虚拟磁盘内部的数据块，把那些标为空闲的数据块从文件里真正删除掉。整个过程跑了几分钟，完成后再看ext4.vhdx，文件从230GB缩减到了35GB左右——和发行版内部实际使用量基本一致了。
如果你用的Windows版本较新，WSL还支持直接设置发行版为稀疏模式（sparse），开启后虚拟磁盘会自动回收空闲空间，不需要定期手动压缩。操作如下：
wsl --manage Ubuntu --set-sparse true这个命令能从根本上缓解vhdx膨胀问题，但是在开启之前建议先确认发行版版本支持，因为旧版WSL不一定兼容。
4.3 重启后端链路并验证沙箱可用性
压缩完虚拟磁盘后，我又确认了C盘剩余空间恢复到了60GB以上，这才依次启动服务链。
先启动WSL发行版，确认能正常进入：
wsl ~进入后跑了一个简单的命令确认基本功能正常，然后退出。接着启动Docker Desktop，等到它的状态变为Running后，再验证Docker引擎是否可用：
docker info docker run hello-worldhello-world镜像能正常拉取并运行，说明Docker引擎已经恢复。到这里，后端链路基本修复。
最后回到Codex客户端本身，重新发起一个简单任务，让它执行一条无害命令测试沙箱。这次沙箱初始化顺利完成，任务正常跑完，日志里也不再出现engine not reachable之类的错误。为了稳妥，我又跑了一个原本卡住的中等规模任务（需要安装依赖、执行测试），沙箱状态下全部通过，才算确认故障彻底解决。
5. 常见问题与排查技巧实录
5.1 故障速查表
这次复盘过程中，我把几个常见的“沙箱起不来”现象和排查方向整理成了速查表，方便以后对照处理。
| 现象 | 排查方向 | 常见根因 | 解决方法 |
|---|---|---|---|
| Codex报sandbox initialization failed | 查看Codex日志，确认CNI后端是否可达 | Docker引擎未运行或连不上 | 依次检查Docker Desktop和WSL状态 |
| Docker Desktop显示Running但引擎不可达 | 运行docker info确认 | WSL2发行版异常或虚拟磁盘损坏 | 使用wsl --shutdown重启WSL |
| WSL发行版无法启动 | 检查事件日志和磁盘空间 | vhdx磁盘空间耗尽或元数据损坏 | 清理磁盘、压缩vhdx |
| 系统盘空间持续走低 | 查看ext4.vhdx文件体积 | 虚拟磁盘动态膨胀未回收 | 定期compact或开启sparse模式 |
| 系统更新后沙箱突然异常 | 检查Hyper-V和WSL服务状态 | 更新改变了虚拟化相关配置 | 重新启用相关Windows功能后重启 |
这张表对Windows平台的兼容性和诊断顺序尤其有用。每次故障都按“应用日志 -> 引擎状态 -> 虚拟化/磁盘”的顺序来排查，基本能快速收敛问题。
5.2 几条独家的避坑经验
这次排障踩了不少坑，有几个经验值得单独拿出来说。
第一，别在磁盘空间边缘做开发。这句话听起来像废话，但很多人（包括我）总觉得C盘剩个5GB、10GB就够用了。可WSL2的虚拟磁盘是动态增长的，Docker镜像拉几个大的、项目跑几轮、日志堆一堆，几十GB很快就没了。建议给系统盘预留至少30GB的余量，同时把Docker的镜像存储目录、WSL发行版的存放目录迁移到数据盘，避免和系统盘抢空间。
第二，定期给WSL2虚拟磁盘瘦身。我现在的习惯是每两周执行一次压缩操作，或者直接开启sparse模式。如果你不想记复杂命令，也可以直接用WSL自带的配置项限制虚拟磁盘大小。在用户目录下建一个.wslconfig文件，里面可以这样配置：
[wsl2] memory=8GB processors=4 swap=4GB虽然这里不能直接限制vhdx上限，但限制内存和处理器数量能减少日志和交换文件的写入规模，间接延缓磁盘膨胀。更重要的是能在日常使用中保持系统性能稳定。
第三，Windows更新后最好检查一遍虚拟化状态。这台机器装了最近的系统更新之后，我并没有留意Hyper-V和WSL相关的服务配置有没有被改。这次排障时花了不少时间排查这个干扰项，才判断出更新并不是根因。建议你在每次系统大更新后快速跑一下wsl --status和docker info，确认后端链路没被影响。
第四，沙箱故障不等于Codex故障。如果你遇到类似报错，先别急着向Codex抱怨，也别一上来就重装客户端。花十分钟追踪一下从Codex到沙箱后端的链路，往往问题在WSL或Docker这一层。毕竟沙箱再复杂，也只是建立在系统虚拟化能力之上的一个服务，底层不稳，上层一定跟着崩。
我个人在实际操作中最大的体会是：Windows平台的沙箱工具链有一个“木桶效应”——Hyper-V、WSL2、Docker引擎、磁盘空间、Codex客户端，每一块都得同时在线，才能让沙箱正常工作。任何一块短板都会让整个工作流中断，而且报错往往不会把你直接指向最短的那块板。所以与其在等到故障发生后再去逐个排查，不如平时就把磁盘监控、vhdx瘦身、系统更新检查这三件事做扎实。做完这些，Codex在Windows上的沙箱体验会稳定很多，至少不会再因为一个230GB的虚拟磁盘文件而全线崩溃。
