OpenAI Codex 中文文档（4.14更新）
联系我 ↗
官方文档 ↗

Windows

在 Windows 上使用 Codex 的运行方式、WSL2 工作流与常见排障方法。

你可以通过原生 Codex App、CLI 或 IDE 扩展在 Windows 上使用 Codex。

根据使用表面和你的环境设置，Codex 在 Windows 上通常有三种实际运行方式：

Windows 沙箱

当你在 Windows 原生环境中运行 Codex 时，智能体模式会使用 Windows 沙箱，阻止其向工作目录外写入文件，并防止它在没有你显式批准的情况下访问网络。

原生 Windows 沙箱支持两种模式，你可以在 config.toml 中进行配置：

[windows]
sandbox = "elevated" # or "unelevated"

elevated 是首选的原生 Windows 沙箱。它使用专门的低权限沙箱用户、文件系统权限边界、防火墙规则，以及执行沙箱命令所需的本地策略调整。

unelevated 是回退用的原生 Windows 沙箱。它会基于当前用户派生一个受限 Windows token，使用基于 ACL 的文件系统边界，并通过环境级离线控制替代专用离线用户的防火墙规则。它比 elevated 弱一些，但当本地或企业策略阻止管理员批准的初始化步骤时，它仍然有用。

如果两种模式都可用，优先选择 elevated。如果默认的原生沙箱在你的环境中无法工作，再使用 unelevated 作为排障期间的回退方案。

默认情况下，这两种沙箱模式都会使用私有桌面（private desktop），以提供更强的界面隔离。只有在你确实需要兼容旧的 Winsta0\Default 行为时，才应把 windows.sandbox_private_desktop = false。

沙箱权限

Windows 版本矩阵

Windows 版本 支持级别 说明
Windows 11 推荐 这是在 Windows 上部署 Codex 的最佳基线。如果你正在做企业级标准化部署，优先选它。
较新且已完整更新的 Windows 10 尽力支持 可以工作，但稳定性不如 Windows 11。对于 Windows 10，Codex 依赖较新的控制台支持能力，包括 ConPTY。实践上至少需要 Windows 10 1809（October 2018 Update）或更新版本。
更旧的 Windows 10 构建 不推荐 更可能缺少 ConPTY 等必需控制台组件，也更容易在企业环境中失败。

额外环境假设：

  • 应该具备 winget。如果没有，请先更新 Windows，或安装 Windows Package Manager。
  • 推荐的原生沙箱依赖管理员批准的初始化步骤。
  • 某些受企业管理的设备即便系统版本合格，也可能因为策略限制而阻止所需初始化。

授予沙箱读取权限

当某条命令失败的原因是 Windows 沙箱无法读取某个目录时，可执行：

/sandbox-add-read-dir C:\absolute\directory\path

该路径必须是已存在的绝对目录。命令成功后，后续在当前会话中于沙箱内运行的命令就可以读取该目录。

我们建议默认优先使用原生 Windows 沙箱。它通常能在保持同样安全边界的同时提供最佳性能和速度。如果你需要 Linux 原生环境、你的工作流本来就在 WSL2 中，或者两种原生 Windows 沙箱模式都不适合当前环境，再选择 WSL2。

如果你想复用一组可重复使用的权限配置，可以把 default_permissions 指向某个命名权限档案，再通过 [permissions.<name>.filesystem] 或 [permissions.<name>.network] 定义规则。托管网络权限则使用 [permissions.<name>.network.domains] 和 [permissions.<name>.network.unix_sockets] 这样的 map table 来描述域名和 Unix socket 访问策略。

适用于 Linux 的 Windows 子系统（WSL）

如果你选择 WSL2，Codex 会运行在 Linux 环境中，而不是使用原生 Windows 沙箱。这适合以下情况：

  • 你需要 Linux 原生工具链
  • 你的仓库和开发工作流本来就位于 WSL2 中
  • 两种原生 Windows 沙箱模式都无法满足你的环境需求

WSL1 在 Codex 0.114 之前仍可使用。从 Codex 0.115 开始，Linux 沙箱切换到了 bwrap，因此 WSL1 不再受支持。

从 WSL2 内启动 VS Code

如需逐步说明，请参见官方的 VS Code WSL tutorial。

前置条件

  • 已在 Windows 上安装 WSL。安装方式是以管理员身份打开 PowerShell，然后运行 wsl --install。常见选择是 Ubuntu。
  • 已安装带有 WSL 扩展 的 VS Code。

从 WSL 终端打开 VS Code

# From your WSL shell
cd ~/code/your-project
code .

这会打开一个 WSL 远程窗口，如有需要还会安装 VS Code Server，并确保集成终端运行在 Linux 环境中。

确认你已连接到 WSL

  • 查看绿色状态栏中是否显示 WSL: <distro>
  • 集成终端应显示 Linux 路径，例如 /home/...，而不是 C:\
  • 你还可以运行：
echo $WSL_DISTRO_NAME

这会打印当前发行版名称。

在 WSL2 中使用 Codex CLI

先在提升权限的 PowerShell 或 Windows Terminal 中运行：

# Install default Linux distribution (like Ubuntu)
wsl --install

# Start a shell inside Windows Subsystem for Linux
wsl

然后在 WSL shell 中运行：

# https://learn.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-wsl
# Install Node.js in WSL (via nvm)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash

# In a new tab or after exiting and running `wsl` again to install Node.js
nvm install 22

# Install and run Codex in WSL
npm i -g @openai/codex
codex

在 WSL2 中处理代码

  • 在 Windows 挂载路径，例如 /mnt/c/... 下工作，通常会比在 Windows 原生路径中更慢。为了获得更快的 I/O，并减少符号链接和权限问题，建议把仓库放在 Linux home 目录中，例如 ~/code/my-app：
