故障处理
VS Code 的 Codex 一直转圈、面板空白？按扩展宿主与日志排查
Codex VS Code 扩展卡在 loading、面板空白或没反应？从启用状态、本地与远程宿主、Webview 日志和设置逐层排查，用可逆操作与只读任务验证恢复。
Codex 扩展已经安装，打开侧栏却一直转圈、白屏或没有反应。先确认卡住的是扩展启用、面板渲染，还是任务连接：界面没有出现和请求没有完成，需要看的证据不同。
本文针对 VS Code 的官方 openai.chatgpt 扩展，处理 stuck loading、blank panel 及扩展没反应的情况。Cursor、Windsurf 的入口可能相似，但宿主和日志以各自版本为准；桌面 Codex 应用、JetBrains 与 Xcode 集成不直接套用此流程。
先按现象选择检查入口
| 当前现象 | 从哪里开始 | 需要确认的结果 |
|---|---|---|
| 找不到 Codex 图标或命令 | 扩展身份、当前窗口与启用状态 | 命令可用，能打开侧栏 |
| 有图标，打开后整块空白 | 扩展运行状态、Webview 与窗口日志 | 面板能够渲染内容 |
| 登录界面可见，但登录不完成 | 具体认证或回调错误 | 当前环境的认证通过 |
| 面板正常，发任务后一直转圈 | 本次请求、连接与工具错误 | 找到请求失败阶段或实际回复 |
| 本地正常，SSH/WSL/容器窗口失败 | 扩展实际运行宿主与远程连接 | 在正确主机上读取对应日志 |
| 只有一条旧会话卡住 | 新只读会话与旧会话分别验证 | 区分整个扩展故障和单会话问题 |
先记下时间、VS Code 与扩展版本、系统架构、本地或远程环境。保存编辑器里未保存的文件，并记录当前任务是否仍在执行，再考虑重载；不要先删除认证、缓存、历史会话或整个 ~/.codex。
1. 确认安装的是官方扩展，而且当前窗口已启用
在扩展视图搜索 @id:openai.chatgpt，核对发布者与扩展 ID、当前安装版本。查看是否被禁用、是否存在工作区级禁用，以及当前窗口是否提示安装到 SSH、WSL 或容器环境。
已安装但被禁用时，只启用这一个扩展；按 VS Code 提示完成必要的扩展重启。不要为测试同时启用或停用所有扩展。
从命令面板运行官方入口：
Codex: Open Codex SidebarmacOS 通常用 Cmd+Shift+P，Windows/Linux 用 Ctrl+Shift+P 打开命令面板。中文界面可搜索 Codex 找到对应命令。
预期结果： 侧栏出现登录界面或正常内容。如果命令根本不存在，先留在安装、启用或激活这一层；如果命令存在但空白，继续查宿主和日志，反复点击图标不能提供新的诊断信息。
工作区信任或组织策略有明确提示时，先确认项目来源与策略要求；不要为了让扩展启动而直接信任未知代码、关闭安全校验或改成管理员运行。
2. 确认扩展究竟运行在本地还是远程
适用情况： 使用 Remote SSH、WSL、Dev Container，或终端 CLI 正常而侧栏失败。
打开命令面板，运行：
Developer: Show Running Extensions在列表中找到 Codex，查看运行位置及激活状态；结合窗口左下角的远程标识、扩展详情里的安装位置一起判断。VS Code 官方远程扩展文档说明，这个入口可以区分扩展在本地或远程运行。
预期结果： 能明确本次应检查哪台主机。连接了远程仓库，不等于所有扩展都运行在远程；本机终端的 codex --version 成功，也只证明那份 CLI 能启动，不能证明扩展的独立入口和环境正常。
若 Codex 没出现在运行列表，回到第 1 步确认入口并查看激活错误。若连远程 VS Code Server 都没有正常连接，先解决远程连接，再判断 Codex，避免把编辑器基础连接故障当成扩展故障。
3. 重现一次，读取对应层的日志
适用情况： 已确认启用与运行位置，但仍空白或卡住。
记录时间，只打开一次侧栏或提交一次最小请求，然后查看该时间附近的新错误。不要连续重载多次后只挑一条旧日志。
| 检查层 | 具体入口 | 重点看什么 |
|---|---|---|
| 扩展激活或宿主 | 打开 Output（输出）视图，查看 Log (Extension Host) |
激活失败、启动异常、找不到文件或进程退出 |
| 远程宿主 | 输出视图选择 Log (Remote Extension Host) |
当前远程主机的扩展错误；不是本机同名路径 |
| Codex 专属输出 | 若下拉列表中存在 Codex 相关通道，选择它 | 本次连接、请求、认证或工具初始化错误 |
| 面板渲染 | 命令面板运行 Developer: Toggle Developer Tools，看 Console |
与 Codex 面板相关的 Webview、资源或脚本错误 |
通道名可能随版本和语言不同；没有 Codex 专属通道不等于没有日志。远程宿主根本没启动时，其日志通道也可能尚未生成，VS Code 官方排障文档对此有说明。此时先查对应 Remote SSH、WSL 或容器连接日志。
验证目标： 找到与这一次操作、这个扩展和这个宿主对应的错误。Console 中广告、其他扩展或旧窗口的错误不能直接归给 Codex。只复制必要错误文本，遮去 token、Cookie、用户名、私有仓库地址和项目内容。
4. 根据证据做一项可逆检查
先完成版本、时间和日志记录，再选择符合现象的一行。每次只改一项；操作后重复同一个入口或只读请求，看原错误是否消失。
| 证据或现象 | 下一步操作 | 预期与失败后处理 |
|---|---|---|
| 没有明确错误，面板状态疑似卡住 | 保存文件并确认没有需保留的运行任务，再执行 Developer: Reload Window |
重新打开侧栏；仍失败就保存新错误，不连续重载 |
| Codex 激活失败或启用状态异常 | 在当前作用范围仅停用 Codex，按提示重启扩展，再重新启用 | 查看是否重新激活；无变化就恢复原状态并查具体错误 |
| Webview 资源或脚本加载失败 | 对照失败资源、扩展版本与窗口错误；若有官方更新，记录版本后更新并按提示重启 | 同一入口可渲染且错误不再出现；仍失败则带日志报问题 |
| 日志指向可执行文件不存在或启动失败 | 核对扩展设置中的自定义执行路径、安装平台与报错文件 | 路径与平台匹配、进程能启动；不批量结束所有 Codex 进程 |
| 已渲染，具体出现 401 或登录失败 | 确认实际认证环境，再看 401 与登录排障 | 能完成认证并收到只读回复 |
| 面板正常，只在 MCP 初始化或调用时报错 | 保留具体服务器与阶段，转到 MCP 连接失败与超时 | 对应连接或调用通过，再回到同一任务验证 |
仅在某个远程环境失败时，检查实际运行主机的网络、运行时与配置。浏览器能联网、系统终端的代理有效，都不能直接证明远程扩展进程可访问所需服务。依具体错误修复代理或证书配置，不把关闭 TLS 校验、切换全访问权限作为默认步骤。
不要从旧 issue 抄一个版本号进行通用降级，也不要将“删认证文件后好了”当作所有空白面板的修复。类似现象可能来自不同阶段，先以当前版本日志判断。
5. 两类设置别放错地方
打开编辑器设置，搜索：
@ext:openai.chatgpt官方 IDE 设置文档区分了两层：
config.toml：模型、权限、MCP 等共享 Codex 设置。配置读错或被覆盖时，继续查 config.toml 排障。- 编辑器
chatgpt.*设置：扩展在 VS Code 中的行为，不放进config.toml。核对 User、Workspace、Remote 等当前可见作用范围，找出实际覆盖。
重点检查你是否曾手动设置 chatgpt.cliExecutable。官方将它标为开发用途、默认未设置，随意覆盖扩展自带执行文件可能让部分功能失效。普通使用不需要为了修面板再装一份全局 CLI，也不应直接填入 which codex 的结果。
仅当你不是在开发 CLI、却曾添加这个覆盖时： 记录原值及作用范围，移除这一项自定义值，按提示重启或重载，再重复侧栏检查。若它由团队配置管理，先核对用途；不要清空全部设置。
Windows 专用的 WSL 运行设置是：
chatgpt.runCodexInWindowsSubsystemForLinux它适合仓库和工具位于 WSL 的情况，修改会重载 VS Code。不要把它作为所有 Windows 卡住问题的开关；先确定本次究竟需要 Windows 还是 WSL 环境，再核对相应配置与认证。
6. 面板出现后，用只读任务确认真正恢复
适用情况： 侧栏已能显示，准备判断故障是否解决。此步骤会使用当前账号额度。
在已知项目中新建一个测试会话，发送：
这次只做连接与上下文检查。不要修改文件，不执行写入命令，不调用外部服务。请说明当前可见的项目目录，并根据我已打开的这个文件，用两句话概括用途。如果你无法读取文件，请明确说出缺少什么，不要猜测。
先打开一个你了解的普通文本或代码文件作为上下文，避免敏感文件。核对回复内容是否对应实际文件，而不只看转圈停止。
通过标准： 侧栏可操作，新任务能返回正确的只读回复，本次没有同类错误，原有会话仍可访问。若确需只读工具权限，按界面明确授权范围；不用全访问来完成检查。
新会话正常、只有旧会话卡住，说明排查范围可以缩到那条任务。回看旧任务最后的错误与运行阶段，保留记录；不要删除它来测试。需要继续旧工作时，可参考 恢复会话与继续前核对，但恢复聊天不能保证修复面板或重建已经缺失的记录。
如果界面正常但任务仍无回复，回到第 3 步查这次请求日志；这时已经不能只按“白屏”处理。终端非交互任务另见 codex exec 无输出与异常退出，不要用全局 CLI 的成功替代扩展验证。
仍失败时，提供一份能定位问题的记录
准备 VS Code 与 Codex 扩展版本、系统架构、当前窗口是本地还是 SSH/WSL/容器、实际扩展宿主、出现时间、具体复现步骤、相关脱敏错误，以及每次单项操作的结果。标明“所有会话失败”还是“仅一条会话失败”、“面板未渲染”还是“任务不返回”。
从扩展详情页的官方问题反馈入口提交这份最小记录，比上传整个配置或会话目录更容易判断。没有日志支持时，先保留“原因尚未确定”的结论，不把重装、清缓存或删除凭据包装成必然有效的方案。