Codex Windows 使用指南

本文档翻译并整理自 Codex Windows 使用说明，用于记录在 Windows 上使用 Codex app、CLI、IDE extension、原生 Windows sandbox 和 WSL2 的注意事项。

注意： 涉及 Codex app、CLI、IDE extension、sandbox 策略、企业设备策略等信息时，以 OpenAI 官方文档和当前账号实际界面为准。本文最后核对日期为 2026-05-26。

概览

Windows 上可以通过三种方式使用 Codex：

Windows 版 Codex app 支持核心工作流，例如：

并行 agent 线程
worktree
automations
Git 功能
in-app browser
artifact previews
plugins
skills

根据使用入口和本机环境，Codex 在 Windows 上主要有三种运行方式：

原生 Windows + 更强的 elevated sandbox
原生 Windows + 兜底的 unelevated sandbox
在 Windows Subsystem for Linux 2（WSL2）中运行，使用 Linux sandbox 实现

Windows Sandbox

当 Codex 原生运行在 Windows 上时，agent mode 会使用 Windows sandbox，限制命令在工作目录之外写入文件，并在没有明确批准时阻止网络访问。

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

1 2	[windows] sandbox = "elevated" # 或 "unelevated"

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

unelevated 是兜底的 Windows 原生 sandbox。它使用从当前用户派生的受限 Windows token、基于 ACL 的文件系统边界，以及环境级离线控制，而不是 elevated 模式中专用离线用户的防火墙规则。它比 elevated 弱，但当管理员批准的 setup 被本地策略或企业策略阻止时，仍然有用。

如果两种模式都可用，优先使用 elevated。如果默认原生 sandbox 在当前环境中无法工作，可以临时使用 unelevated，同时排查 setup 问题。

默认情况下，两种 sandbox 模式都会使用 private desktop 来获得更强的 UI 隔离。只有在兼容性需要旧的 Winsta0\Default 行为时，才设置：

1 2	[windows] sandbox_private_desktop = false

Sandbox 权限

以 full access mode 运行 Codex 意味着 Codex 不再受限于项目目录，可能执行非预期的破坏性操作并造成数据丢失。为了更安全的自动化，建议保留 sandbox 边界，并用 rules 配置特定例外。

也可以根据 approval and security setup 调整审批策略，例如设置 approval policy 为 never，让 Codex 在不请求提升权限的情况下尽力解决问题。

Windows 版本矩阵

Windows 版本	支持级别	说明
Windows 11	推荐	Codex on Windows 的最佳基线。企业标准化部署优先选择。
最近且完整更新的 Windows 10	尽力支持	可以工作，但可靠性不如 Windows 11。Windows 10 依赖现代控制台能力，包括 ConPTY。实践中要求 Windows 10 1809 或更高版本。
较旧 Windows 10 构建	不推荐	更可能缺少 ConPTY 等必需控制台组件，也更容易在企业环境中失败。

其他环境假设：

winget 应可用。如果缺失，请更新 Windows，或先安装 Windows Package Manager。
推荐的原生 sandbox 依赖管理员批准的 setup。
某些企业托管设备即使 OS 版本满足要求，也可能阻止所需 setup 步骤。

授予 Sandbox 读取目录权限

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

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

路径必须是已存在的绝对目录。命令成功后，本会话中后续 sandbox 命令可以读取该目录。

默认优先使用原生 Windows sandbox。原生 Windows sandbox 在保持安全边界的同时，通常有更好的性能和速度。只有在需要 Linux-native 环境、工作流已经在 WSL2 中，或两个原生 Windows sandbox 模式都无法满足需求时，再选择 WSL2。

Windows Subsystem for Linux

如果选择 WSL2，Codex 会运行在 Linux 环境中，而不是使用原生 Windows sandbox。这适用于需要 Linux-native 工具链、仓库和开发流程已经在 WSL2 中，或原生 Windows sandbox 无法满足需求的情况。

Codex 0.114 及以前支持 WSL1。从 Codex 0.115 开始，Linux sandbox 迁移到 bubblewrap，因此不再支持 WSL1。

