【排障实录】GPT Desktop (Codex) 开启 WSL 智能体模式后无法启动？手把手教你修复

作者：AITechLab 由 QClaw Agent 复盘整理 | 日期：2026-07-21 | 适用版本：OpenAI Codex (Microsoft Store 版)
https://openai.com/zh-Hans-CN/codex/

一、问题现象

用户反馈：GPT Desktop (Codex) 在设置 WSL 作为智能体运行环境后，应用无法启动------点击图标后窗口闪一下就消失，或者根本没有任何反应。

错误表现：

应用启动后立即崩溃或无响应
Windows 任务栏没有 Codex 图标
进程存在但没有可见窗口
无论是修复/重置/卸载重装皆无法解决（本地残留配置干扰）

二、诊断过程

2.1 确认问题应用

首先需要确认是哪个应用出现问题。系统上可能存在多个相关应用：

应用名称	包名/路径	说明
OpenAI Codex	`OpenAI.Codex_*` (WindowsApps)	本次问题应用
Codex++	`D:\Programs\Codex++`	独立第三方应用
ChatGPT Classic	`OpenAI.ChatGPT-Desktop_*`	独立的 ChatGPT 桌面版

powershell

复制代码

# 查找 Codex 相关进程
Get-Process | Where-Object { $_.Path -match "Codex" } |
  Format-Table ProcessName, Id, Path -AutoSize

2.2 定位配置文件

Codex 的配置文件位于用户目录：

code

复制代码

C:\Users\<用户名>\.codex\

关键文件：

config.toml --- 主配置文件
.codex-global-state.json --- 全局状态
sqlite/ --- 数据库目录
bin/wsl/ --- WSL 模式二进制缓存

2.3 分析日志

Codex 日志位置：

code

复制代码

C:\Users\<用户名>\AppData\Local\Packages\OpenAI.Codex_<ID>\LocalCache\Local\Codex\Logs\

关键错误日志：

code

复制代码

2026-07-21T10:13:55.630Z warning bundled_executable_relocation_failed
  executableName=bwrap
  errorCode=ENOENT
  errorMessage="Bundled executable relocation failed during stat_source"
  sourcePath="C:\Program Files\WindowsApps\OpenAI.Codex_...\app\resources\codex-resources\bwrap"

2026-07-21T10:14:25.670Z warning Initialize handshake still pending
  errorMessage="state db backfill is running at /mnt/c/Users/.../.codex;
                waiting up to 30s before retrying startup initialization"

2026-07-21T10:14:25.671Z error Codex app-server initialize handshake timed out
  errorMessage="Codex app-server initialize handshake timed out"

2026-07-21T10:14:28.003Z error Codex CLI process exited
  code=1
  reason="failed to initialize sqlite state runtime under /root/.codex/sqlite:
          timed out waiting for state db backfill at /mnt/c/Users/.../.codex
          after 30s (status: running)"

2.4 根本原因分析

从日志中提取三个关键信息：

① WSL 模式已启用

code

复制代码

[wsl] eligible distro list
  * Ubuntu-Preview    Stopped    2
  HeyGem-GenVideo   Stopped    2
  ...

Codex 正在尝试使用 WSL 作为运行环境。

② bwrap 工具缺失

code

复制代码

bundled_executable_relocation_failed
  executableName=bwrap
  errorCode=ENOENT

bwrap（Bubblewrap）是 Linux 沙箱工具，WSL 模式下运行 Codex 核心进程需要它，但 WindowsApps 目录下的可执行文件不存在。

③ WSL 状态数据库迁移超时

code

复制代码

failed to initialize sqlite state runtime under /root/.codex/sqlite:
  timed out waiting for state db backfill at /mnt/c/Users/.../.codex
  after 30s

即使 WSL 环境存在，其内的状态数据库同步到 Windows 文件系统的操作超时了 30 秒，导致初始化失败。

2.5 定位配置项

打开 config.toml，找到 [desktop] 部分：

toml

复制代码

[desktop]
runCodexInWindowsSubsystemForLinux = true   # ← 问题根源

这就是控制是否使用 WSL 的开关。

三、解决方案

方案：关闭 WSL 模式，恢复 Windows 原生运行

步骤 1：关闭所有 Codex 进程

powershell

复制代码

