Codex Desktop 卡在白屏或一直转圈：Windows 和 macOS 上的解决方法

打开 Codex Desktop，它一直停在白屏上转圈；或者窗口本来好好的，突然变成白屏，中间只剩一个 logo。重装几乎没用。2026 年 9 月，这个症状在官方仓库 openai/codex 里以三种不同的原因出现，而且哪一种都不会让你丢失工作：卡住的是界面，不是代理。

你遇到的是哪一种白屏？

白屏出现的时机就指向原因。对照下表，直接跳到对应的小节。

什么时候出现	可能的原因	怎么做
Windows 上更新到 26.924 版本后，一启动就出现	窗口与 codex.exe 进程（app-server）之间的启动故障	只结束子进程 codex
Windows 或 macOS 上，使用一段时间后出现	渲染进程卡死，占用 3 GB 以上内存	只结束 Codex (Renderer)
一直出现，重装后也一样	~/.codex/config.toml 损坏，内容全是 NUL 字节	给文件改名

更新后一启动就卡在转圈：Windows 上怎么解决？

在转圈画面还在时，只结束子进程 codex。主程序会立刻重新拉起一个，界面随即加载出你的项目和对话。

这个情况记录在 issue #48333，于 2026 年 9 月 26 日提交，安装包为 OpenAI.Codex 26.924.1866.0，其他用户在 26.924.2738.0 版本上也确认了。日志显示内部 MCP 服务器超时：

MCP server startup failed server_name="codex_app" error="timed out awaiting tools/list after 10s"

提交者已经试过 Windows 的修复与重置、卸载重装、全新的 .codex，以及删除 config.toml，都没有用，所以这些步骤可以跳过。

怎么做：

1. 转圈画面还在时，打开任务管理器，展开应用的进程组，结束名为 Codex 的子进程（见 issue #48578）。
2. 也可以在 PowerShell 里执行，#48333 中有用户记录了这条命令：

   Stop-Process -Name codex -Force

   注意：这条命令会结束所有 codex 进程，包括在另一个终端里运行的 Codex CLI 会话。
3. 如果还是不行，试试同一个 issue 里的另一种做法：结束应用的主渲染进程。列出候选进程：

   Get-CimInstance Win32_Process -Filter "Name='ChatGPT.exe'" |
     Where-Object CommandLine -like '*--type=renderer*' |
     Select-Object ProcessId, CommandLine

   用 Stop-Process -Id <PID> 结束 --renderer-client-id 最小的那个。据报告，窗口大约 5 秒后恢复。

这是每次启动都要做一遍的临时办法：下次关闭再打开，转圈大概率还会出现，直到修复版本发布。截至 2026 年 9 月 28 日，这些 issue 都还没有 OpenAI 维护者的回复。

工作到一半突然白屏：代理停了吗？

没有。在这些报告里，代理一直在后台运行，只是窗口不再绘制。结束渲染进程，界面就会回来，不用关闭应用。

macOS 上，issue #46641（ChatGPT 应用 26.915.31945）显示 Codex (Renderer) 进程 CPU 达到约 120%，内存 3.2 GB，峰值 4.7 GB。Windows 上，#47110（版本 26.915.4065.0）记录渲染进程占用 2,973 MB，而会话通过手机应用仍在正常工作。

macOS：打开活动监视器，找到 CPU 很高的 Codex (Renderer)，只对它执行强制退出。用终端：

ps aux | grep -i codex | grep -i renderer
kill <PID>

Windows：用上一节的 Get-CimInstance 命令，结束占用内存最多的渲染进程。

#46641 的报告说得很清楚：只结束渲染进程，屏幕立刻恢复，不需要退出 ChatGPT。用一段时间后问题往往会再次出现。

重装后还是白屏：重装后什么东西还留着？

~/.codex 文件夹。卸载应用不会删除它，里面一个损坏的 config.toml 会让任何新安装都保持白屏。

issue #44374 记录了这种情况：config.toml 大小 2,700 字节，全部是 0x00。Codex Desktop 只显示白屏，是 Codex CLI 暴露了错误：

Error loading config.toml:
C:\Users\<username>\.codex\config.toml:1:2701
key with no value, expected '='

怎么做：

1. 查看文件的前几个字节。Windows：

   Format-Hex "$env:USERPROFILE\.codex\config.toml" | Select-Object -First 2

   macOS 或 Linux：

   head -c 64 ~/.codex/config.toml | xxd

   全是零（00 00 00 ...）就说明文件已损坏。
2. 给文件改名，而不是删除：

   Rename-Item "$env:USERPROFILE\.codex\config.toml" config.toml.bak

   mv ~/.codex/config.toml ~/.codex/config.toml.bak

3. 重新打开应用。在那份报告里，界面立刻恢复，项目和历史记录都还在。之后在新的 config.toml 里重新配置即可。

只在一台机器上反复出现：怎么找到诱因？

把旧的 ~/.codex 改名，用一个全新的文件夹测试。如果应用稳定下来，诱因就在旧的状态数据里，而不是账号或版本。

#46641 就是这样定位问题的：同一个版本在 MacBook 上正常、在 Mac mini 上出错；在这台 Mac mini 上新建一个 macOS 用户则正常；清空 ~/Library/Application Support/OpenAI/Codex 没有用。换成空的 ~/.codex 后，应用恢复正常。

# macOS / Linux，先关闭应用
mv ~/.codex ~/.codex-backup

# Windows（PowerShell），先关闭应用
Rename-Item "$env:USERPROFILE\.codex" .codex-backup

不要删除旧文件夹：你的会话（sessions/）和历史都在里面。同一份报告提到，移走一个仍被引用的会话文件会让应用显示 "unable to restore"。需要什么就一点点挪回来，界面状态文件（比如 .codex-global-state.json）不要带回来。

现在就得干活：能不能不用窗口使用 Codex？

可以。Codex CLI 不依赖 Desktop 窗口。在 issue #48578 中，应用卡在转圈时，终端里的 codex 0.157.0 仍能正常接收并回复提示。提交 issue 之前，先运行本地诊断，并附上脱敏后的版本：

codex doctor --json