如果在 Windows 上使用 Codex IDE extension，并希望优先让 agent 运行在 WSL2 内，可以在 VS Code settings 中设置：

1
2
3

{
  "chatgpt.runCodexInWindowsSubsystemForLinux": true
}

这样可以让 IDE extension 在可用时继承 WSL2 的 Linux sandbox 语义，避免同一个项目同时混用 Windows 和 WSL 工具链。

从 WSL 中启动 VS Code

详细步骤可参考 VS Code WSL 官方教程。

前置条件

Windows 已安装 WSL。安装方式：以管理员身份打开 PowerShell，运行 wsl --install，常见发行版是 Ubuntu。
VS Code 已安装 WSL extension。

从 WSL 终端打开 VS Code

1
2
3

# 在 WSL shell 中
cd ~/code/your-project
code .

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

确认已连接到 WSL

确认方式：

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

1	echo $WSL_DISTRO_NAME

该命令会输出当前发行版名称。

如果状态栏没有显示 WSL: ...，按 Ctrl+Shift+P，选择 WSL: Reopen Folder in WSL。为了最佳性能，仓库应放在 /home/... 下，而不是 C:\ 下。

如果 Windows app 或项目选择器里看不到 WSL 仓库，可以在文件选择器或 Explorer 中输入：

\\wsl$

然后进入对应发行版的 home 目录。

在 WSL 中使用 Codex CLI

先在管理员 PowerShell 或 Windows Terminal 中执行：

# 安装默认 Linux 发行版，例如 Ubuntu
wsl --install

# 启动 WSL shell
wsl

再在 WSL shell 中执行：

# https://learn.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-wsl
# 通过 nvm 在 WSL 中安装 Node.js
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash

# 打开新终端，或退出后重新进入 wsl，再安装 Node.js
nvm install 22

# 在 WSL 中安装并运行 Codex
npm i -g @openai/codex
codex

在 WSL 中开发代码

在 Windows 挂载路径下工作，例如 /mnt/c/...，通常比 Windows 原生路径更慢。建议把仓库放在 Linux home 目录下，例如 ~/code/my-app，以获得更快 I/O，并减少符号链接和权限问题：

1
2
3

mkdir -p ~/code && cd ~/code
git clone https://github.com/your/repo.git
cd repo

如果需要从 Windows 访问这些文件，可以在 Explorer 中进入：

1	\\wsl$\Ubuntu\home\<user>

Troubleshooting 和 FAQ

如果在企业托管 Windows 机器上排查问题，优先从原生 sandbox 模式、Windows 版本和 Codex 显示的策略错误开始。大多数 Windows 原生支持问题来自 sandbox setup、logon rights 或文件系统权限，而不是编辑器本身。

原生 Sandbox Setup 失败

如果 Codex 无法完成 elevated sandbox setup，最常见原因包括：

Windows UAC 或管理员提示被拒绝。
机器不允许创建本地用户或用户组。
机器不允许修改防火墙规则。
机器阻止 sandbox 用户所需的 logon rights。
其他企业策略阻止了部分 setup 流程。

可以尝试：

重新尝试 elevated sandbox setup，并在环境允许时批准管理员提示。
如果公司电脑阻止该操作，询问 IT 团队设备是否允许管理员批准的本地用户/用户组创建、防火墙配置和 sandbox 用户 logon rights。
如果默认 setup 仍失败，先使用 unelevated sandbox 继续工作，同时排查问题。

Codex 切换到了 Unelevated Sandbox

这表示 Codex 无法在当前机器上完成更强的 elevated sandbox setup。

Codex 仍能以 sandbox 模式运行。
它仍会应用基于 ACL 的文件系统边界。
它不使用 elevated 模式中的独立 sandbox 用户边界，网络隔离也更弱。
这是一种可用的兜底方案，但不是推荐的长期企业配置。

如果是企业托管笔记本，长期解决方案通常是让 IT 团队协助使 elevated sandbox 正常工作。

