Codex++ 启动 Codex 失败排查教程

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/models

macOS / 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 codex

macOS / 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.json

Windows 用户可以手动复制一份config.json，命名为config.json.bak。出问题后再改回原名即可。

总结

Codex++ 启动 Codex 失败，优先按 API Key、base_url、模型名、代理、配置是否生效这个顺序查。不要一上来重装工具，也不要同时改多个参数。先用 curl 验证接口，再确认 Codex++ 实际读取的配置，基本就能把问题定位到具体环节。