Windows 专题：
原生沙箱与 WSL2

你的 Windows 版本够不够

另外两个前提：Windows 自带的包管理器 winget 要能用，没有就先更新 Windows 或装 Windows Package Manager；推荐的沙箱需要管理员批准一次设置，有些公司管理的电脑即使系统版本够，也会拦住这一步（第 3 节讲）。手机 Remote 也能遥控 Windows 电脑（第 13 课）；Computer Use 在 Windows 上的限制见专题 E。

winget install --id 9PLM9XGG6VKS -s msstore

winget install --id Git.Git
winget install --id OpenJS.NodeJS.LTS
winget install --id Python.Python.3.14
winget install --id Microsoft.DotNet.SDK.10
winget install --id GitHub.cli

要别的 Python 或 .NET 版本，把包名里的版本号换掉就行。

Windows 上最常用的快捷键

快捷键的完整用法第 2 课讲。

顺手设好编辑器和终端

在 Settings 里可以选 Open（用什么打开文件）的默认程序，比如 Visual Studio、VS Code；每个项目还能单独改，你在某个项目的 Open 菜单里选过别的程序，就以那个为准。

集成终端也能选默认的：PowerShell、Command Prompt、Git Bash 或 WSL，看你电脑上装了哪些。这个设置只对新开的终端生效；已经开着的终端，要重启 App 或开个新对话才会换。终端和 agent（替你跑命令的那个 Codex）是分开设置的，第 6 节细说。

换成术语：elevated 用的是 Codex 专门建的低权限沙箱用户，加上文件系统权限边界、防火墙规则和几项本机策略；unelevated 用的是从你当前用户派生出来的受限令牌（restricted token），靠 ACL（文件访问控制列表）划边界。点下面切换，对比三种围挡。

它管住的是所有命令

沙箱不只管 Codex 自己改文件。它启动的每条命令，比如 git、npm、跑测试，都继承同样的边界。所以在围挡里，常规的读文件、改文件、跑项目命令它自己就能做；要越界，才停下来问你。

在配置文件里指定模式

[windows]
sandbox = "elevated"      # 推荐
# sandbox = "unelevated"  # 没有管理员权限、或 elevated 设置失败时的后备

两种都能用就选 elevated；默认的原生沙箱在你这儿跑不起来，先用 unelevated 顶上，同时排查。配置文件怎么写、放哪、优先级怎么算，第 7 课讲。

画面为教学示意：沙箱设置提示的文字和按钮、Codex 说的话、测试数量都是虚构的；报错原文、修复命令、安装命令与官方文档一致。

还没装 WSL 的，用管理员身份打开 PowerShell，运行 wsl --install（常见的选择是 Ubuntu）。注意只支持 WSL2：Linux 沙箱换成 bubblewrap 之后，WSL1 就不再支持了。

选一种组合，看怎么放

让 agent 跑在 WSL2 里

1. 打开 Settings，把 agent 从 Windows native 切到 WSL。
2. 重启 App。不重启不生效。项目会留在原处，不用重新添加。
3. WSL2 里用的是 Linux 沙箱，要先装 bubblewrap（Linux 上做沙箱隔离的工具）：sudo apt install bubblewrap（Fedora 用 sudo dnf install bubblewrap）。缺了它，Codex 启动时会警告。

agent 和集成终端是分开设置的：可以 agent 在 WSL、终端用 PowerShell，也可以两边都用 WSL，看你习惯。

在 WSL 里用 CLI，想和 App 共用设置

Windows 上的 App 和原生 Codex 共用 %USERPROFILE%\.codex 这个目录。WSL 里的 CLI 默认用 Linux 的家目录，所以配置、登录缓存、会话记录都不自动共享。两个办法：把 WSL 的 ~/.codex 和 %USERPROFILE%\.codex 同步；或者在 WSL 里把 CODEX_HOME 指向 Windows 那个目录：

export CODEX_HOME=/mnt/c/Users/<windows-user>/.codex

把 <windows-user> 换成你的 Windows 用户名。CODEX_HOME 指向的目录必须已经存在。

VS Code 扩展

在 VS Code 的设置里打开下面这项，有 WSL 时 Codex 就在 WSL2 里跑，命令、审批、文件访问都按 Linux 沙箱的规矩来。改了会重新加载 VS Code。VS Code 本身也建议从 WSL 里打开：在 WSL 的终端里进到项目目录，运行 code .，连上以后状态栏会显示 WSL: 发行版名，终端里的路径也变成 /home/... 这样的 Linux 路径。

{
  "chatgpt.runCodexInWindowsSubsystemForLinux": true
}

脚本被执行策略拦住

