Codex Windows避坑指南：从安装到沙箱报错的完整排查手册

Codex CLI 是 OpenAI 推出的本地编码 agent，从 2026 年开始就原生支持 Windows 了。通过 PowerShell 一行命令就能安装，不再强制要求 WSL 或虚拟机。在 Windows 上运行时，Codex 会使用专门的 Windows 沙箱来限制文件写入范围并拦截网络访问。沙箱分为两种模式：elevated（独立低权限沙箱用户加上防火墙规则，官方首选）和 unelevated（受限令牌加 ACL 边界，企业策略受限时的回退方案）。实践中，Windows 用户最常踩的坑主要集中在五处：Microsoft Store 分发限制导致企业环境无法安装（对应 issue 获得 229 个赞，是全部 Windows 议题中最高的）、沙箱安装失败触发 Windows 错误 1385、Codex 修改文件后行尾统一变为 LF 导致 CRLF 项目混合换行、WSL 模式下 CODEX_HOME 仍指向 Windows 路径使 worktree 落在 /mnt/c 上拖慢 Git 操作，以及默认会话 shell 锁定 PowerShell 无法切换 Git Bash。本文基于 OpenAI 官方文档与 GitHub Issue 区 25 个高赞 Windows 问题，逐条给出成因、官方配置和实际规避方案，并提供 Windows 10/11 版本支持矩阵与原生 vs WSL 的选型决策依据。

一、Codex 支持 Windows 原生运行吗？

Codex CLI 提供了官方的 Windows 安装脚本，通过 PowerShell 一行命令就能完成安装，不需要 WSL，也不需要虚拟机。

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

也可以走包管理器：

# npm（跨平台）
npm install -g @openai/codex

安装完成后，直接运行 codex 即可启动。

官方对原生运行的定位很明确：Codex 可以直接在 PowerShell 中原生运行，同时保留有边界的文件系统与网络权限。也就是说，原生模式不是“降级方案”，而是默认推荐路径。

：独立安装器默认从 https://releases.openai.com/codex 下载，如果元数据或资源下载不可用，会自动回退到 GitHub Releases。想强制走 GitHub Releases：

$env:CODEX_INSTALLER_USE_RELEASES_OPENAI_COM='false'; irm https://chatgpt.com/codex/install.ps1 | iex

二、坑位一：企业环境装不上（229 赞的头号痛点）

现象

Codex 的 Windows

目前仅通过 Microsoft Store 分发。大量用户因为系统限制、企业策略、离线环境或个人偏好，无法使用 Store 安装。这个诉求对应的 issue（#13993）获得了 229 个赞，是全部 Windows 相关议题中最高的，社区一直在要求提供 codex-setup.exe 或 .msi 独立安装包。

现状与规避

场景	可行方案
企业禁用 Microsoft Store	用 Codex CLI （PowerShell 脚本或 npm 安装），CLI 不依赖 Store
离线/隔离网络环境	从 GitHub Releases 下载对应平台二进制，手动放入 PATH
需要指定安装目录	走 npm 全局安装或手动解压二进制
需要脚本化批量部署	npm 或直接分发二进制，避免 Store 依赖

：桌面应用受 Store 限制，但 CLI 完全不受影响。企业环境优先部署 CLI。

三、坑位二：沙箱模式选错与 Windows 错误 1385

3.1 两种沙箱模式的区别

Codex 在 Windows 上的 agent 模式会用沙箱阻止工作目录之外的文件写入，并在未获明确批准时拦截网络访问。沙箱有两种实现：

模式	机制	定位
elevated	独立的低权限沙箱用户 + 文件系统权限边界 + 防火墙规则 + 本地策略修改	官方首选（preferred native Windows sandbox）
unelevated	从当前用户派生受限 Windows 令牌，施加 ACL 文件边界，用环境级离线控制替代专用防火墙规则	回退方案，强度弱于 elevated

官方对 unelevated 的表述是：“It’s weaker than elevated, but it is still useful when administrator-approved setup is blocked by local or enterprise policy.”

两种模式默认都启用私有桌面以强化 UI 隔离。

3.2 配置方式

在 config.toml 中显式选择：

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

仅在需要旧的 Winsta0Default 兼容行为时才关闭私有桌面：

windows.sandbox_private_desktop = false

企业管理员可通过 requirements.toml 限定允许的实现，禁止回退：

