1. 问题现象与背景拆解1.1 这个报错到底在说什么Windows 版 Codex 在首次启动或重置配置后会弹出一个引导页上面有个按钮叫“继续完成 Windows 设置”。点下去之后正常情况下应该自动完成沙箱环境的初始化然后进入主界面。但很多人包括我自己在这一步会遇到一个弹窗或者命令行输出提示“Windows 沙箱初始化失败”后面往往还跟着一串不太友好的错误码或者干脆什么都没有。这个提示的核心含义是Codex 想在 Windows 上创建一个隔离的运行环境也就是沙箱用来安全地执行代码、调用工具、读写临时文件但创建过程失败了。沙箱初始化失败并不等于 Codex 本身坏了而是它依赖的某个底层组件没有就绪。常见的原因集中在几个方向系统沙箱功能未启用、配置文件config.toml写入了不兼容的参数、权限不足、依赖的运行时缺失、安全软件拦截。我前后在三台不同版本的 Windows 上复现过这个问题有 Windows 10 22H2、Windows 11 23H2 和 Windows 11 24H2表现略有差异但排查思路是一致的。下面我会把整个排查过程拆开从最可能的原因开始一步步往下走。1.2 哪些人容易踩到这个坑根据我自己的观察和社区里的反馈下面这几类用户遇到“Windows 沙箱初始化失败”的概率明显更高刚装完 Codex 桌面版第一次点“继续完成 Windows 设置”的人。这是最高发的场景因为初始化只做一次失败之后不会自动重试。手动改过config.toml的人。尤其是从网上抄了一段配置里面带了sandbox_mode或者mcp_servers相关字段但参数值跟当前版本不匹配。系统里装了多个安全软件或者企业管控策略的人。沙箱创建过程涉及进程隔离和文件系统虚拟化容易被拦截。Windows 家庭版用户。部分沙箱依赖的功能在家庭版上默认不可用需要额外确认。之前装过其他沙箱类工具如 Windows Sandbox、Docker、WSL的人。组件之间可能互相影响尤其是 Hyper-V 和虚拟机平台功能的占用关系。如果你属于上面任意一类那这篇文章就是写给你的。我会尽量把每一步都写清楚让你能直接照着做。2. 排查前的准备工作与信息收集2.1 先确认你的 Codex 版本和安装方式在动手改任何东西之前先搞清楚你装的是哪个版本、用什么方式装的。不同安装方式对应的配置目录和修复手段不一样。打开 PowerShell执行codex --version如果这条命令能正常输出版本号说明 Codex 的可执行文件已经在 PATH 里了。如果提示“无法将‘codex’项识别为 cmdlet”那说明你是通过桌面安装包装的可执行文件没有加入系统 PATH这时候你需要去安装目录里找。常见的安装方式有三种安装方式典型路径配置文件位置官方桌面安装包C:\Users\你的用户名\AppData\Local\Programs\CodexC:\Users\你的用户名\.codex\config.toml命令行工具安装通过包管理器全局安装同上便携版解压你自己选的目录同上或者安装目录下的config.toml我实测下来不管哪种安装方式用户级配置文件默认都在C:\Users\你的用户名\.codex\config.toml。这个路径很关键后面很多问题都出在这里。你可以用下面这条命令快速确认文件是否存在Test-Path $env:USERPROFILE\.codex\config.toml返回True就说明文件在返回False说明你还没生成过配置文件或者被清理掉了。2.2 把报错信息完整抓下来很多人一看到弹窗就急着点“确定”结果什么信息都没留下。我的习惯是先把完整报错抓下来再动手。具体做法有两种。第一种如果报错是以弹窗形式出现的先别关用截图工具截下来或者用手机拍一下。重点看有没有错误码比如0x80070005权限拒绝、0x8007019e组件未安装这类。第二种如果报错是在命令行里输出的直接复制粘贴到记事本里。你还可以用重定向把输出存成文件codex --diagnose * $env:USERPROFILE\Desktop\codex_diag.txt这样所有的诊断信息都会存到桌面的codex_diag.txt里方便你慢慢看也方便发给别人求助。提示如果你在弹窗里看到的是“Windows 沙箱初始化失败”但没有任何附加信息那大概率是沙箱功能本身没启用或者配置文件里有非法字段导致解析提前中断。这两种情况在下面都会讲到。2.3 检查系统版本和关键功能状态沙箱初始化依赖 Windows 的几项底层能力。先确认你的系统版本winver会弹出一个窗口显示版本号和内部版本号。我建议你记下来因为不同版本对沙箱的支持程度不一样。然后检查几个关键功能是否启用Get-WindowsOptionalFeature -Online -FeatureName Containers-DisposableClientVM Get-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V这三条命令分别对应Windows 沙箱、虚拟机平台、Hyper-V。返回结果里State字段如果是Enabled就说明已启用Disabled就是没启用。我遇到的大部分“沙箱初始化失败”案例问题都出在Containers-DisposableClientVM这一项是Disabled。3. 核心原因逐项排查与修复3.1 原因一Windows 沙箱功能未启用这是最常见的原因没有之一。Codex 在 Windows 上创建沙箱时底层会调用 Windows 自带的沙箱能力也就是Containers-DisposableClientVM这个可选功能。如果这个功能没开初始化必然失败。修复步骤以管理员身份打开 PowerShell。注意必须是管理员否则下面的命令会报权限错误。执行启用命令Enable-WindowsOptionalFeature -Online -FeatureName Containers-DisposableClientVM -All执行完之后系统会提示你是否重启。一定要重启不重启功能不会生效。重启后再次执行检查命令确认状态变成EnabledGet-WindowsOptionalFeature -Online -FeatureName Containers-DisposableClientVM重新打开 Codex再点一次“继续完成 Windows 设置”。这里有个细节要注意Windows 家庭版默认没有 Windows 沙箱功能。如果你在家庭版上执行上面的启用命令可能会提示找不到该功能。这种情况下你有两个选择一是升级到专业版或企业版二是改用 Codex 的轻量沙箱模式如果当前版本支持的话具体在config.toml里设置sandbox_mode为对应的值。我后面会专门讲配置文件的写法。注意启用沙箱功能会同时启用 Hyper-V 相关组件。如果你机器上装了其他虚拟化软件比如某些安卓模拟器可能会提示冲突。遇到这种情况先关掉那些软件再启用启用完重启后再打开。3.2 原因二config.toml 里有非法或过时字段Codex 的配置文件config.toml是 TOML 格式对字段名和值的要求比较严格。如果你从网上抄了一段配置里面带了当前版本不认识的字段Codex 在解析时可能会直接中断导致沙箱初始化流程走不下去。我见过最典型的几个问题字段mcp_servers.node_repl.type—— 这个字段在某些版本里已经被重命名或移除留着会触发“unrecognized configuration setting”警告严重时直接导致初始化失败。sandbox_mode的值写成了不支持的字符串比如off、none、true这类。正确的值通常是read-only、workspace-write、danger-full-access之一具体取决于你的版本。字段名拼写错误比如把sandbox_mode写成sandboxMode或者sandbox-mode。TOML 是大小写敏感且要求下划线的。修复步骤先备份现有配置Copy-Item $env:USERPROFILE\.codex\config.toml $env:USERPROFILE\.codex\config.toml.bak用记事本打开配置文件notepad $env:USERPROFILE\.codex\config.toml把里面所有你不确定的字段先注释掉在行首加#只保留最基础的几行。一个最小可用的配置大概长这样# Codex 基础配置 model gpt-5 sandbox_mode workspace-write approval_policy on-request保存文件重新启动 Codex再点“继续完成 Windows 设置”。如果这样能成功说明问题确实出在配置字段上。接下来你可以逐段把之前注释掉的配置加回来每加一段就重启一次 Codex直到找到那个导致失败的字段。这个过程有点笨但非常有效。提示Codex 在启动时会检查配置文件如果发现不认识的字段会在日志里输出类似“codex is ignoring 1 unrecognized configuration setting”的提示。你可以通过查看日志来快速定位是哪个字段有问题。日志位置一般在C:\Users\你的用户名\.codex\logs目录下。3.3 原因三权限不足或用户目录异常沙箱初始化需要在用户目录下创建临时文件夹、写入状态文件。如果你的用户目录权限被改过或者磁盘空间不足也会导致失败。检查点确认C:\Users\你的用户名\.codex目录存在且可写。你可以手动在里面新建一个文本文件试试如果连新建都失败那就是权限问题。确认系统盘剩余空间大于 5GB。沙箱初始化会解压一些运行时文件空间不够会直接失败。确认你的用户名里没有特殊字符。我遇到过用户名带中文或者空格导致路径解析异常的情况。如果你用的是中文用户名可以尝试在config.toml里显式指定一个纯英文的临时目录。修复权限的方法icacls $env:USERPROFILE\.codex /grant $env:USERNAME:(OI)(CI)F /T这条命令会把.codex目录及其子目录的完全控制权限授予当前用户。执行完之后再试一次。如果磁盘空间不足清理一下临时文件Remove-Item $env:TEMP\* -Recurse -Force -ErrorAction SilentlyContinue3.4 原因四安全软件或系统策略拦截沙箱创建过程涉及进程隔离和文件系统虚拟化行为特征比较像“敏感操作”容易被安全软件拦截。我实测下来下面几类软件最容易造成干扰第三方杀毒软件尤其是带“主动防御”功能的企业级终端管控软件Windows 自带的“受控文件夹访问”功能排查方法临时关闭第三方杀毒软件的实时防护再试一次。如果成功说明就是它拦的你需要把 Codex 的安装目录和.codex目录加入白名单。检查“受控文件夹访问”是否开启打开 Windows 安全中心找到“病毒和威胁防护”再找到“勒索软件防护”看“受控文件夹访问”是不是开着的。如果是把它关掉再试。如果你在公司电脑上可能有组策略限制。这种情况你自己改不了需要找 IT 管理员。注意临时关闭安全软件只是排查手段排查完一定要重新打开。长期关闭安全软件风险很大正确的做法是加白名单而不是一关了之。3.5 原因五依赖运行时缺失或损坏Codex 的沙箱组件依赖一些运行时库比如 VC 运行库、.NET 运行时等。如果这些库缺失或者版本太旧初始化也会失败。检查方法Get-Item C:\Windows\System32\vcruntime140.dll | Select-Object VersionInfo如果这条命令报错说找不到文件那说明 VC 运行库没装。你可以去微软官网下载最新的 VC 运行库合集安装包装完重启再试。另外如果你之前装过 Docker 或者 WSL可能会存在组件版本冲突。我遇到过一次是因为 Docker 自带的某个虚拟化组件版本比 Codex 要求的低导致沙箱创建时调用了错误的接口。解决办法是更新 Docker 到最新版或者临时停掉 Docker 的后台服务再试。4. 完整修复流程实操记录4.1 一次真实的修复过程下面是我在一台 Windows 11 23H2 机器上的完整修复记录。这台机器之前装过 Docker Desktop用户手动改过config.toml报错就是“Windows 沙箱初始化失败”。第一步抓取报错。我在命令行里执行了codex --diagnose输出里有一行关键信息[ERROR] sandbox init failed: feature Containers-DisposableClientVM is not enabled这就直接定位到了原因一。第二步启用沙箱功能。以管理员身份运行 PowerShell执行Enable-WindowsOptionalFeature -Online -FeatureName Containers-DisposableClientVM -All系统提示重启我重启了。第三步检查配置文件。重启后我先没急着开 Codex而是打开config.toml看了一眼。里面有一段[mcp_servers.node_repl] type stdio command node这个type字段在当前版本里已经不需要了留着会触发警告。我把它注释掉了。第四步重新初始化。打开 Codex点“继续完成 Windows 设置”这次没有报错直接进入了主界面。第五步验证沙箱是否真的可用。我在 Codex 里新建了一个会话让它执行一段简单的 Python 代码import os print(os.getcwd())输出正常说明沙箱已经能正常创建和运行了。4.2 修复后的验证清单修好之后别急着用先做几个验证确保沙箱是真的可用而不是表面看起来好了。验证项操作方法预期结果沙箱功能状态Get-WindowsOptionalFeature -Online -FeatureName Containers-DisposableClientVMState 为 Enabled配置文件解析启动 Codex 时观察日志无 unrecognized setting 警告沙箱内执行代码在 Codex 会话里运行print(hello)正常输出 hello文件读写让 Codex 在临时目录创建文件文件成功创建且可读权限隔离尝试访问系统目录被拒绝或提示无权限这五项都通过基本可以确认沙箱初始化问题彻底解决了。4.3 如果所有方法都试过还是失败如果你把上面五类原因都排查了一遍还是失败那可能是更底层的问题。我建议你按下面的顺序做最后尝试完全卸载 Codex清理残留目录重新安装。残留目录包括C:\Users\你的用户名\.codex和安装目录。清理完重启电脑再装。新建一个 Windows 本地用户账户在新账户下安装 Codex。这可以排除当前用户配置文件损坏的问题。检查系统日志。打开“事件查看器”看“Windows 日志”下的“应用程序”和“系统”里有没有跟沙箱相关的错误记录。错误码能提供更精确的线索。在社区里搜索错误码。把完整的错误码贴到搜索引擎里通常能找到遇到同样问题的人。5. 常见问题速查与避坑经验5.1 高频问题速查表问题现象最可能原因快速修复点按钮后弹窗“沙箱初始化失败”无错误码沙箱功能未启用管理员启用 Containers-DisposableClientVM 并重启报错提到 unrecognized configuration settingconfig.toml 有非法字段注释掉可疑字段保留最小配置报错提到 access denied权限不足用 icacls 授予 .codex 目录完全控制报错提到 feature not found系统版本不支持确认是否家庭版考虑升级或改用轻量模式初始化卡住不动安全软件拦截临时关闭实时防护加白名单初始化后沙箱内命令执行失败运行时缺失安装最新 VC 运行库5.2 我踩过的几个坑坑一以为重启不重要。启用沙箱功能后系统提示重启我嫌麻烦没重启直接开 Codex结果还是失败。后来老老实实重启一次就过了。Windows 的可选功能启用后必须重启才能生效这个没有捷径。坑二配置文件里留了中文注释导致解析异常。TOML 标准是支持 UTF-8 的但某些版本的解析器对中文注释处理有问题。我后来把注释全改成英文问题消失。如果你也遇到莫名其妙的解析失败可以试试把注释删掉或者改成英文。坑三Docker 和 Codex 抢虚拟化资源。我机器上 Docker Desktop 默认开机自启占用了 Hyper-V 的一部分资源。Codex 初始化沙箱时申请不到足够的虚拟化能力就失败了。解决办法是把 Docker 改成手动启动用的时候再开。坑四用户名带空格导致路径解析出错。我有一个测试账户的用户名是test user中间有空格。Codex 在拼接路径时没有加引号导致找不到目录。后来我把用户名改成testuser问题解决。如果你用户名里有空格或特殊字符建议新建一个纯英文无空格的账户来用。5.3 关于 config.toml 的几点经验config.toml是 Codex 在 Windows 上最容易出问题的地方我总结了几条经验改之前一定备份。我习惯用config.toml.bak作为备份文件名出问题直接改回来。只加你理解的字段。网上抄来的配置如果不确定某个字段的作用先别加。加了之后如果出问题优先怀疑它。字段值用双引号包起来。TOML 里字符串值必须用引号漏了引号会导致解析失败。不要用 Tab 缩进。TOML 对缩进不敏感但混用 Tab 和空格在某些解析器里会出问题统一用空格。改完用codex --diagnose验证。这条命令会解析配置并输出结果有错会直接告诉你。5.4 沙箱模式的选择建议sandbox_mode这个字段控制沙箱的隔离级别不同值对初始化的要求不一样。我整理了一个对照表sandbox_mode 值隔离级别初始化要求适用场景read-only最高需要完整沙箱功能只读代码审查、安全敏感任务workspace-write中等需要完整沙箱功能日常开发、文件读写danger-full-access最低可能不需要沙箱功能本地调试、信任环境如果你在家庭版 Windows 上完整沙箱功能不可用可以尝试把sandbox_mode设为danger-full-access这样 Codex 可能跳过沙箱创建步骤。但我要强调这个模式的安全性最低只建议在你完全信任运行环境的情况下使用。6. 预防措施与长期维护建议6.1 保持系统和运行库更新Windows 的可选功能和运行时库会随着系统更新而变化。我建议把 Windows Update 保持开启至少每月检查一次更新。特别是累积更新里面经常包含沙箱相关组件的修复。VC 运行库也建议定期更新。你可以去微软官网下载最新的可再发行组件包装一次管很久。6.2 给 Codex 目录加白名单如果你装了第三方安全软件把下面两个目录加入白名单可以避免很多莫名其妙的拦截Codex 安装目录比如C:\Users\你的用户名\AppData\Local\Programs\Codex配置目录C:\Users\你的用户名\.codex加白名单的方法因软件而异一般在“设置”里的“排除项”或“信任区”里添加。6.3 定期清理沙箱临时文件沙箱运行过程中会在临时目录里留下一些文件。时间长了可能占用空间也可能导致新的初始化失败。我习惯每个月清理一次Remove-Item $env:TEMP\codex-* -Recurse -Force -ErrorAction SilentlyContinue这条命令只删除 Codex 相关的临时文件不影响其他程序。6.4 记录你的可用配置一旦你找到一组能正常工作的配置把它单独存一份。我是在.codex目录下建了一个config.working.toml把当前可用的配置复制进去。下次如果改坏了直接复制回来就行不用重新排查。这个习惯帮我省了很多时间。尤其是 Codex 版本更新后如果新版本对配置字段有改动我可以快速对比新旧配置定位差异。6.5 关注版本更新日志Codex 的每个版本更新日志里通常会提到配置字段的变更和沙箱相关的修复。我建议每次更新前花两分钟扫一眼更新日志看看有没有影响你的改动。特别是看到“deprecated”“removed”“renamed”这类词就要留意自己的配置文件里有没有对应的字段。我在实际使用中的体会是Windows 上的沙箱问题九成以上都能通过“启用功能 清理配置 重启”这三步解决。剩下的那一成多半是权限或者安全软件的问题。把这两类原因排查完基本就没有解决不了的。