出现 Windows Error 1385

如果 sandbox 命令失败，并出现错误 1385，说明 Windows 拒绝了 sandbox 用户启动命令所需的 logon type。

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

处理方式：

询问 IT 团队，设备策略是否授予 Codex 创建的 sandbox 用户所需 logon rights。
如果只影响部分机器或团队，比较 group policy 或 OU 差异。
如果需要立即继续工作，先使用 unelevated sandbox。
发送 CODEX_HOME/.sandbox/sandbox.log，并附带 Windows 版本和简短故障描述。

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

Codex 可能提示某些文件夹可被 Everyone 写入。

如果看到这个警告，说明这些文件夹的 Windows 权限过宽，sandbox 无法完整保护它们。

处理方式：

检查 Codex 警告中列出的文件夹。
如果环境允许，移除这些文件夹的 Everyone 写权限。
修正权限后重启 Codex，或重新运行 sandbox setup。

如果不确定如何修改这些权限，请让 IT 团队协助。

Sandboxed 命令无法访问网络

根据权限模式不同，某些 Codex 任务会故意在没有出站网络访问的情况下运行。

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

确认该任务是否本来应该在禁用网络的情况下运行。
如果预期应该有网络访问，重启 Codex 后再试。
如果问题持续出现，收集 sandbox log，方便检查机器是否处于部分损坏的 sandbox 状态。

Sandbox 之前正常，后来停止工作

可能原因包括：

移动了 repo 或 workspace。
修改了机器权限。
修改了 Windows 策略。
其他系统配置变化。

可以尝试：

重启 Codex。
重新尝试 elevated sandbox setup。
如果仍无法修复，临时使用 unelevated sandbox。
收集 sandbox log 供排查。

需要向 OpenAI 发送诊断信息

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

1	CODEX_HOME/.sandbox/sandbox.log

同时建议附带：

正在尝试做什么。
elevated sandbox 是否失败，或是否使用了 unelevated sandbox。
app 中显示的错误信息。
是否出现 1385 或其他 Windows / PowerShell 错误。
当前使用 Windows 11 还是 Windows 10。

不要发送：

1	CODEX_HOME/.sandbox-secrets/

IDE Extension 已安装但无响应

系统可能缺少 C++ 开发工具，部分 native dependencies 需要这些工具：

Visual Studio Build Tools（C++ workload）
Microsoft Visual C++ Redistributable（x64）

使用 winget 安装：

1	winget install --id Microsoft.VisualStudio.2022.BuildTools -e

安装后完全重启 VS Code。

大仓库在 WSL 中很慢

检查是否在 /mnt/c 下工作。应把仓库移动到 WSL 文件系统中，例如：

1	~/code/...

必要时增加 WSL 的内存和 CPU，或更新 WSL：

1 2	wsl --update wsl --shutdown

VS Code in WSL 找不到 Codex

检查 WSL 中是否存在 codex，并确认它在 PATH 中：

1	which codex \|\| echo "codex not found"

如果找不到二进制文件，按本文在 WSL 中使用 Codex CLI 小节重新安装。

参考链接

Codex Windows: https://developers.openai.com/codex/windows
Codex CLI: https://developers.openai.com/codex/cli
Codex IDE: https://developers.openai.com/codex/ide
Agent approvals and security: https://developers.openai.com/codex/agent-approvals-security
Codex rules: https://developers.openai.com/codex/rules
WSL install: https://learn.microsoft.com/en-us/windows/wsl/install
VS Code WSL tutorial: https://code.visualstudio.com/docs/remote/wsl-tutorial

迭代记录

2026-05-26：按 OpenAI Codex Windows 和 sandbox 官方说明复核原生 Windows sandbox、WSL2、WSL1 支持边界和 IDE extension 运行位置；补充 chatgpt.runCodexInWindowsSubsystemForLinux 设置，并更新 Windows 官方参考链接。
2026-05-15：初始化 Codex Windows 使用指南，整理 Codex app、CLI、IDE extension、Windows sandbox、WSL2 和常见排障。