发布日期：2026-06-25 | 话题：AI 编程工具 | 适用人群：Windows 开发者、Codex 用户

Codex 在 Windows 上有三条路径：原生 Windows App（桌面版）、CLI + 原生 PowerShell/CMD、CLI + WSL2，三者的沙盒机制、插件支持、Ollama 接入方式各不相同，踩坑点也完全不同。官方文档（developers.openai.com/codex/windows）明确标注：WSL2 路径是最稳定的 CLI 方案，原生 Windows CLI 从版本 0.130.0 起改善但仍标 experimental；桌面版（Windows App）提供完整 GUI 功能（Worktrees、Computer Use、Automations）但 Linux 版本暂未发布。最常见的 Windows 问题集中在四类：沙盒权限设置失败（错误 1385）、PowerShell 编码冲突（UTF-16 vs UTF-8）、WSL2 网络隔离导致 Ollama 连不上、IDE 扩展安装后无响应（缺 C++ Build Tools）。本文按问题类型逐一梳理配置步骤和排查方法。

 

Windows 三条路径对比

在动手之前，先确认你要走哪条路：

 

桌面版 App

CLI + 原生 Windows

CLI + WSL2

官方支持级别

✅ 稳定

⚠️ experimental（0.130.0+）

✅ 稳定

沙盒机制

elevated / unelevated

elevated / unelevated

Linux bubblewrap

Worktrees

✅

❌

✅

Computer Use

✅（macOS 独占）

❌

❌

Automations

✅

❌

✅

Ollama 接入

host.docker.internal

localhost:11434

host.docker.internal

中文/编码问题

无

需手动修复

无

config.toml 路径

%USERPROFILE%\.codex\

%USERPROFILE%\.codex\

~/.codex/（Linux 路径）

快速选型：

● 需要完整 GUI + 任务管理 → 桌面版 App（Microsoft Store 下载）

● 只用 CLI，追求稳定 → WSL2

● 只用 CLI，不想装 WSL → 原生 Windows（0.130.0+ 可用，但遇问题文档少）

 

路径一：桌面版 App（Windows）

下载安装

Microsoft Store 搜索 “Codex”，或通过官网链接安装。安装后首次启动可能较慢（5-15 秒），属正常现象。

沙盒初始化

首次运行桌面版时，Codex 会自动尝试初始化 elevated 沙盒（推荐模式）。初始化失败的常见原因：

错误 1385（登录类型不允许）：

Error 1385: Logon failure: the user has not been granted the requested logon type at this computer.

原因：公司域策略或本地安全策略限制了沙盒用户的登录权限。

排查步骤：

1. 以管理员身份打开"本地安全策略"（secpol.msc）

2. 本地策略 → 用户权限分配 → 找"作为批处理作业登录"

3. 确认沙盒用户（Codex 创建的低权限用户）在列表里

4. 如无法修改（企业策略），改用 unelevated 回退：

# %USERPROFILE%\.codex\config.toml
[windows]
sandbox = "unelevated"

Everyone 可写目录警告：

Warning: directory writable by Everyone

处理方法：移除该目录的 Everyone 写入权限（右键 → 属性 → 安全），然后完全退出重启 Codex。

沙盒内读取额外目录

沙盒默认只能读写项目目录，需要访问其他路径（如共享配置目录）时：

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

企业环境限制沙盒实现

管理员可通过 requirements.toml 强制要求 elevated 模式，防止用户降级到隔离较弱的 unelevated：

# requirements.toml（企业策略文件）
[windows]
allowed_sandbox_implementations = ["elevated"]

 

路径二：CLI + WSL2（推荐 Windows CLI 方案）

安装 WSL2

# 以管理员身份运行 PowerShell
wsl --install          # 安装默认 Ubuntu 发行版
wsl --update           # 确保 WSL2 内核最新
wsl --shutdown         # 重启生效
wsl                    # 进入 WSL shell

WSL1 已不支持：Codex 从版本 0.115 起改用 bubblewrap 沙盒，WSL1 无法运行，必须升级到 WSL2。

检查当前版本：wsl -l -v，STATUS 列应显示 Running，VERSION 列应为 2。

在 WSL2 里安装 Codex CLI

 

# 进入 WSL shell 后
curl -fsSL https://chatgpt.com/codex/install.sh | sh
 
# 验证
codex --version
 
# 如果找不到 codex 命令
which codex || echo "codex not found"
# 重新安装或检查 PATH
export PATH="$HOME/.local/bin:$PATH"

仓库放哪里（关键）

不要把仓库放在 Windows 文件系统挂载路径（/mnt/c/）：

 

# ❌ 避免：跨文件系统，I/O 极慢，权限问题多
cd /mnt/c/Users/你的用户名/Projects/my-repo
 
# ✅ 推荐：Linux 原生文件系统，性能和权限正常
mkdir -p ~/code && cd ~/code
git clone https://github.com/your/repo.git

