保姆级教程：拯救 Windows 11 上“罢工”的 Codex 沙箱环境

最近在折腾 AI 开发工具的时候，不少朋友反映在 Windows 11 上运行 OpenAI Codex 总是遇到各种疑难杂症，尤其是沙箱（Sandbox）环境动不动就崩，或者提示找不到依赖文件。其实这大多不是 Codex 本身的问题，而是咱们 Windows 环境变量和历史遗留的配置在“作祟”。

今天我就把这套经过实测的修复方案整理出来，顺带分享一些关于 PowerShell 7 管理的最佳实践，帮你把开发环境彻底理顺。

⚠️ 第一步：更换安装方式并清理旧版本

很多人第一次装 Codex 可能习惯了用 npm，但在 Windows 上这有时候会挖坑。为了稳妥起见，建议直接切换到官方的 PowerShell 安装源。在管理员 PowerShell 中运行：

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

使用 mklink 命令修复断裂的目录链接

安装方法只是前菜，真正的“大坑”往往藏在 PowerShell 7 的版本里。

如果你之前是通过 Microsoft Store 安装的 PowerShell 7，请务必卸载它。Store 版本的权限管理和路径机制经常与开发工具的沙箱机制冲突。推荐的做法是前往 GitHub 官方仓库下载最新的 ZIP 包，把它手动解压到 C:\Program Files\PowerShell\7，然后手动将这个路径添加到系统环境变量的 Path 列表中，确保系统优先调用这个版本。

🔧 第二步：修复断裂的目录链接（核心步骤）

Codex 沙箱无法运行的核心原因，往往是找不到 bin 目录和资源目录。我们可以通过检查一个关键路径来确诊：

• 路径：%LOCALAPPDATA%\Programs\OpenAI\Codex

打开这个文件夹，正常情况下你应该能看到里面有两个文件夹。如果你的这两个文件夹不见了，或者图标看起来不太对劲（快捷方式图标等），那就说明软链接丢失了。我们需要用 mklink 命令把它们重新挂载回来。

请在 PowerShell 中依次执行以下两条命令，它们会创建“目录联接”（Junction），相当于把 Codex 的实际工作目录映射到系统预期的位置：

cmd /c mklink /J "$env:LOCALAPPDATA\Programs\OpenAI\Codex\bin" "$env:USERPROFILE\.codex\packages\standalone\current\bin"

cmd /c mklink /J "$env:LOCALAPPDATA\Programs\OpenAI\Codex\codex-resources" "$env:USERPROFILE\.codex\packages\standalone\current\codex-resources"

执行完后，再去看看那个目录，文件是不是都回来了？这时候再尝试启动 Codex，大概率就能丝滑入住了。

📜 附赠：PowerShell 7 高效调用规范

既然把环境重置了一遍，不如把写脚本的习惯也升级一下。如果你经常需要在 Windows 上通过命令行调用 Node、Python 或者处理复杂任务，下面这套规则能让你少掉很多头发。这是我和 Claude/GPT 总结出来的“防坑指南”：

1. 启动参数要严谨

• 一律使用 pwsh -NoProfile -NonInteractive，这样可以避免加载个人配置脚本带来的干扰，同时禁用老旧的 powershell 5.1。
• 只有当执行策略明确报错阻止时，才加上 -ExecutionPolicy Bypass，不要为了省事默认开启。

2. 引号与变量的避坑守则

• 短命令用 -Command '...'：记住一条铁律，外层用单引号，内层用双引号。一旦命令里包含 $变量、$_、$env:、$(...) 或者花括号 {}，严禁外层使用双引号，否则变量会被意外展开甚至报错。

3. 复杂脚本怎么处理？

• 如果是多行代码、复杂管道操作，或者涉及 Node/Python 调用、处理大量 JSON/正则/引号时，不要直接内联写。
• 正确的做法是将脚本写入系统临时目录（如 $env:TEMP），然后用 -File 参数调用（JS/PY 则用 node / python 执行文件）。切记不要把脚本落在项目目录里，执行完后默认清理掉，除非有特殊保留需求。

4. 内联脚本的 Here-String 写法

• 如果非要内联写脚本，短脚本可以用单引号的 Here-String @'...'@，这样可以实现“零展开”，最安全。
• 只有确实需要 PowerShell 插值变量时，才使用 @"..."@。
• 起止标记 @' 和 '@ 必须独占一行，且行首不能有空格。

5. 路径操作的细节

• 路径拼接尽量用 Join-Path，或者针对已存在的路径用 Resolve-Path。
• 在执行删除、移动、覆盖、递归操作前，务必检查目标绝对路径是否在你预期的目录内，防止误删系统文件。

6. 安全与调用

• 禁用 Invoke-Expression（IEX），这是安全大忌。
• 如果调用的外部程序路径含空格，必须使用调用操作符 & （即 & "path with space"）。

7. 错误处理

• 脚本内部第一行最好加上 $ErrorActionPreference = 'Stop'，注意这默认不会捕获外部 exe 的失败，需要你手动检查。
• 执行完外部命令后，一定要检查 $LASTEXITCODE。如果需要把外部命令的结果传递出去，记得显式写 exit $LASTEXITCODE。

8. 编码问题

• PowerShell 7 默认就是 UTF-8，只有在实际出现乱码的情况下才需要去特意外部处理编码。

总结

Windows 上的开发环境配置确实细节繁多，尤其是涉及到沙箱和软链接的时候。通过卸载 Store 版 PowerShell、手动安装修复版，并手动重建 mklink 链接，基本上能解决 90% 的 Codex 启动失败问题。配合上面的 PowerShell 规范，不仅能修复环境，还能让你的自动化脚本更加健壮。

如果你按照这个步骤操作后还有问题，欢迎在评论区交流，咱们一起排查！