1. VScode 本地/远程 SSH 下 Codex 界面空白到底卡在哪你打开 VScode左侧 Codex 面板一片空白没有聊天框、没有输入区甚至连登录按钮都不给。本地窗口这样远程 SSH 连上去还是这样。这个现象在 VScode 本地/远程 SSH 使用 Codex 的场景里非常典型核心检索词就是「VScode Codex 界面空白」和「auth.json 配置」。先说清楚 Codex 在 Vscode 里是什么。它是 OpenAI 官方出的编码助手扩展装完之后会在侧边栏挂一个面板正常情况下应该显示对话历史、输入框和模型选择。它跟普通插件不一样的地方在于它依赖一个本地 CLI 进程codex 命令和一个认证文件~/.codex/auth.json面板只是前端壳子真正的会话逻辑跑在后台进程里。所以面板空白八成不是 Vscode 本身坏了而是后台进程没起来或者认证文件读不到、过期了、格式不对。适合谁看三类人第一类是本机装了 Codex 扩展但一直白屏的第二类是通过 Remote-SSH 连到服务器在远程窗口里装 Codex 的第三类是把 Codex 接到自建端点比如 TaoToken 这类兼容 OpenAI 协议的服务之后突然不显示的。这三类的排查路径高度重合区别只在配置文件的位置和端点地址。为什么认证文件这么关键你可以把auth.json理解成门禁卡config.toml理解成通讯录。门禁卡失效进程连不上服务端前端拿不到任何会话数据面板就只能渲染成空白。通讯录写错比如 Base URL 指向一个不存在的地址进程请求超时前端同样拿不到数据。所以排查顺序永远是先看进程日志再动 config.toml最后才动 auth.json。很多人一上来就删 auth.json结果把还能用的登录态也弄没了反而要多走一步重新登录。还有一个容易被忽略的点本地和远程 SSH 是两套独立的~/.codex目录。你在本地配好了SSH 到远程服务器用的是服务器上那个用户的家目录配置完全不共享。远程面板空白先确认你改的是远程那台机器上的文件而不是本地的。我见过有人在本机改了半天 auth.json远程窗口纹丝不动就是因为改错了机器。下面按「先定位、再配置、后验证」的顺序走每一步都给可复制的命令和配置片段。整个过程不需要重装扩展也不需要卸载重来。2. 接入 TaoToken 前的前置准备端点、Key 与目录结构在动 auth.json 之前先把三样东西备齐一个可用的 API Key、一个正确的 Base URL、以及确认~/.codex目录存在。这一步是后面所有配置的基础缺一样都会导致面板继续空白。TaoToken 的 API 地址是https://taotoken.net/api注意这里不带任何查询参数就是干净的根路径。Codex 走的是 OpenAI 兼容协议所以 Base URL 填这个就行不需要在后面拼/v1之类的后缀具体以你所用客户端的说明为准Codex 的 config.toml 里通常写根地址。API Key 在控制台的 API Keys 页面生成地址是https://taotoken.net/api-keys生成后复制那一长串sk-开头的字符串只显示一次记得先存到安全的地方。模型 ID 这块要单独说。Codex 默认会用一个模型名去请求如果你接的是自建端点模型名必须跟端点支持的名称对上否则请求会返回模型不存在的错误前端同样白屏。常见的做法是在 config.toml 里显式指定 model 字段。具体支持哪些模型 ID以你账号下的模型列表为准别照抄别人的模型名对不上是最隐蔽的坑之一。目录结构长这样本地和远程都一样~/.codex/ ├── config.toml # 端点、模型等配置 ├── auth.json # 认证信息API Key 或 OAuth token └── ... # 其他缓存文件先确认目录在不在ls -la ~/.codex如果提示No such file or directory说明 Codex CLI 从没在这台机器上跑过。这时候先手动建目录mkdir -p ~/.codex然后确认 codex 命令本身可用which codex codex --version如果which codex没有任何输出说明 CLI 没装或者不在 PATH 里。Vscode 扩展虽然自带一部分逻辑但很多版本仍然依赖系统里的 codex 可执行文件。这种情况下先装 CLI再回来配 auth.json。装完之后codex --version能打印版本号才算前置条件满足。远程 SSH 场景要额外注意一件事你 SSH 进去之后默认用户是谁whoami看一下。~/.codex展开的是当前用户的家目录。如果你用 root 登录但配置写在普通用户目录下Codex 读的是 root 的目录自然读不到。确认用户身份再动手能省掉一大半「改了没反应」的困惑。三件套备齐后进入下一步。记住这个对应关系Base URL 填https://taotoken.net/apiKey 填控制台生成的sk-串Model ID 填你账号下真实可用的模型名。这三样在 config.toml 和 auth.json 里各司其职别混。3. 可复制配置auth.json 与 config.toml 的正确写法这一步是全文的核心。Codex 界面空白绝大多数情况是这两个文件的格式或内容不对。下面给出可直接复制的片段路径和字段名保持原样你按自己的 Key 替换即可。先看~/.codex/auth.json。它的作用是存放认证凭据。用 API Key 方式接入时结构如下{ OPENAI_API_KEY: sk-你的TaoToken密钥, OPENAI_BASE_URL: https://taotoken.net/api }注意两点第一JSON 里不能有注释不能有多余逗号最后一项后面不能带逗号否则解析失败直接白屏第二Key 要用英文双引号包起来别用中文引号。我见过有人从网页复制粘贴引号被输入法转成中文的肉眼几乎看不出来但解析就是报错。再看~/.codex/config.toml。它管的是端点和模型model 你的模型ID model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api wire_api chatwire_api这个字段决定用哪种请求格式Codex 接 OpenAI 兼容端点时一般用chat。如果你的端点走的是 responses 风格按实际说明调整。model字段填你账号下真实存在的模型 ID填错会返回 404 或模型不存在前端一样白屏。改文件之前先备份这是保命操作cd ~/.codex cp config.toml config.toml.bak cp auth.json auth.json.bak备份完再写入新内容。写 auth.json 可以用 heredoc避免手抖cat ~/.codex/auth.json EOF { OPENAI_API_KEY: sk-你的TaoToken密钥, OPENAI_BASE_URL: https://taotoken.net/api } EOF写 config.toml 同理cat ~/.codex/config.toml EOF model 你的模型ID model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api wire_api chat EOF写完检查一下 JSON 是否合法这一步能提前拦住大部分白屏python3 -m json.tool ~/.codex/auth.json如果输出格式化后的 JSON说明格式没问题如果报Expecting property name之类的错就是引号或逗号的问题回去改。TOML 没有内置校验命令但可以用 python 的 tomllib3.11快速验证python3 -c import tomllib; tomllib.load(open($HOME/.codex/config.toml,rb)); print(toml ok)两个文件都通过校验后回到 Vscode 执行重载窗口。快捷键Ctrl Shift P输入Developer: Reload Window回车。远程 SSH 窗口同样适用这个命令重载的是远程那一侧的扩展宿主。如果你用的是 Cline MCP 或 Codex 的 auth.json 体系记住三件套必须同时正确Base URL 指向https://taotoken.net/apiKey 是控制台生成的sk-串Model ID 是账号下真实可用的名字。三者缺一或者任意一个写错面板都会以空白的形式表现出来而不是给你一个明确的报错弹窗。这也是为什么很多人觉得「莫名其妙就白了」。4. 验证请求是否正常返回日志、命令行与成功标志配置写完、窗口重载之后怎么确认真的通了别只盯着面板看面板空白和面板正常之间中间态是「进程在跑但没数据」。用下面几个动作逐层验证。第一层看 Vscode 的输出面板。Ctrl Shift U打开输出右上角下拉选 Codex 相关的通道通常叫 Codex 或 OpenAI Codex。这里会打印扩展和后台进程的日志。重点找这几类信息进程启动成功的行、请求发出的 URL、返回的状态码。如果看到401是 Key 不对或没读到看到ECONNREFUSED或local proxy failed是端点地址写错或网络不通看到reading choices相关的解析错误多半是返回体格式跟wire_api不匹配。第二层直接在终端里跑一次 CLI 请求绕开 Vscode 前端codex exec print hello如果这条命令能正常返回内容说明 auth.json 和 config.toml 都是对的问题出在 Vscode 扩展这一侧重载窗口或重装扩展即可。如果这条命令也报错那问题就在配置文件或网络按报错信息继续查。这一步能把「前端问题」和「配置问题」彻底分开非常省时间。第三层用 curl 直接打端点验证 Key 和 Base URL 本身可用curl -s https://taotoken.net/api/models \ -H Authorization: Bearer sk-你的TaoToken密钥 \ | head -c 500正常的话会返回一段 JSON里面列出可用模型。如果返回401 UnauthorizedKey 有问题返回404路径不对卡住不动网络层有问题。这一步不依赖 Codex纯粹验证凭据和端点是最干净的隔离测试。三层都过了回到 Vscode 重载窗口Codex 面板应该出现聊天框。如果还是空白去输出面板看最新日志通常会有明确的错误行。把错误行贴出来对照下一节的排查表基本能定位。成功标志有三个输出面板里能看到请求返回 200codex exec能打印结果面板出现输入框且能发消息收到回复。三个都满足说明整条链路通了。只满足前两个而面板仍空白那就是扩展缓存问题试试禁用再启用扩展或者重载窗口两次。5. 本篇常见报错排查401、local proxy failed、reading choices、OAuth这一节把最常见的四类报错摊开讲每条都给现象、原因、动作。对照你的输出面板日志找对应项。401 Unauthorized。现象是日志里明确出现 401面板空白。原因通常是 auth.json 里的 Key 写错、过期或者根本没读到这个文件。动作先确认文件路径是当前用户的~/.codex/auth.json用cat ~/.codex/auth.json看内容再用上一节的 curl 命令单独验证 Key 是否有效。如果 curl 也 401去控制台重新生成 Key如果 curl 正常但 Codex 401说明 Codex 读的不是这个文件检查是不是 SSH 到了另一台机器或者扩展配置里指定了别的路径。local proxy failed。现象是日志里出现local proxy failed或连接被拒绝。原因一般是 config.toml 里的 base_url 写错或者本机网络到端点不通。动作确认 base_url 是https://taotoken.net/api没有多余斜杠、没有拼错然后在同一台机器上curl -I https://taotoken.net/api看能否连通。远程 SSH 场景下网络出口是远程服务器如果服务器本身出网受限也会报这个错这时候要在服务器侧排查网络而不是改 Codex 配置。reading choices 解析错误。现象是日志里出现类似error reading choices或返回体解析失败。原因是wire_api跟端点实际返回的格式不匹配。动作把 config.toml 里的wire_api在chat和其他可选值之间切换试一次每次改完重载窗口。这个字段决定请求走哪种协议填错就会在解析返回体时炸掉前端表现为空白。OAuth 相关报错。现象是日志里出现 OAuth、token refresh 之类的字样。原因是 auth.json 里残留了旧的 OAuth 登录态跟你现在用的 API Key 方式冲突。动作备份后重置登录状态cd ~/.codex mv auth.json auth.json.bak然后重载窗口让 Codex 重新走一次认证流程或者按上一节重新写入 API Key 版的 auth.json。注意区分config.toml管配置auth.json管认证。如果只是 SSH 面板空白、CLI 能跑优先动 config.toml如果是登录/认证异常、CLI 也报错再动 auth.json。这个判断顺序能避免误删有效凭据。还有一类不报错但白屏的情况扩展版本和 CLI 版本不匹配。动作是codex --version和扩展页面显示的版本对一下差距太大就升级其中一个。升级后重载窗口。排查时养成一个习惯每次只改一个文件改完立刻重载窗口看日志。同时改多个地方出问题就不知道是哪个引起的。备份文件留着实在不行cp auth.json.bak auth.json回滚比从头配快得多。6. 长期编码与 Agent 场景把配置固化下来单次修好不算完如果你打算长期用 Codex 做编码和 Agent 任务把配置固化下来能省掉反复排查的麻烦。核心思路是让~/.codex下的两个文件保持稳定端点、Key、模型三件套一次配对之后不再随意改动。对于经常切换本地和远程的开发方式建议把配置写成脚本在新机器上一键铺开。比如建一个setup-codex.sh#!/usr/bin/env bash set -e mkdir -p ~/.codex cat ~/.codex/auth.json EOF { OPENAI_API_KEY: sk-你的TaoToken密钥, OPENAI_BASE_URL: https://taotoken.net/api } EOF cat ~/.codex/config.toml EOF model 你的模型ID model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api wire_api chat EOF python3 -m json.tool ~/.codex/auth.json /dev/null echo auth ok注意脚本里 Key 是明文别提交到公开仓库本地用或者放私有环境里。远程服务器上跑一遍配置就齐了比手动改文件稳。长期跑 Agent 任务的话模型选择上可以固定一个稳定的 ID别频繁换。频繁换模型容易遇到「这个模型名端点不认」的白屏排查成本高。把常用的模型 ID 记在 config.toml 里需要切换时改一处、重载一次路径清晰。另外Codex 的会话缓存和日志会占空间远程服务器上跑久了记得清理旧的缓存目录但别删config.toml和auth.json。清理前先确认哪些是缓存、哪些是配置拿不准就只删明确带 cache 字样的目录。如果你需要更完整的接入说明和字段解释可以看接入文档https://taotoken.net/doc 。想直接在网页里验证模型是否可用用模型对话页面试一条消息最快https://taotoken.net/model-chat 。长期做编码和 Agent 任务、需要稳定额度和调用计划的看 Coding Planhttps://taotoken.net/coding-plan 。Key 的管理和重新生成在控制台https://taotoken.net/console API Keys 单独页面是 https://taotoken.net/api-keys 。最后留一个实用习惯每次改完配置先跑codex exec print hello通了再回 Vscode 重载窗口。命令行通了前端基本不会白屏命令行不通改前端也是白费。这个顺序坚持下来Vscode 本地/远程 SSH 下 Codex 界面空白的问题基本能在几分钟内定位到具体是 Key、端点还是模型名的问题。