mkdir -p ~/code && cd ~/code
git clone https://github.com/your/repo.git
cd repo
  • 如果你需要从 Windows 访问这些文件，可以在 Explorer 中通过 \\wsl$\Ubuntu\home\<user> 访问。

排障与常见问题

如果你正在排查一台受管理的 Windows 机器，先从原生沙箱模式、Windows 版本以及 Codex 显示的策略错误开始排查。多数原生 Windows 支持问题都来自沙箱初始化、登录权限或文件系统权限，而不是编辑器本身。

原生沙箱设置失败

如果 Codex 无法完成 elevated 沙箱设置，最常见原因包括：

  • Windows UAC 或管理员提示被拒绝
  • 机器不允许创建本地用户或组
  • 机器不允许修改防火墙规则
  • 机器阻止了沙箱用户所需的登录权限
  • 或者其他企业策略阻止了设置流程中的某个环节

可尝试：

  1. 重新执行 elevated 沙箱设置，并在环境允许的情况下批准管理员提示。
  2. 如果公司电脑阻止了这一步，请向 IT 团队确认，该设备是否允许管理员批准的本地用户 / 组创建、防火墙配置，以及沙箱用户所需的登录权限。
  3. 如果默认设置仍然失败，先切换到 unelevated 沙箱，以便在调查问题时继续工作。
Codex 自动切换到了 unelevated 沙箱

这表示 Codex 无法在你的机器上完成更强的 elevated 沙箱设置。

  • Codex 仍然可以在沙箱模式下运行。
  • 它仍然会应用基于 ACL 的文件系统边界，但不会使用 elevated 中独立的沙箱用户边界，网络隔离也更弱。
  • 这是一个有用的回退方案，但不应作为企业环境中的长期首选配置。

如果你使用的是受管理企业电脑，长期最优解通常还是在 IT 团队协助下把 elevated 沙箱配置打通。

我看到了 Windows 错误 1385

如果沙箱中的命令以错误 1385 失败，说明 Windows 拒绝了沙箱用户启动命令所需的登录类型。

实践中，这通常意味着 Codex 已成功创建沙箱用户，但 Windows 策略仍然阻止这些用户启动沙箱命令。

可以这样处理：

  1. 请 IT 团队确认设备策略是否为 Codex 创建的沙箱用户授予了所需的登录权限。
  2. 如果只有部分机器或团队受影响，请比较相关 group policy 或 OU 差异。
  3. 如果你需要立即继续工作，可以先使用 unelevated 沙箱，同时排查策略问题。
  4. 同时提供 CODEX_HOME/.sandbox/sandbox.log、Windows 版本以及故障简述。
Codex 警告某些文件夹对 Everyone 可写

Codex 可能会警告某些文件夹可被 Everyone 写入。

如果出现这个警告，说明这些文件夹的 Windows 权限过宽，沙箱无法完全保护它们。

建议操作：

  1. 查看 Codex 在警告中列出的文件夹。
  2. 如果符合你的环境要求，移除这些文件夹对 Everyone 的写权限。
  3. 修正权限后，重启 Codex 或重新运行沙箱设置。

如果你不确定如何调整这些权限，请联系 IT 团队。

沙箱中的命令无法访问网络

取决于当前启用的权限模式，有些 Codex 任务本来就会在无出站网络访问的情况下运行。

如果任务因为无法联网而失败：

  1. 先确认该任务是否本来就应该在关闭网络的情况下运行。
  2. 如果你原本预期它可以联网，重启 Codex 后再试一次。
  3. 如果问题持续存在，请收集沙箱日志，让团队检查机器是否处于部分损坏或配置不完整的沙箱状态。
沙箱以前能用，后来失效了

这种情况可能发生在以下变化之后：

  • 移动了仓库或工作区
  • 修改了机器权限
  • 修改了 Windows 策略
  • 或其他系统配置变化

可以尝试：

  1. 重启 Codex。
  2. 重新执行 elevated 沙箱设置。
  3. 如果仍然无法解决，临时切换到 unelevated 作为回退方案。
  4. 收集沙箱日志供进一步审查。
我需要把诊断信息发送给 OpenAI

如果问题仍然存在，请发送：

  • CODEX_HOME/.sandbox/sandbox.log

同时附上这些信息也会很有帮助：

  • 你当时试图执行的操作简述
  • elevated 沙箱是失败了，还是实际使用了 unelevated
  • 应用中显示的错误信息
  • 是否看到了 1385 或其他 Windows / PowerShell 错误
  • 你使用的是 Windows 11 还是 Windows 10

不要发送：

  • CODEX_HOME/.sandbox-secrets/ 中的内容
IDE 扩展已安装，但没有响应

你的系统可能缺少某些原生依赖所需的 C++ 开发工具：

  • Visual Studio Build Tools（C++ workload）
  • Microsoft Visual C++ Redistributable（x64）
  • 如果使用 winget，可执行 winget install --id Microsoft.VisualStudio.2022.BuildTools -e

安装完成后，请完整重启 VS Code。

WSL 中的大型仓库感觉很慢
  • 确保你不是在 /mnt/c 下工作。把仓库移动到 WSL 内，例如 ~/code/...。
  • 如有需要，增加 WSL 的内存和 CPU；同时把 WSL 更新到最新版本：
wsl --update
wsl --shutdown
WSL 中的 VS Code 找不到 codex

请先确认二进制在 WSL 内存在且位于 PATH 中：

which codex || echo "codex not found"

如果没有找到，请按上面的在 WSL 中使用 Codex CLI重新安装。

来源：https://developers.openai.com/codex/windows