[windows]
allowed_sandbox_implementations = ["elevated"]

未显式选择时，Codex 优先使用 elevated。

3.3 Windows 错误 1385 怎么解决

：Windows 拒绝了沙箱用户启动命令所需的登录类型。通常沙箱用户已创建成功，但策略仍阻止其启动命令。

：

1. 请 IT 核查设备策略是否授予沙箱用户所需的登录权限
2. 若只影响部分机器或团队，对比组策略（GPO）或 OU 配置差异
3. 临时改用 unelevated 模式顶住，保证可用性
4. 提交诊断信息：CODEX_HOME/.sandbox/sandbox.log，附系统版本和简要说明

：提交日志时发送 CODEX_HOME/.sandbox-secrets/ 目录内容。

3.4 elevated 安装失败的其他原因

• UAC / 管理员提示被拒绝
• 机器不允许创建本地用户或组
• 不允许修改防火墙规则
• 阻断了沙箱用户所需的登录权限
• 其他企业策略拦截

处理顺序：重试并批准管理员提示 → 请 IT 确认设备策略 → 仍失败则用 unelevated。

四、坑位三：改文件后行尾 LF/CRLF 混乱

现象

Codex 修改文件时不遵循文件原有的行尾风格，始终使用 Unix 风格的 LF。在使用 CRLF 的 Windows 项目中，这会导致同一文件内混合换行符——Visual Studio 打开时会弹出警告，询问是否规范化行尾。该问题（issue #4003）获得了 72 个赞，截至 2026 年 7 月仍处于 open 状态。

规避方案

在仓库根目录创建或编辑 .gitattributes：

# 让 Git 在检出时按平台规范化，提交时统一存 LF
* text=auto

# 明确指定必须为 CRLF 的文件
*.bat text eol=crlf
*.cmd text eol=crlf
*.ps1 text eol=crlf

# 明确指定必须为 LF 的文件
*.sh text eol=lf

# Windows 上检出转 CRLF，提交转 LF
git config --global core.autocrlf true

在 .editorconfig 中声明期望行尾，让编辑器保存时自动修正：

root = true

[*]
end_of_line = crlf
insert_final_newline = true

[*.sh]
end_of_line = lf

：三个方案叠加使用最稳。.gitattributes 管 Git 层，.editorconfig 管编辑器层，两层同时兜住，Codex 写入的 LF 会在提交或保存时被规范化。

五、坑位四：WSL 模式下 worktree 跑到 /mnt/c

现象

Codex Desktop 安装在 Windows 且启用 WSL 模式时，WSL 侧的 app-server 会继承 Windows 的 CODEX_HOME（即 C:Users.codex），而不是使用 WSL 原生的 home 目录。结果是：即使仓库完整位于 WSL 内（例如 /home//Development/...），worktree 仍被解析到 /mnt/c/Users//.codex/worktrees/...。

：

1. worktree 创建在 Windows 挂载文件系统上，Git 操作显著变慢
2. 桌面应用可能保留指向 Windows 侧 worktree 路径的过期引用

该问题（issue #13762）获得了 54 个赞，另有相关议题 #13549（Codex App 在 WSL 模式下仍引用 Windows 侧 config.toml，34 赞）和 #14468（要求可配置 worktree 目录，26 赞）。

官方推荐做法

把仓库放在

下，而不是 /mnt/c 挂载路径：

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

官方明确指出，Linux home 目录能带来 “faster I/O and fewer symlink and permission issues”。

从 Windows 侧访问这些文件的路径是：\wsl$Ubuntuhome（在资源管理器地址栏输入 \wsl$ 即可进入）。

大仓库变慢的排查

# 确认当前不在 /mnt/c 下
pwd
# 更新 WSL 并重启
wsl --update
wsl --shutdown

必要时在 .wslconfig 中提高 WSL 的内存与 CPU 配额。

六、坑位五：默认 shell 锁定 PowerShell

现象

Codex 在 Windows 上默认使用 PowerShell 作为会话 shell。主要在 Git Bash 或其他 shell 中工作的用户，难以把自己的 shell 设为 Codex 默认。相关 issue（#16579，29 赞；#16717，34 赞）已提出配置方案。

社区提出的配置方案

[windows]
shell_path = "C:\Program Files\Git\bin\bash.exe"

