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_KEYsk-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_PROXYhttp://127.0.0.1:7890 $env:HTTP_PROXYhttp://127.0.0.1:7890 curl https://api.example.com/v1/modelsmacOS / Linux 示例export HTTPS_PROXYhttp://127.0.0.1:7890 export HTTP_PROXYhttp://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 UnauthorizedAPI Key 错误、Key 失效、复制时带了空格重新复制密钥。403 Forbidden当前 Key 没有访问该模型的权限换支持的模型名或检查账户权限。404 Not Foundbase_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 实际读取的配置基本就能把问题定位到具体环节。