从 Windows 侧访问 WSL 文件：资源管理器地址栏输入 \\wsl$\Ubuntu\home\<用户名>\code

WSL2 里接 Ollama

WSL2 和 Windows 主机是网络隔离的，localhost 在 WSL2 里指向 Linux 本身，不是 Windows：

 

# ~/.codex/config.toml（WSL2 内的 Linux 路径）
model = "qwen2.5-coder:32b"
model_provider = "ollama"
oss_provider = "ollama"
 
# 沙盒内需要网络访问
sandbox_mode = "workspace-write"
[sandbox_workspace_write]
network_access = true

如果 Ollama 运行在 Windows 侧（不是 WSL 里）：

 

model_provider = "wsl-ollama"
 
[model_providers.wsl-ollama]
name = "Ollama (Windows Host)"
base_url = "http://host.docker.internal:11434/v1"
wire_api = "responses"

config.toml 路径

WSL2 里的 Codex 读取 Linux 路径的配置文件，与 Windows 侧完全独立：

 

~/.codex/config.toml          # Linux 全局配置（对应 /home/你的用户名/.codex/）
.codex/config.toml            # 项目级配置（model_provider 不生效）

不会自动读取 Windows 侧的 %USERPROFILE%\.codex\config.toml，两套配置互相独立。

 

路径三：CLI + 原生 Windows（PowerShell/CMD）

安装前置依赖

# 1. 安装 Node.js（官网下载或 winget）
winget install OpenJS.NodeJS
 
# 2. 验证
node -v    # 应输出 v20.x 或以上
npm -v
 
# 3. 安装 Codex CLI
npm install -g @openai/codex
 
# 4. 验证
codex --version

PowerShell 编码问题（高频坑）

PowerShell 默认使用 UTF-16 LE 编码，而 Codex 返回 UTF-8 响应，管道传输时冲突——中文输出乱码或报"无效的 Unicode 字符"。

症状：

● 中文显示为 涓枃、??

● 报错：无法处理参数，因为参数"query"的值包含无效的 Unicode 字符

● 重定向到文件后内容正常（说明是终端显示层问题，不是 Codex bug）

修复：强制 UTF-8

 

# 临时修复（当前会话有效）
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$OutputEncoding = [System.Text.Encoding]::UTF8
chcp 65001    # 切换代码页到 UTF-8

写入 PowerShell Profile（永久生效）：

 

# 查看 Profile 路径
echo $PROFILE
 
# 编辑（如不存在会自动创建）
notepad $PROFILE
 
# 添加以下内容：
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$OutputEncoding = [System.Text.Encoding]::UTF8

更彻底的方案：用 Windows Terminal + UTF-8

Windows Terminal（微软商店免费下载）对 UTF-8 支持比内置 PowerShell 终端好得多，是在 Windows 上跑 Codex CLI 的推荐终端。

原生 Windows 的沙盒配置

原生 Windows CLI 也使用 elevated/unelevated 沙盒，报错和排查方式与桌面版相同（见"路径一"）。

config.toml 位置：%USERPROFILE%\.codex\config.toml（即 C:\Users\你的用户名\.codex\config.toml）

 

IDE 扩展（VS Code / JetBrains）在 Windows 的配置

VS Code 扩展安装后无响应

最常见原因：缺少 C++ Build Tools。

 

# 安装 Visual Studio Build Tools（含 C++ 工作负载）
winget install --id Microsoft.VisualStudio.2022.BuildTools -e

安装完成后同时确认：

● Microsoft Visual C++ Redistributable (x64) 已安装（控制面板 → 程序 → 程序和功能 里搜索）

● 完全退出并重启 VS Code（不是 reload window，是彻底关掉重开）

VS Code + WSL2 配置

在 WSL 里开发时，VS Code 需要连接到 WSL 子系统：

1. VS Code 安装 WSL 扩展（Remote - WSL，微软官方）

2. 在 WSL 终端里进入项目目录，执行 code . 打开

3. VS Code 状态栏左下角应出现绿色 WSL: Ubuntu 标识

验证 WSL 连接：

echo $WSL_DISTRO_NAME    # 应输出 Ubuntu 或你安装的发行版名称

如果 code . 没有自动拉起 VS Code：

 

# 检查 code 命令是否在 PATH 里
which code
 
# 如果没有，在 VS Code 中执行：
# Command Palette (Ctrl+Shift+P) → "Shell Command: Install 'code' command in PATH"

JetBrains 扩展连接 WSL

JetBrains IDE（IntelliJ/PyCharm/WebStorm）可以直接通过 WSL 作为远程解释器：

● 设置 → 项目 → Python 解释器（或对应语言）→ 添加 → WSL

● Codex 扩展会自动跟随 IDE 的 WSL 配置

 

按报错信息快速定位

报错 / 现象

原因

解决

Error 1385

沙盒用户登录权限被域策略限制

secpol.msc 授权，或改 unelevated

Warning: directory writable by Everyone