配置后 Codex 用该可执行文件作为默认会话 shell；未配置时保持现有行为，仍回退 PowerShell。

（issue 作者给出的理由）：

• Windows 没有 Unix $SHELL 那样单一可靠的等价物
• PATH 上可能同时存在多个 bash.exe 变体（Git Bash、WSL、MSYS2 等）
• 显式配置更易推理和排查

：该配置项状态请以你所用版本的官方文档为准，若当前版本尚未合并，可通过 WSL 模式获得 Linux shell 环境作为替代。

七、原生 Windows 还是 WSL？决策依据

7.1 官方给出的选择条件

改用 WSL 的三个条件（满足任一即可考虑）：

1. 需要 Linux 原生工具链
2. 仓库与开发流程本就位于 WSL2 中
3. 两种原生沙箱模式（elevated / unelevated）都不适用于你的环境

7.2 对比表

维度	原生 Windows	WSL2
安装复杂度	一行 PowerShell 命令	需先装 WSL + 发行版
沙箱机制	Windows 沙箱（elevated/unelevated）	Linux 沙箱（bubblewrap）
工具链	Windows 原生	Linux 原生
文件 I/O	快（原生路径）	快（仅当仓库在 ~ 下）；慢（在 /mnt/c 下）
企业策略敏感度	高（沙箱需管理员批准）	中
已知坑位	沙箱 1385、行尾、Store 分发	CODEX_HOME 路径继承、worktree 位置

7.3 WSL 版本限制

• WSL1 支持截止于 Codex 0.114
• 从 0.115 起，Linux 沙箱迁移到 bubblewrap，官方原文：“WSL1 is no longer supported”

检查与升级：

wsl --list --verbose   # 查看 VERSION 列
wsl --set-version Ubuntu 2

7.4 WSL 安装 Codex 完整流程

在提权的 PowerShell 或 Windows Terminal 中：

# 安装默认 Linux 发行版（通常是 Ubuntu）
wsl --install
# 进入 WSL shell
wsl

在 WSL shell 中：

curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex

7.5 从 WSL 内启动 VS Code

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

：

1. 状态栏显示 WSL:
2. 集成终端显示 Linux 路径（/home/...）而非 C:
3. 校验命令 echo $WSL_DISTRO_NAME 有输出

若状态栏未显示，按 Ctrl+Shift+P 执行 WSL: Reopen Folder in WSL。

若 VS Code 在 WSL 中找不到 codex：

which codex || echo "codex not found"

八、Windows 版本支持矩阵

版本	支持级别	说明
Windows 11	✅ 推荐	企业标准化部署的最佳基线
较新且完整更新的 Windows 10	⚠️ 尽力支持	可用但不如 Win11 可靠；依赖现代控制台支持（含 ConPTY），实践中需 1809 或更新
更旧的 Windows 10	❌ 不推荐	更可能缺少 ConPTY 等必需控制台组件，企业环境中更易失败

：

• winget 应可用（缺失则更新 Windows 或先安装 Windows Package Manager）
• 推荐的原生沙箱依赖管理员批准的安装步骤
• 部分受管设备即使系统版本达标也会阻断所需步骤

九、其他高频问题速查

9.1 会话内临时放开目录读权限

/sandbox-add-read-dir C:absolutedirectorypath

路径必须是

。成功后当前会话中后续沙箱命令即可读取该目录。

9.2 IDE 扩展装了没反应

可能缺少 C++ 开发工具（部分原生依赖需要）：

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

需同时确认已安装 Microsoft Visual C++ Redistributable (x64)。安装后

（不是重载窗口）。

9.3 沙箱命令无法联网

排查顺序：

1. 确认该任务是否本应禁网（部分会话按权限模式设计就是禁网的）
2. 若预期有网络，重启 Codex 重试
3. 反复出现则收集沙箱日志，排查机器是否处于部分或损坏的沙箱状态

9.4 提示"某些文件夹对 Everyone 可写"

表示这些目录的 Windows 权限过宽，沙箱无法完全保护。处理：核对告警列出的目录 → 在环境允许时移除 Everyone 写权限 → 修正后重启 Codex 或重跑沙箱安装。

9.5 曾经可用后来失效

常见于仓库/工作区迁移、机器权限变更、Windows 策略变更或其他系统配置改动之后。