如果你以前没在 PowerShell 里用过 Node.js、npm 这类工具，Codex 或集成终端第一次跑它们时，可能看到这样的报错：

意思是 PowerShell 的执行策略不让运行脚本。Codex 替你写的 PowerShell 脚本（.ps1）跑不起来，也是同一个原因。官方给的常见解法是把执行策略改成 RemoteSigned：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

需要管理员权限才能跑的命令

Codex 的 agent 继承 App 本身的权限。要让它用管理员权限跑命令，就得用管理员身份启动 App：在开始菜单里找到它，选 Run as administrator（以管理员身份运行）。Codex 的 agent 会继承这个权限级别。权限越大，出错时的代价越大，所以只在确实需要时这样打开，用完换回普通方式。

本地环境脚本

项目的本地环境（setup 脚本和 Actions，第 12 课讲）在 Windows 上照样能用。用的是 npm 脚本这类跨平台命令，所有系统共用一份就行；要 Windows 专用的行为，单独写 Windows 版的 setup 脚本或 Actions。注意两者跑的地方不一样：setup 脚本跑在 agent 的环境里（agent 在 WSL 就是 WSL，否则是 PowerShell），Actions 跑在集成终端的环境里。

装命令行版（CLI）

原生 Windows 上首选官方安装脚本，装和更新都是同一条命令：

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

• 也可以用 npm 装：npm install -g @openai/codex。
• 安装脚本默认把 codex 命令放在 %LOCALAPPDATA%\Programs\OpenAI\Codex\bin；想换位置，设 CODEX_INSTALL_DIR。
• 原生 CLI 和 App 共用 %USERPROFILE%\.codex，配置、登录都是同一份。
• 要装进 WSL2：在 WSL 的终端里运行 curl -fsSL https://chatgpt.com/codex/install.sh | sh，再运行 codex。

原生 Windows 的 CLI 里有一个 Windows 专用的斜杠命令：

文档里还写着 /sandbox-add-read-dir（给沙箱多开一个读目录），但本教程核对的版本里已经移除（见更新记录）。读不到目录的问题，按第 9 节收集 sandbox.log 发诊断。

CLI 的安装、参数和终端里的用法，第 14 课讲全；当前版本号见专题 A。

排查公司管理的 Windows 电脑时，官方建议先弄清三样：用的是哪种原生沙箱模式、Windows 版本、Codex 显示的策略报错。Windows 以外的问题，看专题 C。

自测：看到这个，第一步做什么

不看向导，你能选对吗？

Windows 专用的配置项

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

Windows sandbox 页还说：两种模式默认都把沙箱里的命令放到一个私有桌面（private desktop）上运行，把界面也隔离开；只有为了兼容旧的 Winsta0\Default 行为，才设 sandbox_private_desktop = false。不过 9 月 29 日之后的配置参考里已经没有这个键了，而 sandbox 多了第三个值 mxc，官方还没写它是什么。这两处先别改，等文档说清楚。

管理员可以锁定沙箱模式

公司管理员能在 requirements.toml（管理员强制的配置，第 7 课提到）里规定允许哪几种原生沙箱。下面这样写，就只能用 elevated，用户没法退到 unelevated：

[windows]
allowed_sandbox_implementations = ["elevated"]

两种都允许就把两个值都写上；这时如果没选模式，Codex 优先用 elevated。列表不能是空的。

在沙箱里试跑一条命令（命令行）

想知道某条命令放进沙箱会怎样，可以用 CLI 的沙箱辅助命令，它用的是和 Codex 内部一样的策略：

codex sandbox windows [--permissions-profile <name>] [COMMAND]...

给 OpenAI 发诊断

沙箱问题实在解决不了，把 CODEX_HOME/.sandbox/sandbox.log 发过去，再附上：你想做什么；是 elevated 设置失败了，还是在用 unelevated；App 里显示的报错；有没有看到 1385 或别的 Windows、PowerShell 报错；Windows 11 还是 10。不要发 CODEX_HOME/.sandbox-secrets/ 里的任何东西。分享日志前自己先看一遍，确认里面没有敏感信息。

公司统一部署

IT 可以用 Intune、SCCM 或别的管理工具统一安装和更新 App，有 x64 和 Arm64 两种离线 MSIX 包。具体步骤看官方的 Deploy the Windows app。

sudo apt update
sudo apt install apparmor-profiles apparmor-utils
sudo install -m 0644 \
  /usr/share/apparmor/extra-profiles/bwrap-userns-restrict \
  /etc/apparmor.d/bwrap-userns-restrict
sudo apparmor_parser -r /etc/apparmor.d/bwrap-userns-restrict