跳到主要内容

本文为非官方中文翻译，内容以 OpenAI 官方英文文档为准。
官方来源：https://developers.openai.com/codex/windows

Windows

在 Windows 上运行 Codex 的提示

可通过原生 Codex app、CLI 或 IDE extension 在 Windows 上使用 Codex。

Windows 上的 Codex app 支持并行 agent 线程、worktrees、自动化、Git 功能、应用内浏览器、artifact 预览、插件和 skills 等核心工作流。

根据使用界面和你的设置，Codex 在 Windows 上有三种实用的运行方式：

  • 在 Windows 上原生运行，并使用更强的 elevated sandbox，
  • 在 Windows 上原生运行，并使用后备的 unelevated sandbox，
  • 或在 Windows Subsystem for Linux 2 (WSL2) 中运行，此时使用 Linux sandbox 实现。

Windows sandbox​

当你在 Windows 上原生运行 Codex 时，agent mode 会使用 Windows sandbox 来阻止对工作文件夹之外的文件系统写入，并在未经你明确批准的情况下阻止网络访问。

原生 Windows sandbox 支持两种可在 config.toml 中配置的模式：

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

elevated 是首选的原生 Windows sandbox。它使用专用的低权限 sandbox 用户、文件系统权限边界、防火墙规则，以及 sandbox 中运行命令所需的本地策略更改。

unelevated 是后备的原生 Windows sandbox。它使用从当前用户派生的受限 Windows token 运行命令，应用基于 ACL 的文件系统边界，并使用环境级离线控制来代替专用离线用户防火墙规则。它比 elevated 更弱，但当本地或企业策略阻止管理员批准的设置时，仍然很有用。

如果两种模式都可用，请使用 elevated。如果默认的原生 sandbox 在你的环境中无法工作，请在排查设置问题时使用 unelevated 作为后备方案。

默认情况下，两种 sandbox 模式也都会使用 private desktop 来提供更强的 UI 隔离。仅当你因兼容性需要较旧的 Winsta0\\Default 行为时，才将 windows.sandbox_private_desktop = false。

Sandbox 权限​

以完全访问模式运行 Codex 意味着 Codex 不再局限于你的项目目录，并且可能执行无意的破坏性操作，从而导致数据丢失。为了更安全的自动化，请保留 sandbox 边界，并使用 rules 为特定例外进行配置，或者将你的审批策略设为 never，让 Codex 根据你的审批与安全设置尝试在不请求提升权限的情况下解决问题。

Windows 版本矩阵​

Windows versionSupport levelNotes
Windows 11推荐作为 Windows 上运行 Codex 的基础环境最佳。如果你要标准化企业部署，请使用此版本。
Recent, fully updated Windows 10尽力支持可以工作，但可靠性不如 Windows 11。对于 Windows 10，Codex 依赖现代控制台支持，包括 ConPTY。实际上，需要 Windows 10 1809 或更高版本。
Older Windows 10 builds不推荐更可能缺少所需的控制台组件（如 ConPTY），并且在企业环境中更容易失败。

附加环境假设：

  • 应可使用 winget。如果缺失，请更新 Windows 或先安装 Windows Package Manager，再设置 Codex。
  • 推荐的原生 sandbox 依赖管理员批准的设置。
  • 某些企业管理设备即使 OS 版本本身可接受，也会阻止所需的设置步骤。

授予 sandbox 读取权限​

当某个命令因 Windows sandbox 无法读取某个目录而失败时，请使用：

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

该路径必须是现有的绝对目录。命令成功后，在当前会话期间，之后在 sandbox 中运行的命令即可读取该目录。

默认使用原生 Windows sandbox。原生 Windows sandbox 在保持相同安全性的同时提供最佳性能和最高速度。当你需要 Windows 上的 Linux 原生环境、你的工作流已在 WSL2 中运行，或者原生 Windows sandbox 的两种模式都无法满足你的需求时，请选择 WSL2。

Windows Subsystem for Linux​

如果你选择 WSL2，Codex 将在 Linux 环境中运行，而不是使用原生 Windows sandbox。如果你在 Windows 上需要 Linux 原生工具链、你的仓库和开发者工作流已经位于 WSL2 中，或者原生 Windows sandbox 的两种模式都不适用于你的环境，这会很有用。