处理顺序：重启 Codex → 重试 elevated 安装 → 临时回退 unelevated → 收集日志。

9.6 Codex Desktop 在 Windows 上卡顿

社区已报告多起相关问题（#20214 卡顿/冻结获 73 赞，#23198 极慢获 46 赞，#33375 serialport.node 延迟加载失败导致严重 UI 卡顿获 30 赞）。当前可行的规避是改用

——CLI 不依赖 Electron 与桌面应用的原生模块加载链路，在 Windows 上表现更稳定。

9.7 bundled rg 报 Access Denied

Codex Desktop 中 rg 解析到应用包目录下的捆绑二进制（C:Program FilesWindowsApps...rg.exe），但从集成 PowerShell 调用时报 Access Denied（issue #13542，29 赞）。规避：自行安装 ripgrep 并确保其在 PATH 中优先级高于捆绑版本。

winget install BurntSushi.ripgrep.MSVC

十、权限风险提示

官方明确警告：

更安全的两种做法：

1. 保留沙箱边界 + 用 rules 开特例
   —— 只对确实需要的路径放行

2. 把 approval policy 设为 never
   —— 让 Codex 不请求提权地尝试解决问题，而不是每次都弹窗诱导你批准全权限

不建议为了省事直接开全权限，尤其在包含生产配置或凭据的机器上。

十一、FAQ

Q1：Windows 上必须用 WSL 才能跑 Codex 吗？

A：不需要。Codex CLI 提供原生 Windows PowerShell 安装脚本，官方将原生模式列为默认推荐。只有在需要 Linux 原生工具链、仓库本就在 WSL2 内、或两种原生沙箱模式都不适用时才改用 WSL。

Q2：Windows 10 能用吗？

A：较新且完整更新的 Windows 10 属于"尽力支持"，实践中需 1809 或更新版本（依赖 ConPTY 控制台组件）。更旧的 Windows 10 不推荐。Windows 11 是官方推荐基线。

Q3：公司禁用了 Microsoft Store，怎么装 Codex？

A：Store 限制只影响桌面应用。用 Codex CLI 即可绕过——PowerShell 安装脚本、npm 全局安装、或从 GitHub Releases 下载二进制三种方式都不依赖 Store。

Q4：沙箱报 1385 错误，一定要联系 IT 吗？

A：根治需要 IT 授予沙箱用户所需的登录权限。但可以先在 config.toml 中把 sandbox 改为 "unelevated" 临时恢复可用性——仍在沙箱内运行、仍有 ACL 文件边界，只是缺少独立沙箱用户边界且网络隔离更弱。

Q5：Codex 改完文件行尾乱了，会影响 Git 提交吗？

A：会。混合行尾会导致 diff 出现大量无意义变更。建议用 .gitattributes（* text=auto 加按扩展名指定 eol）配合 .editorconfig 双层兜底，让 Git 和编辑器在提交/保存时自动规范化。

Q6：WSL 模式下仓库该放哪？

A：放在 WSL 的 Linux home 目录下（如 ~/code/my-app），不要放在 /mnt/c 挂载路径下。官方指出前者带来更快的 I/O 和更少的符号链接与权限问题。

Q7：桌面应用卡顿有解吗？

A：截至 2026 年 7 月，多个相关 issue 仍处于 open 状态。当前最有效的规避是改用 Codex CLI，避开 Electron 与原生模块加载链路。

十二、总结

：

1. 原生优先
   —— Codex CLI 已原生支持 Windows，PowerShell 一行命令安装，不必默认上 WSL

2. 企业环境用 CLI
   —— 桌面应用受 Microsoft Store 分发限制，CLI 完全不受影响，且更稳定

3. 沙箱按策略降级
   —— elevated 装不上时用 unelevated 顶住可用性，同时推动 IT 调整登录权限策略

：Store 分发限制 → 沙箱 1385 → 行尾 LF/CRLF → WSL worktree 落 /mnt/c → 默认 shell 锁 PowerShell。

：本文安装命令、沙箱配置项、版本支持矩阵、报错处理流程均出自 OpenAI Codex 官方文档（learn.chatgpt.com/docs）与 openai/codex 仓库 README；坑位与点赞数据来自该仓库 Issue 区，截至 2026 年 7 月 27 日。issue 状态可能随版本更新变化，遇到问题建议先查对应 issue 的最新进展。