# 关闭所有 Codex 相关进程
Stop-Process -Name "ChatGPT" -Force -ErrorAction SilentlyContinue

# 验证进程已关闭
Get-Process | Where-Object { $_.Path -match "Codex" -and 
                               $_.Path -notmatch "ChatGPT-Desktop" }

步骤 2：修改配置文件

编辑 C:\Users\<用户名>\.codex\config.toml，将：

toml

复制代码

runCodexInWindowsSubsystemForLinux = true

改为：

toml

复制代码

runCodexInWindowsSubsystemForLinux = false

步骤 3：重新启动 Codex

powershell

复制代码

Start-Process "C:\Program Files\WindowsApps\OpenAI.Codex_26.715.8383.0_x64__2p2nqsd0c76g0\app\ChatGPT.exe"

步骤 4：验证启动成功

检查进程是否正常运行：

powershell

复制代码

# 等待 5 秒后检查
Start-Sleep -Seconds 5
Get-Process | Where-Object { $_.ProcessName -eq "codex" }

正常情况下应该看到 codex 进程存在（日志中不再有 bwrap 错误）。

检查最新日志确认无错误：

powershell

复制代码

$latestLog = Get-ChildItem "$env:LOCALAPPDATA\Packages\OpenAI.Codex_*\LocalCache\Local\Codex\Logs\$(Get-Date -Format 'yyyy\MM\dd')" -Filter "*.log" |
  Sort-Object LastWriteTime -Descending | Select-Object -First 1
Get-Content $latestLog.FullName -Tail 20

四、修复效果

修复前

Codex 启动失败，初始化握手超时
bwrap 工具缺失，/root/.codex/sqlite 状态同步超时
应用崩溃或闪退

修复后

Codex 以 Windows 原生模式启动
日志显示正常 git 操作和文件系统访问
应用正常运行

五、进阶：如何正确使用 WSL 模式

如果你需要 WSL 模式（用于访问 Linux 工具链），需要额外配置：

5.1 确保 WSL 已安装且可用

powershell

复制代码

wsl --list --verbose

5.2 在 WSL 中安装 bwrap

bash

复制代码

# Ubuntu/Debian
sudo apt install bubblewrap

# 或从源码编译
git clone https://github.com/containers/bwrap.git
cd bwrap
meson setup build
ninja -C build
sudo ninja -C build install

5.3 验证 Codex CLI 在 WSL 中可用

bash

复制代码

codex --version

5.4 重新开启 WSL 模式

将配置改回：

toml

复制代码

runCodexInWindowsSubsystemForLinux = true

六、相关文件路径汇总

用途	路径
Codex 主配置	`C:\Users\<用户名>\.codex\config.toml`
Codex 日志	`C:\Users\<用户名>\AppData\Local\Packages\OpenAI.Codex_<ID>\LocalCache\Local\Codex\Logs\`
Codex 缓存	`C:\Users\<用户名>\.codex\bin\wsl\`
Codex 状态数据库	`C:\Users\<用户名>\.codex\sqlite\`
Codex 安装目录	`C:\Program Files\WindowsApps\OpenAI.Codex_26.715.8383.0_x64__2p2nqsd0c76g0\`
Codex AppData	`C:\Users\<用户名>\AppData\Local\Packages\OpenAI.Codex_<ID>\LocalCache\`

七、常见问题

Q：修改配置后仍然报错？

A：确保完全关闭了所有 Codex 进程（包括后台进程），然后重新启动。

Q：bwrap 是什么？

A：Bubblewrap 是一个 Linux 沙箱工具，用于在 WSL 模式下隔离 Codex 核心进程。如果不想安装 WSL 依赖，保持 Windows 原生模式即可。

Q：Codex++ 和 OpenAI Codex 有什么区别？

A：Codex++ 是第三方开发的应用；OpenAI Codex 是 OpenAI 官方的 ChatGPT Desktop 应用（Microsoft Store 版），内置 Codex 智能体功能。

Q：WSL 模式有什么优势？

A：可以访问 Linux 工具链（如 gcc、make、bash 脚本），适合需要 Linux 环境的开发场景。大多数 Windows 用户使用 Windows 原生模式即可。

本文由 QClaw Agent 复盘整理*，记录真实排障过程。如有疑问欢迎交流。*