10月8号晚上我手头一个Codex驱动的批处理任务卡在了Windows沙箱上连续四次启动全部失败前后折腾了四个多小时才把问题彻底解决。这不是一次简单的环境报错而是容器沙箱的任务锚定机制、镜像层完整性、资源预算三个环节同时出了岔子任何一个单点都很难直接看出全貌。这篇文章就是那次故障的完整复盘从Codex在Windows下是怎么跑沙箱的、故障现场是什么样、我是怎么一层层定位到根的到最终怎么修复、以后怎么预防全部摊开讲。如果你也在Windows上用Codex或其他依赖容器化沙箱的编码智能体这篇文章应该能帮你少走几趟弯路。1. 先搞清楚Codex在Windows上到底是怎么跑沙箱的1.1 为什么编码智能体非要一个沙箱不可Codex这类编码智能体的工作模式是理解你的需求自己拆解任务然后执行工具调用去读写文件、跑命令、构建项目。这个过程中模型自己生成的代码是不可完全信任的——不是它故意使坏而是它对你环境的理解可能出错跑出一条rm误删、改错配置、疯狂占内存的命令完全有可能。所以沙箱的意义就是在系统和你之间加一层可控的隔离墙。沙箱至少要做四件事文件系统隔离让智能体只能碰挂载进去的目录网络策略限制默认断网或只允许白名单地址资源配额限制CPU、内存、磁盘用量防止失控生命周期管理任务结束后容器自动销毁不残留进程。1.2 Windows下三种沙箱方案的取舍Windows上要给Codex做沙箱常见的有三条路。第一条是Windows自带的应用沙箱隔离级别高但它每次启动都要重置系统状态无法持久化对Codex这种需要跨会话保留工作区的场景来说基本没法用。第二条是WSL2里的Linux容器轻量、启动快但WSL2本身不是一个面向单进程隔离的运行时更像是一个轻量虚拟机上的进程环境隔离性有限。第三条就是Docker Desktop的容器沙箱把智能体的工具调用跑在独立容器里既有隔离又支持持久化还能用Docker的成熟生态。Codex默认采用的正是第三种方案宿主Windows上的Codex CLI负责调度所有工具调用通过API转发到WSL2后端的Docker运行时在容器里执行。整个链路是宿主进程 → WSL2 → Docker守护进程 → 沙箱容器 → 工作区挂载目录。理解了这条链路你就会发现所谓“Codex沙箱故障”检查面其实横跨Windows应用层、WSL2虚拟化层、Docker存储层三块。这也是为什么这类问题排查起来特别容易晕。1.3 沙箱生命周期里的两个关键机制和这次故障直接相关的是两个平时不太起眼的机制。第一个是任务锚定。每次会话创建时Codex会生成一个会话ID并将它映射到一个固定名字的容器比如codex-sbx-a8f3c2d1。后续所有工具调用都发往这个容器同时容器名和会话元数据会被写入宿主机上的状态文件用于会话恢复。第二个是恢复机制。当任务中断或CLI重启后Codex会尝试读取最近的会话元数据找到对应容器检查它是否还在运行然后决定是恢复还是重建。这两个机制本身逻辑不复杂但它们都依赖一个前提容器镜像和状态文件是完好一致的。镜像层一旦损坏或者状态文件和实际容器对不上恢复逻辑就会走到一个非常尴尬的中间状态——既没法恢复旧会话也建不了新容器。2. 故障现场不是简单启动失败而是连环告警2.1 故障现象记录那天晚上我跑的是一批代码重构任务某个跨平台系统迁移需要Codex在沙箱里连续处理十几个模块。任务运行到第三个模块时Codex突然报错退出。我记录了当时看到的所有关键现象。第一个现象是启动即失败。重新运行Codex时CLI直接报Failed to start sandbox: rpc error: code Unavailable连容器都没拉起来。第二个现象是容器启动后立刻退出。偶尔一次能启动成功但几秒钟后容器就被杀掉日志里只有一句Container exited with code 137。第三个现象是工作区文件系统异常挂载目录内部分文件变成只读个别目录即使有管理员权限也无法读取。第四个现象是会话恢复变成空白。Codex的--resume选项读不到之前的任务记录状态文件存在但内容与当前容器完全不匹配。这四个现象如果单独看前两个像资源问题第三个像文件系统问题第四个像应用层问题。但它们同时出现就没法用单点故障解释了。2.2 故障时间线我完整记录了从发现问题到最终恢复的全过程这里按时间线还原。16:40第三个模块重构任务开始Codex正常进入沙箱。16:58任务日志中断沙箱容器被系统杀掉退出码137。17:05第一次尝试重启Codex报rpc error: Unavailable。17:10重启Docker Desktop等待约三分钟后容器可启动但会话内容全部丢失。17:30把任务切到新会话重新跑约二十分钟后再次被杀死现象与第一次相同。18:10检查事件日志发现之前有强制关机记录是在我昨晚下班时误触了电源键系统没有正常走完关机流程。20:10执行完整清理流程WSL2冷重启 孤儿容器清理 镜像重建服务恢复正常。2.3 影响评估这次故障的直接影响不只是那一个晚上的任务中断。首先是整个批次的任务回退到了第三个模块的起点前面两个模块虽然已生成代码但会话状态丢失导致无法继续增量处理。其次是工作区里大约3GB的中间产物因为容器重建被清掉而这些产物理论上不应该依赖容器生存期。最后是恢复后我发现Codex的监控统计里出现了内存与文件系统异常的告警说明异常状态实际上在故障前就已经有苗头只是被我忽略了。3. 排查全过程从应用层一路挖到存储层3.1 第一轮先看应用层日志故障发生后我的第一反应是查Codex自己的日志。在Windows上Codex的日志通常在%USERPROFILE%\.codex\log\下面打开当天的日志文件里面反复出现的错误有两类一类是容器RPC连接断开时间点大概在进程被杀之前另一类是状态文件读写失败具体报错是failed to lock state file: resource temporarily unavailable。这两个信息有一定价值RPC断开说明容器进程先于CLI退出状态文件报锁错误说明有另一个进程还占着状态文件的锁——也就是说有一个残留的Codex守护进程在后台没有退出。我在任务管理器里确实找到了几个残留的codex serve进程强制结束后重新运行情况好转了一点点CLI能发命令了但容器依然是启动后秒挂。到这里可以初步排除应用层独占锁的问题继续往容器层看。3.2 第二轮检查容器事件和资源状态我把排查重心转向Docker。先跑docker events --since 30m看到的关键事件是die和oom容器是被OOM杀手杀掉的。再看容器配置docker inspect返回的HostConfig.Memory显示内存限制是2GBMemorySwap是1GB。这个配置很可疑按Linux的cgroup规则SWAP是“内存换页上限”而Docker Desktop在WSL2后端里的SWAP实际上由WSL2全局配置决定容器层面的MemorySwap如果设得比WSL2可用的交换空间还大就会产生一个虚假的“超额”内存预算进程一跑到高位就容易被判定为OOM。同时我注意到了一个更关键的数字WSL2配置里.wslconfig的memory被设置为4GB但docker desktop setting里分配给WSL2的内存却按“动态分配”处理。也就是说容器请求2GB内存 1GB交换而WSL2本身可用内存不满4GBDocker Desktop还要占掉一部分剩余内存留给容器cgroup的实际配额可能不足2GB。这种情况下容器内的高内存负载会被cgroup的OOM killer杀掉退出码137表现形式就是启动后秒挂。3.3 第三轮检查镜像层完整性解决内存参数后又试了一次容器没有秒挂但工作区里依然有只读文件。我意识到这可能不是资源问题而是文件系统层面的问题。去查容器镜像的状态docker image inspect显示镜像的rootfs有多个层其中一层的diff_id校验和异常但这个异常并没有触发Docker的自动恢复机制——它的完整性信息是滞后更新的。再查docker system df发现镜像空间占用异常大同一版本沙箱镜像竟然有六个历史副本其中一个副本处于“悬挂”状态没有标签但没有被清理。这种悬挂层在正常卸载更新时会被自动清理但如果宿主机经历过程序异常终止图层读写的元数据就来不及更新导致悬挂层残留。而Codex的容器镜像在启动时会去读取这些残留层的元数据来组装rootfs一旦某层的元数据不一致轻则文件只读重则启动失败。3.4 第四轮WSL2全局状态检查到这里已经比较明确了但我还是想确认WSL2本身有没有补刀。执行wsl --status输出显示Default Distribution: docker-desktop正常运行。但wsl --shutdown之后重新启动Docker Desktop界面上提示需要重置网络组件说明WSL2的虚拟网络交换机状态也异常过。结合昨晚的强制关机记录我判断这就是整个事件的起点强制关机导致WSL2虚拟磁盘和Docker存储目录处于未正常卸载状态再叠加Docker Desktop动态内存分配本身的资源竞争最终引爆了后续的连环故障。4. 根因分析三个问题纠缠在一起的完整链条4.1 根因之一镜像层损坏叠加悬挂层残留究其根源一切始于昨晚那次坏关机。Windows在强制关机后不会对WSL2的虚拟磁盘文件ext4.vhdx执行优雅的fsck流程导致Docker的overlay2存储驱动中的图层元数据出现不一致。这种不一致平时不会直接暴露因为系统会尝试自动修复但仓库里残留的悬挂层会干扰修复流程它把破损层误当成“正在使用”的层导致Docker拒绝清理镜像启动时读取到的层信息又是旧的。如果没有6个历史副本也许不会这么严重。正是因为我之前多次更新镜像后没有主动清理旧镜像悬挂层数量积累到了一个临界点最终有一个旧层正好位于rootfs的关键路径上才导致workload文件只读和部分工具调用失败。4.2 根因之二任务锚定机制与容器名冲突Codex的任务锚定机制会按会话ID生成固定容器名比如codex-sbx-a8f3c2d1。正常情况下一个会话对应一个容器任务结束后容器被销毁名字释放。但这次在强制关机后Docker守护进程重启时会重新检测容器状态它发现codex-sbx-a8f3c2d1的容器名仍在被一个僵尸容器占用而Codex侧的状态文件又记录着这个会话ID。Codex启动新会话时尝试重建同名的容器Docker返回Conflict错误而Codex的容器创建代码没有针对这个冲突做重试只是报了Unavailable。这解释了第一次启动失败的真正原因——不是镜像坏了是容器名被僵尸容器占住了。4.3 根因之三内存配额与实际可用内存不匹配前面提到容器内OOM的问题背后是Docker Desktop在WSL2上的内存管理缺陷。WSL2默认是动态分配内存但Docker Desktop为了给宿主机确保桌面响应会在.wslconfig里设置一个上限。当容器内进程请求内存时cgroup向WSL2内存子系统申请而WSL2还没把内存从“已缓存”状态回收回来就直接判定为无法满足于是触发了OOM。我检查了当时的默认配置Docker Desktop界面上显示内存限制为2GB.wslconfig里memory4GB看起来不会有问题。但运行中的实际内存状态里WSL2的页面缓存占用了接近3GB容器cgroup可用不到1GB。这导致容器内的Codex进程在构建时一旦超过800MB就秒挂。这属于配置与运行时不匹配问题也是整个故障链中唯一一个在完全正常操作下也能复现的环节。4.4 根因之间的交互关系把三个根因串起来看链条是这样的强制关机导致镜像层与悬挂层损坏 → 容器启动时加载到错误的层 → 文件系统出现只读异常 → 容器进程在读写工作区时被卡住 → 内存快速上涨触发OOM → 容器被杀后残留僵尸容器 → 新会话建容器时名字冲突 → 状态文件与容器不一致导致恢复失败。每一个单独的问题都不致命但它们像多米诺一样一个推一个最终把整个沙箱彻底堵死。5. 修复实操从紧急恢复到根治方案5.1 紧急恢复流程直接照做如果你现在正被同样的问题卡住可以按下面这套流程走我已经实测有效。不要跳过任何一步顺序也不能颠倒。第一步先把所有Codex进程杀掉。在PowerShell里执行Get-Process | Where-Object {$_.ProcessName -like *codex*} | Stop-Process -Force第二步彻底关闭Docker Desktop。不要点界面的退出按钮直接用命令强制结束Stop-Process -Name Docker Desktop -Force # 再确认没有残留的后台进程 Get-Process | Where-Object {$_.ProcessName -like *docker*} | Stop-Process -Force第三步执行WSL2冷重启。这一步能强制清理虚拟磁盘上的文件锁和网络组件状态wsl --shutdown # 等待10秒让虚拟机和虚拟磁盘完全释放 Start-Sleep -Seconds 10第四步清理僵尸容器和悬挂镜像。重新启动Docker Desktop后执行docker rm -f $(docker ps -aq) docker system prune -af --volumes注意--volumes会把所有容器卷数据也清掉如果你有重要的中间产物先把它们复制到宿主机目录里再执行。第五步重建沙箱镜像。Codex首次运行时会自动拉取也可以手动指定镜像标签重建docker pull registry.internal/codex-sandbox:v2.3.1跑完这五步再正常启动Codex我这里是立刻恢复了。提示这套流程会丢失所有历史会话状态如果Codex里有还没保存到宿主机的输出文件务必先在第一步之前把工作区整个复制出来。5.2 根治方案一调整资源预算紧急恢复只是把当前问题处理掉防止再次发生才是重点。先处理资源问题。Docker Desktop在Windows上的内存分配不要用动态模式直接固定一个值。我的建议是如果宿主机有16GB内存就把WSL2的.wslconfig改成[wsl2] memory8GB processors4 swap0Docker Desktop设置里也要把内存限制改为8GBCPU保持4核。容器级别的内存参数在Codex的配置文件里设置以config.toml为例[sandbox] memory_limit_mb 1536 memory_swap_mb 0 cpu_shares 2关键是memory_swap_mb 0让容器的内存上限严格等于memory_limit_mb不要给SWAP预算。因为WSL2的SWAP在Docker Desktop后端里的行为不可控与其让它造成虚假的“可以超额内存”错觉不如不要。5.3 根治方案二镜像不可变与定期清理镜像层要走到“不可变”这个程度。我给自己的实践定了几条规则你可以直接抄。第一每次更新镜像后立刻清理旧镜像不要留历史副本。第二给镜像打上不可变标签代码仓库里明确禁止在镜像上追加修改层任何工作区变化都走卷挂载不写进镜像层。第三每周固定跑一次Docker的深度清理不仅仅是docker system prune要加上docker builder prune --all清理旧的构建缓存。清理命令我放在计划任务里每周日凌晨执行docker builder prune -af docker system prune -af --volumes5.4 根治方案三给沙箱加健康检查最后一步也是我觉得最重要的预防措施让Codex启动沙箱时执行一次健康检查。这个功能不是Codex原生支持的但可以写一个外挂脚本在启动前检查三个东西。# 检查退出码为137的僵尸容器 docker ps -aq --filter statusexited --filter statusdead | Measure-Object | Select-Object -ExpandProperty Count # 检查镜像层校验和 docker image inspect registry.internal/codex-sandbox:v2.3.1 --format {{json .RootFS.Layers}} # 检查WSL2虚拟磁盘占用 Get-ChildItem $env:LOCALAPPDATA\Docker\wsl\disk\docker_data.vhdx | Select-Object Length如果第一条返回的计数大于3基本可以预告会有容器名冲突问题。如果第二条返回的层数比镜像定义多出两个以上镜像层已经有残留了。如果第三条文件大小超过宿主机内存的1.5倍说明历史数据堆积已经比较危险。6. 常见问题速查与后续排查清单6.1 常见问题速查表现象最可能的根因快速检查命令解决方案启动报rpc error: Unavailable僵尸容器占用会话名或Docker守护进程异常docker ps -aq --filter statusdead清僵尸容器重启Docker容器启动后秒挂退出码137内存配额耗尽或cgroup与WSL2内存不匹配docker inspect --format {{.State.OOMKilled}} 容器名调整.wslconfig内存上限容器内去掉swap工作区文件只读镜像层损坏或overlay2层不一致docker system df清理悬挂层重建镜像会话恢复后内容丢失状态文件与容器实际状态不一致检查.codex\state\下的会话元数据手动清理会话文件重建容器容器启动极慢构建时卡顿WSL2虚拟磁盘碎片化历史数据过多Get-Item $env:LOCALAPPDATA\Docker\wsl\disk\docker_data.vhdx定期清理镜像与卷或执行docker system prune -a6.2 后续需要留意的三个征兆这次故障让我意识到沙箱类问题往往不是突然炸的而是有一段时间的“亚健康”状态只是我没有注意。第一个征兆是容器冷启动时间变长。以前启动一个沙箱容器只需要3到5秒出故障前一段时间每次要8到10秒。这就是镜像层读取变慢的表现层不完整时Docker要反复校验启动时间会明显上涨。第二个征兆是vmmem进程的内存占用持续居高不下。正常情况下WSL2内部的内存可以被回收如果任务结束后vmmem还占着50%以上物理内存说明WSL2的内存回收机制已经出现异常。第三个征兆是Codex的日志里偶尔出现retrying sandbox start这说明CLI已经感知到容器不稳定只是暂时还能靠重试掩盖过去。这三个征兆随便出现一个就应该执行一次完整的清理流程而不是等到故障来了再处理。6.3 恢复后的验证与回归测试修复完成后不能直接说“好了”要做回归验证。我当时的验证分三步走。第一步连续启动并销毁沙箱容器五次每次启动时间都在5秒内没有被OOM杀死的记录。第二步跑一次完整工具调用链路在沙箱内创建文件、修改文件、删除文件、执行构建命令、退出会话再恢复确认所有操作正常。第三步跑一个真实的小模块任务让Codex连续执行超过200次工具调用观察内存曲线是否稳定。只有这三步全部通过才算真正恢复了。7. 踩过这次坑后的几点经验写到最后分享几个我个人体会最深的经验。第一个经验是在Windows上玩Codex这类依赖容器的工具永远把“坏关机”当成头号风险源。一次非正常的电源中断可能比升十个版本带来的问题都多。现在我每次离开工作台都会确认所有虚拟机服务已经正常关闭宁可多等30秒也不想再花4个小时去修复镜像层。第二个经验是Codex的沙箱配置绝不是默认值就能一路跑通的。默认配置在干净的Linux环境里或许没问题但在Windows的WSL2后端下内存和SWAP的默认策略必须手动调而且调完一定要压测不能只看界面上的参数。第三个经验是关于中间产物的。以前我习惯把Codex的工作区直接当作数据保险箱觉得容器里写的文件应该一直在。现在我会在任务的关键节点把输出同步到宿主机目录沙箱容器本来就是可以随时销毁的临时环境任何依赖容器生存期的数据都不可靠。希望这篇复盘能帮到你。如果你的Codex沙箱也出现过类似的问题欢迎按上面的检查清单先自查一遍多数情况不需要重装系统也犯不着一怒之下把Docker Desktop卸载重装。按从应用到容器到WSL2的层级一步步查下来总能定位到真正的问题。