目录权限过宽触发安全检查

移除 Everyone 写入权限，重启 Codex

中文乱码 / 无效 Unicode 字符

PowerShell UTF-16 vs Codex UTF-8

chcp 65001 + Profile 里加 UTF-8 设置

codex not found（WSL 里）

PATH 未更新或安装未完成

export PATH="$HOME/.local/bin:$PATH"，重新安装

Ollama 连接被拒（WSL 里）

WSL 网络隔离，localhost 不通

用 host.docker.internal:11434，加 network_access = true

IDE 扩展安装后无响应

缺 Visual Studio C++ Build Tools

winget install Microsoft.VisualStudio.2022.BuildTools

config.toml 改了不生效

修改了 WSL 里的配置，但用原生 Windows 跑（或反之）

确认 Codex 运行路径对应的 config.toml 位置

沙盒曾正常现在失效

沙盒用户/文件权限变化

重启 Codex → 重试 elevated → 回退 unelevated

WSL2 I/O 极慢

仓库在 /mnt/c/ 跨文件系统

把仓库移到 ~/code/（Linux 原生文件系统）

 

诊断日志在哪里

向社区或 OpenAI 提交问题时，提供以下信息：

%USERPROFILE%\.codex\.sandbox\sandbox.log    # Windows 侧沙盒日志
~/.codex/.sandbox/sandbox.log                # WSL 侧沙盒日志

同时附上：

● Windows 版本（winver 命令查看）

● Codex 版本（codex --version）

● 完整报错截图或文字

注意：不要上传 %USERPROFILE%\.codex\.sandbox-secrets\ 目录内容，其中包含认证凭据。

Windows 版本支持矩阵

版本

支持状态

备注

Windows 11

✅ 推荐

企业部署首选

Windows 10（1809+，已更新）

⚠️ 尽力支持

需最新补丁，依赖 ConPTY

Windows 10 旧版

❌

缺少必要控制台组件

WSL1

❌

Codex 0.115+ 不支持

 

常见问题 FAQ

Q1：Windows 上推荐用桌面版还是 CLI + WSL2？

日常开发推荐 CLI + WSL2：稳定性最好、编码问题最少、Ollama 接入最简单。桌面版适合需要 Worktrees、Automations 可视化管理的场景，或者不想装 WSL 的用户。两者可以同时安装，独立使用，配置文件互不干扰。Q2：elevated 和 unelevated 沙盒有什么实际区别？

elevated 沙盒使用专用低权限用户 + 文件系统权限边界 + 防火墙规则，隔离最完整，适合企业环境。unelevated 沙盒使用受限 Windows token + ACL 文件系统边界，隔离弱一些，但不需要特殊权限，在受限域环境下可作为回退方案。官方推荐 elevated，遇到权限问题再降级 unelevated。Q3：WSL2 里的 Codex 能用 Windows 侧的 Node.js 项目吗？

可以，但要把仓库从 Windows 文件系统复制到 WSL 的 Linux 文件系统里（~/code/）。直接用 /mnt/c/ 路径也能工作，但 I/O 性能会大幅下降（跨文件系统读写），大型项目分析时会明显变慢。

Q4：VS Code 在 Windows 侧，Codex CLI 在 WSL2 里，能配合工作吗？

可以，这是推荐的组合。VS Code 安装 Remote - WSL 扩展后，code . 会在 WSL 里启动 VS Code Server，编辑的文件存在 Linux 文件系统，Codex CLI 也在同一 WSL 环境里运行，两者完全共享上下文。VS Code 状态栏显示绿色 WSL: Ubuntu 说明配置正确。

Q5：企业电脑（加入域/有 IT 管控）能正常用 Codex 吗？

通常能用，但 elevated 沙盒可能需要 IT 介入。常见情况是域策略禁止了沙盒用户的批处理登录（触发错误 1385），需要 IT 在本地安全策略里为沙盒用户授权，或者临时改用 unelevated 模式。WSL2 路径的 CLI 版本通常对 IT 管控兼容性更好。

小结

Codex Windows 配置的核心原则：优先 WSL2，遇到不得不用原生 Windows 再处理编码和沙盒问题。三类最高频的 Windows 特有问题都有明确解法：elevated 沙盒报错 1385 → secpol.msc 授权或改 unelevated；PowerShell 中文乱码 → Profile 里强制 UTF-8；WSL2 连不上 Ollama → 改 host.docker.internal + 开 network_access = true。IDE 扩展不响应几乎全是 C++ Build Tools 缺失，winget install Microsoft.VisualStudio.2022.BuildTools 解决。本文数据来源：Codex 官方 Windows 文档（developers.openai.com/codex/windows），2026-06。

 

参考来源：

● Codex 官方 Windows 配置文档（developers.openai.com/codex/windows）

● Codex 官方 IDE 扩展文档（developers.openai.com/codex/ide）

● 七牛云：AI 编程工具配置大全

● Fenno 官网：AI 编程