在 Windows 上使用 Codex

Codex 在 Windows 上有三个入口：

顶层 Windows 页讲的是平台选择、Windows sandbox、WSL2、版本要求和排错。具体 Windows App 的下载、设置、terminal、developer tools 和 App 内常见问题，见 42 Windows App。

官方页面：

三种运行方式

方式	适合场景	说明
Windows native + `elevated` sandbox	标准 Windows 开发环境、企业部署、重视隔离边界	推荐方式。使用低权限 sandbox users、文件系统权限边界、firewall rules 和 local policy。
Windows native + `unelevated` sandbox	管理员批准、企业策略或本机权限阻止 `elevated` setup	fallback 方式。使用当前用户派生的 restricted Windows token、ACL 文件边界和环境级 offline controls。隔离弱于 `elevated`。
WSL2	项目和工具链本来就在 Linux 环境，或 native sandbox 无法满足需要	在 Windows Subsystem for Linux 2 内运行 Codex，使用 Linux sandbox implementation。

如果两个 native sandbox 都可用，优先选 elevated。如果默认 native sandbox 在你的机器上失败，再临时退到 unelevated 排查。

Windows sandbox

Codex 原生运行在 Windows 时，agent mode 会用 Windows sandbox 限制写入范围，并在没有明确批准时阻止网络访问。

配置写在 config.toml：

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

默认情况下，两个 sandbox mode 都会使用 private desktop，增强 UI isolation。只有遇到兼容性问题时，才考虑关闭：

[windows]
sandbox_private_desktop = false

关闭后会回到较旧的 Winsta0\\Default 行为。

权限边界

full access mode 会让 Codex 不再只受 project directory 限制，可能执行非预期 destructive actions，导致 data loss。

更稳的做法：

保留 sandbox boundaries。
用 rules 针对具体目录或命令放行。
需要少打断的自动化场景，再结合 approval policy: never 和 approval and security setup 设计边界。

Windows 版本要求

Windows version	Support level	Notes
Windows 11	Recommended	推荐基线。企业标准化部署优先选 Windows 11。
Recent, fully updated Windows 10	Best effort	可以尝试，但可靠性低于 Windows 11。Windows 10 需要 modern console support，包括 ConPTY；实践上至少需要 Windows 10 version 1809。
Older Windows 10 builds	Not recommended	更容易缺少 ConPTY 等 console 组件，也更容易在企业环境 setup 失败。

额外前提：

winget 应该可用。缺失时先更新 Windows，或安装 Windows Package Manager。
推荐的 native sandbox 依赖 administrator-approved setup。
部分 enterprise-managed devices 会阻止本地用户、组、firewall 或 logon rights 相关设置。

给 sandbox 增加只读目录

如果命令失败是因为 Windows sandbox 不能读取某个目录，可以在 Codex 中使用：

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

要求：

路径必须是已经存在的 absolute directory。
命令成功后，当前 session 后续 sandboxed commands 可以读取这个目录。

什么时候选 WSL2

默认优先使用 native Windows sandbox。它在 Windows 上性能更好，也能保留平台级安全边界。

选择 WSL2 的典型场景：

你的项目、依赖和运行命令已经在 WSL2。
你需要 Linux-native tooling。
native elevated 和 unelevated 都不能满足当前机器策略。
你希望 VS Code、terminal、Codex CLI 都在同一个 Linux filesystem 中工作。

WSL1 支持到 Codex 0.114。从 Codex 0.115 开始，Linux sandbox 切到 bubblewrap，WSL1 不再支持。

在 WSL 中启动 VS Code

详细教程见 VS Code 官方文档：

前置条件：

Windows 已安装 WSL。管理员 PowerShell 中可以运行：
```
wsl --install
```
VS Code 已安装 WSL extension。

从 WSL shell 打开项目：

cd ~/code/your-project
code .

确认 VS Code 已连接 WSL：

状态栏显示 WSL: <distro>。
integrated terminal 中是 /home/... 这类 Linux 路径，而不是 C:\。
可以运行：
```
echo $WSL_DISTRO_NAME
```

如果没看到 WSL: ...，按 Ctrl+Shift+P，选择 WSL: Reopen Folder in WSL。

如果 Windows App 或 project picker 看不到 WSL repo，在 file picker 或 Explorer 输入：

\\wsl$

然后进入对应 distro 的 home directory。

在 WSL 中使用 Codex CLI