WSL1 在 Codex 0.114 之前都受支持。从 Codex 0.115 开始，Linux sandbox 已迁移到 bubblewrap，因此不再支持 WSL1。

从 WSL 内部启动 VS Code​

有关分步说明，请参阅官方 VS Code WSL 教程。

前提条件​

  • 已安装 WSL 的 Windows。要安装 WSL，请以管理员身份打开 PowerShell，然后运行 wsl --install（Ubuntu 是一个常见选择）。
  • 已安装 WSL extension 的 VS Code。

从 WSL 终端打开 VS Code​

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

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

确认你已连接到 WSL​

  • 查看显示 WSL: 的绿色状态栏。

  • 集成终端应显示 Linux 路径（如 /home/...），而不是 C:\。

  • 你可以通过以下命令验证：

    echo $WSL_DISTRO_NAME

    这将输出你的发行版名称。

如果你没有在状态栏中看到“WSL: ...”，请按 Ctrl+Shift+P，选择 WSL: Reopen Folder in WSL，并将你的仓库放在 /home/... 下（而不是 C:\）以获得最佳性能。

如果 Windows app 或项目选择器没有显示你的 WSL 仓库，请在文件选择器或资源管理器中输入 \wsl$，然后导航到你的发行版主目录。

在 WSL 中使用 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

在 WSL 中处理代码​

  • 在 Windows 挂载路径（如 /mnt/c/...）中工作，可能比在 Windows 原生路径中工作更慢。请将仓库保存在 Linux 主目录下（如 ~/code/my-app），以获得更快的 I/O，并减少符号链接和权限问题： 
    mkdir -p ~/code && cd ~/code
    git clone https://github.com/your/repo.git
    cd repo
  • 如果你需要从 Windows 访问文件，它们位于资源管理器中的 \wsl$\Ubuntu\home<user> 下。

故障排查和 FAQ​

如果你正在排查受管理的 Windows 机器，请先检查原生 sandbox 模式、Windows 版本，以及 Codex 显示的任何策略错误。大多数原生 Windows 支持问题都来自 sandbox 设置、登录权限或文件系统权限，而不是编辑器本身。

原生 sandbox 设置失败

如果 Codex 无法完成 elevated sandbox 设置，最常见的原因是：

  • Windows UAC 或管理员提示被拒绝，
  • 机器不允许创建本地用户或组，
  • 机器不允许更改防火墙规则，
  • 机器阻止 sandbox 用户所需的登录权限，
  • 或其他企业策略阻止了设置流程的一部分。

可尝试的方法：

  1. 再次尝试 elevated sandbox 设置，并在你的环境允许时批准管理员提示。
  2. 如果你的公司笔记本阻止此操作，请询问 IT 团队该机器是否允许管理员批准以下设置：创建本地用户/组、防火墙配置，以及所需的 sandbox 用户登录权限。
  3. 如果默认设置仍然失败，请使用 unelevated sandbox，以便你在调查问题期间继续工作。

Codex 将我切换到了非提权沙箱

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

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

如果你使用的是受管理的企业笔记本电脑，最佳的长期修复方法通常是在 IT 团队的帮助下让 elevated 沙箱正常工作。

我看到了 Windows 错误 1385

如果沙箱命令因错误 1385 失败，说明 Windows 正在拒绝 sandbox user 启动命令所需的登录类型。

在实际情况下，这通常意味着 Codex 已成功创建 sandbox user，但 Windows 策略仍在阻止这些用户启动沙箱命令。

该怎么做：

  1. 询问你的 IT 团队，设备策略是否向 Codex 创建的 sandbox user 授予了所需的登录权限。
  2. 如果问题只影响某些机器或团队，请比较组策略或 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. 如果问题持续发生，请收集沙箱日志，以便团队检查机器是否处于部分或损坏的沙箱状态。

沙箱之前可用，后来停止工作了

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

  • 移动了 repo 或工作区，
  • 更改了机器权限，
  • 更改了 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++ 工作负载）
  • 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"

如果找不到该二进制文件，请按照上文中的说明进行安装。