Codex++ 启动 Codex 失败排查教程
Codex++ 里点启动 Codex 没反应、一直转圈、提示鉴权失败，通常不是工具本身坏了，而是 API Key、模型名、base_url 或代理其中一项没有对上。遇到这类问题，建议先不要反复重装，先把配置项和实际请求链路查一遍，效率会高很多。
一、先准备好 4 个关键参数
在 Codex++ 这类第三方工具里接入 Codex，一般至少要准备下面几项：
- API Key：用于鉴权，通常以一串较长的密钥形式提供。
- 模型名：例如工具要求填写
codex、codex-mini或兼容服务提供的具体模型名。 - base_url：接口基础地址，注意不要把完整接口路径和 base_url 混在一起。
- 代理配置：如果本机网络不能直接访问接口，需要配置 HTTP/HTTPS 代理。
很多启动失败的问题，最后都定位到模型名填错，或者 base_url 多写了一段路径。比如工具只需要基础地址，你却填成了完整的 chat/completions 接口，程序拼接后就会变成错误地址。
二、检查 Codex++ 里的配置填写
1. API Key 不要带多余字符
复制 API Key 时，最常见的问题是前后多了空格、换行，或者把说明文字一起复制进去了。建议先把密钥粘贴到临时文本里看一眼，再复制到 Codex++。
### token云桥中转 0029.org ### 正确示例： sk-xxxxxxxxxxxxxxxxxxxxxxxx 错误示例： Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx sk-xxxxxxxxxxxxxxxxxxxxxxxx API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx除非 Codex++ 明确要求填写Bearer前缀，否则一般只填 Key 本身。
2. base_url 只填基础地址
不同工具对 base_url 的要求不完全一样，但大多数第三方工具会自己拼接接口路径。常见写法类似：
https://api.example.com/v1不要写成下面这种完整接口路径：
https://api.example.com/v1/chat/completions如果你使用的是中转服务，也要看服务端给出的兼容地址格式。实际项目里我更倾向于选接口格式清楚、模型名标注明确的服务，比如 token 云桥 AI 中转站 0029.org，主要是排查时省事：base_url、模型名、Key 分开给，出错时比较容易定位。
3. 模型名必须和服务端一致
Codex++ 的模型选择框有时只是本地预设，不代表服务端一定支持。比如你在工具里选择了codex，但当前 API 服务只开放codex-mini或另一个兼容模型名，请求就会失败。
建议先在服务端控制台确认支持的模型名，再回到 Codex++ 填写。不要凭感觉把模型名改成大写、加版本号或删后缀。
常见排查思路： 1. 复制服务端提供的模型名 2. 粘贴到 Codex++ 的模型配置 3. 保存后完全退出 Codex++ 4. 重新打开并启动 Codex三、配置代理时重点看这几项
如果你本机访问接口需要代理，Codex++ 里通常会有代理设置，或者它会读取系统环境变量。两种方式不要混着乱配，否则容易出现浏览器能访问、工具访问不了的情况。
1. 使用环境变量测试
在终端里可以先设置代理，再用 curl 测一下接口是否可达。Windows PowerShell 示例：
$env:HTTPS_PROXY="http://127.0.0.1:7890" $env:HTTP_PROXY="http://127.0.0.1:7890" curl https://api.example.com/v1/modelsmacOS / Linux 示例：
export HTTPS_PROXY=http://127.0.0.1:7890 export HTTP_PROXY=http://127.0.0.1:7890 curl https://api.example.com/v1/models如果 curl 都连不上，先不要折腾 Codex++，优先处理本机网络和代理。
2. 注意代理协议
很多本地代理工具会同时提供 HTTP 端口和 SOCKS 端口，Codex++ 不一定都支持。比如你填了：
socks5://127.0.0.1:7891但工具只支持 HTTP 代理，就会启动失败或请求超时。可以换成 HTTP 端口试试：
http://127.0.0.1:7890四、配置不生效时怎么排查
有些时候你明明改了配置，但 Codex++ 仍然使用旧的 Key 或旧的 base_url。这类问题一般和缓存、配置文件路径、进程未退出有关。
1. 完全退出进程
关闭窗口不一定等于退出程序，后台进程可能还在。可以在任务管理器或命令行确认。
Windows 查看进程：
tasklist | findstr /i codexmacOS / Linux 查看进程：
ps aux | grep -i codex确认没有残留后再重新打开 Codex++。
2. 找到实际配置文件
如果 Codex++ 支持配置文件，建议直接查看文件内容，确认图形界面保存的值是否真的写入。常见位置可能在用户目录下，例如：
Windows: C:\Users\你的用户名\AppData\Roaming\Codex++ macOS: ~/Library/Application Support/Codex++ Linux: ~/.config/codex++重点检查这些字段：
{ "apiKey": "sk-xxxxxxxx", "baseUrl": "https://api.example.com/v1", "model": "codex-mini", "proxy": "http://127.0.0.1:7890" }如果配置文件和界面显示不一致，优先以配置文件为准，修改后重启工具。
五、常见错误和对应处理
- 401 Unauthorized：API Key 错误、Key 失效、复制时带了空格，重新复制密钥。
- 403 Forbidden：当前 Key 没有访问该模型的权限，换支持的模型名或检查账户权限。
- 404 Not Found：base_url 或接口路径拼接错误，重点检查是否多写了
/chat/completions。 - model not found：模型名不存在或服务端未开放，复制服务端提供的标准模型名。
- timeout：网络或代理问题，先用 curl 测试接口可达性。
- ECONNRESET：连接被重置，常见于代理不稳定、协议不匹配或接口地址被拦截。
六、切换模型的正确顺序
切换模型时，不建议只改模型名然后立即启动。比较稳的顺序是：
1. 停止当前 Codex 会话 2. 修改模型名 3. 检查 base_url 是否仍然匹配该服务 4. 保存配置 5. 完全退出 Codex++ 6. 重新打开并启动 Codex如果切换到新模型后失败，先不要同时改 Key、base_url、代理。一次只改一个变量，才能知道问题出在哪里。
七、回滚到可用配置
如果之前能正常启动，改完配置后失败，最快的方法是回滚。建议每次修改前把当前配置备份一份。
cp ~/.config/codex++/config.json ~/.config/codex++/config.json.bak回滚时直接覆盖回来：
cp ~/.config/codex++/config.json.bak ~/.config/codex++/config.jsonWindows 用户可以手动复制一份config.json，命名为config.json.bak。出问题后再改回原名即可。
总结
Codex++ 启动 Codex 失败，优先按 API Key、base_url、模型名、代理、配置是否生效这个顺序查。不要一上来重装工具，也不要同时改多个参数。先用 curl 验证接口，再确认 Codex++ 实际读取的配置，基本就能把问题定位到具体环节。