先从 elevated PowerShell 或 Windows Terminal 安装并进入 WSL：

wsl --install
wsl

再从 WSL shell 安装 Node.js 和 Codex CLI：

# https://learn.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-wsl
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash

# 打开新 tab，或退出后重新运行 `wsl`
nvm install 22

npm i -g @openai/codex
codex

WSL 项目位置

不要把主要开发目录放在 /mnt/c/... 下。更建议放到 WSL home directory：

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

原因：

/mnt/c/... 的 I/O 往往更慢。
symlink 和权限问题更容易出现。
Linux 工具链在 /home/... 下更稳定。

如果要从 Windows Explorer 访问 WSL 文件，路径通常是：

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

排错 and FAQ

Native sandbox setup failed

常见原因：

UAC 或 administrator prompt 被拒绝。
机器不允许创建 local users 或 groups。
机器不允许修改 firewall rules。
机器阻止 sandbox users 所需的 logon rights。
enterprise policy 阻止 setup flow 的一部分。

处理顺序：

重新尝试 elevated sandbox setup，并批准 administrator prompt。
如果是公司电脑，问 IT 是否允许 local user/group creation、firewall configuration 和 sandbox-user logon rights。
如果仍然失败，临时使用 unelevated sandbox 继续工作。

Codex switched me to the unelevated sandbox

这表示 Codex 没能完成更强的 elevated sandbox setup。

unelevated 仍然是 sandboxed mode，也会应用 ACL-based filesystem boundaries，但没有 elevated 的独立 sandbox-user boundary，network isolation 也更弱。

长期看，enterprise laptop 应该让 IT 协助把 elevated sandbox 跑通。

Windows error 1385

错误 1385 表示 Windows 拒绝 sandbox user 启动命令所需的 logon type。

这通常意味着 Codex 已经创建 sandbox users，但 Windows policy 仍然阻止这些用户启动 sandboxed commands。

处理顺序：

问 IT 当前 device policy 是否给 Codex-created sandbox users 授予所需 logon rights。
如果只有部分机器或团队受影响，对比 group policy 或 OU 差异。
临时使用 unelevated sandbox。
向 OpenAI 提供 CODEX_HOME/.sandbox/sandbox.log、Windows version 和失败描述。

Folders are writable by Everyone

如果 Codex 提示某些 folders 对 Everyone 可写，说明这些目录权限过宽，sandbox 无法完整保护。

处理方式：

查看 Codex warning 中列出的 folders。
在环境允许时移除 Everyone write access。
修正权限后重启 Codex，或重新运行 sandbox setup。

企业机器上不确定怎么改权限时，交给 IT 处理。

Sandboxed commands cannot reach the network

部分 Codex 任务会按权限模式禁用 outbound network access。

排查顺序：

先判断这个任务是否本来就应该在 network disabled 状态下运行。
如果你预期应该联网，重启 Codex 后再试。
如果持续出现，收集 sandbox log，检查机器是否处于部分 setup 或 broken sandbox state。

Sandboxing worked before and then stopped

常见触发：

移动 repo 或 workspace。
修改 machine permissions。
修改 Windows policies。
其他系统配置变化。

处理顺序：

重启 Codex。
重新尝试 elevated sandbox setup。
失败时临时使用 unelevated sandbox。
收集 sandbox log。

Send diagnostics

如果还无法解决，发送：

CODEX_HOME/.sandbox/sandbox.log

附带信息：

你当时要做什么。
elevated sandbox 是否失败，或是否使用了 unelevated。
App 显示的 error message。
是否看到 1385 或其他 Windows / PowerShell error。
Windows 11 还是 Windows 10。

不要发送：

CODEX_HOME/.sandbox-secrets/ 的内容。

IDE extension is installed but unresponsive

系统可能缺少 native dependencies 所需的 C++ tools：

Visual Studio Build Tools，选择 C++ workload。
Microsoft Visual C++ Redistributable (x64)。

用 winget 安装：

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

安装后完整重启 VS Code。

Large repositories feel slow in WSL

先确认 repo 不在 /mnt/c：

wsl --update
wsl --shutdown

然后把 repo 移到 ~/code/...。

VS Code in WSL cannot find codex

在 WSL 中确认 codex 是否在 PATH：

which codex || echo "codex not found"

如果找不到，回到在 WSL 中使用 Codex CLI 的安装步骤。

On this page