> 发布日期：2026-07-27
> 数据来源：OpenAI Codex 官方文档（learn.chatgpt.com/docs）、openai/codex GitHub 仓库 README 及 Issue 区真实反馈
> 时效性：截至 2026 年 7 月，Codex CLI 已原生支持 Windows PowerShell 安装，不再强制 WSL

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 的选型决策依据。

---

![CodexWindows避坑指南-img1.png](https://developer.qcloudimg.com/http-save/yehe-12049964/d6fc6004a85f1ebca3a27fe82a3e6b22.jpg)

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

**支持。** Codex CLI 提供官方 Windows 安装脚本，通过 PowerShell 一行命令完成安装，不需要 WSL、不需要虚拟机。

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

也可以走包管理器：

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

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

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

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

```powershell
$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` 中显式选择：

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

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

```toml
windows.sandbox_private_desktop = false
```

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

```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`：

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

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

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

**方案二：配置 Git 自动转换**

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

**方案三：编辑器侧兜底**

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

```ini
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` 挂载路径：

```bash
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$` 即可进入）。

### 大仓库变慢的排查

```bash
# 确认当前不在 /mnt/c 下
pwd

# 更新 WSL 并重启
wsl --update
wsl --shutdown
```

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

![CodexWindows避坑指南-img2.png](https://developer.qcloudimg.com/http-save/yehe-12049964/2351291d6cf964f106468a5e4e80d26f.jpg)

---

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

### 现象

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

### 社区提出的配置方案

```toml
[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 对比表

| 维度 | 原生 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"

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

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

### 7.4 WSL 安装 Codex 完整流程

在提权的 PowerShell 或 Windows Terminal 中：

```powershell
# 安装默认 Linux 发行版（通常是 Ubuntu）
wsl --install

# 进入 WSL shell
wsl
```

在 WSL shell 中：

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

### 7.5 从 WSL 内启动 VS Code

```bash
# 在 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：

```bash
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:\absolute\directory\path
```

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

### 9.2 IDE 扩展装了没反应

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

```powershell
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 中优先级高于捆绑版本。

```powershell
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 官方文档：developers.openai.com/codex
- Codex Windows 沙箱文档：learn.chatgpt.com/docs/windows/windows-sandbox
- Codex WSL 配置文档：learn.chatgpt.com/docs/windows/wsl
- openai/codex 仓库：github.com/openai/codex
-  AI 大模型广场：qiniu.com/ai/models

发布日期：2026-07-27 数据来源：OpenAI Codex 官方文档（learn.chatgpt.com/docs）、openai/codex GitHub 仓库 README 及 Issue 区真实反馈 时效性：截至 2026 年 7 月，Codex CLI 已原生支持 Windows PowerShell 安装，不再强制 WSL

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

Codex CLI 是 OpenAI 推出的本地编码 agent，自 2026 年起已原生支持 Windows，通过 PowerShell 一行命令即可安装，不再强制要求 WSL 或虚拟机。在 Windows 上运行时，Codex 使用专门的 Windows 沙箱限制文件写入范围并拦截网络访问，沙箱分为 `elevated`（独立低权限沙箱用户 + 防火墙规则，官方首选）和 `unelevated

开发工具

客户端

运维

Codex CLI现已原生支持Windows系统，通过PowerShell一键安装，无需WSL或虚拟机。文章详细解析了Windows用户常见的五大问题：企业环境安装限制、沙箱模式选择、文件行尾混乱、WSL路径问题及默认shell锁定。针对每个问题提供官方解决方案，并对比原生Windows与WSL模式的适用场景，帮助开发者高效部署Codex开发环境。

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Codex CLI现已原生支持Windows系统，通过PowerShell一键安装，无需WSL或虚拟机。文章详细解析了Windows用户常见的五大问题：企业环境安装限制、沙箱模式选择、文件行尾混乱、WSL路径问题及默认shell锁定。针对每个问题提供官方解决方案，并对比原生Windows与WSL模式的适用场景，帮助开发...

Codex CLI Windows 避坑指南：从安装到沙箱报错的完整排查手册-腾讯云开发者社区-腾讯云

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

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

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