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 独立安装包。

现状与规避

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

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

3.1 两种沙箱模式的区别

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

官方对 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"

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

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 强制统一（推荐）

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

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

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

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

方案二：配置 Git 自动转换

# 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\<user>\.codex），而不是使用 WSL 原生的 home 目录。结果是：即使仓库完整位于 WSL 内（例如 /home/<user>/Development/...），worktree 仍被解析到 /mnt/c/Users/<user>/.codex/worktrees/...。

两类后果：

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

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

官方推荐做法

把仓库放在 WSL 的 Linux home 目录下，而不是 /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$\Ubuntu\home\<user>（在资源管理器地址栏输入 \\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 官方给出的选择条件

默认用原生 Windows 沙箱。 改用 WSL 的三个条件（满足任一即可考虑）：

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

7.2 对比表

7.3 WSL 版本限制

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

必须使用 WSL2。 检查与升级：

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 .

确认已连接到 WSL 的三个标志：

1. 状态栏显示 WSL: <distro>
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 版本支持矩阵

其他前提条件：

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

九、其他高频问题速查

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

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

路径必须是已存在的绝对目录。成功后当前会话中后续沙箱命令即可读取该目录。

9.2 IDE 扩展装了没反应

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

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

需同时确认已安装 Microsoft Visual C++ Redistributable (x64)。安装后完全重启 VS Code（不是重载窗口）。

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 赞）。当前可行的规避是改用 Codex CLI——CLI 不依赖 Electron 与桌面应用的原生模块加载链路，在 Windows 上表现更稳定。

9.7 bundled rg 报 Access Denied

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

winget install BurntSushi.ripgrep.MSVC

十、权限风险提示

官方明确警告：全权限模式下 Codex 不再局限于项目目录，可能造成数据丢失。

更安全的两种做法：

1. 保留沙箱边界 + 用 rules 开 特例 —— 只对确实需要的路径放行
2. 把 approval policy 设为 never —— 让 Codex 不请求提权地尝试解决问题，而不是每次都弹窗诱导你批准全权限

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

十一、模型接入的成本考量

Codex CLI 支持用 ChatGPT 账号登录（Plus / Pro / Business / Edu / Enterprise 计划内），也支持 API Key 接入。国内团队在评估长期使用成本时，常见做法是同时保留一条国产模型通道作为成本兜底或合规备选。七牛云 AI 大模型广场（https://www.qiniu.com/ai/models ）聚合了多款主流大模型，国内可直接访问，激活 API Key 即可在支持的模型间切换，适合在主力工具之外准备一条备用链路。

十二、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 的最新进展。

以上就是Codex Windows避坑指南：从安装到沙箱报错的完整排查手册的详细内容，更多关于Codex Windows避坑指南的资料请关注脚本之家其它相关文章！

最新评论