Codex 配置 OpenAI Compatible API：Base URL、API Key、model not found 排错笔记
Codex 配置 OpenAI Compatible API：Base URL、API Key、model not found 排错笔记
最近把几个 AI 编程工具放在一起用，最大的感受不是“哪个工具更强”，而是配置很容易乱。
Cursor 在编辑器里用一套模型，Claude Code 在终端里读一套环境变量，Codex 又有自己的 provider / profile 配置。再加上 Dify、OpenWebUI、Cherry Studio 这些工具，最后经常出现一种情况：同一个模型，在 A 工具里能跑，在 B 工具里就报错。
Codex 这类本地代码代理尤其明显。它不是简单问答，而是会读项目、改文件、跑命令、看测试结果。一次任务链路比普通聊天长很多，所以 API 配置只要有一点不清楚，排错成本就会被放大。
这篇只记录一套比较实用的检查方法，重点看三个字段：
Base URL API Key Model Name一、先确认 Codex 适合什么场景
我一般不会把 Codex 当成普通聊天工具用。
更适合它的场景是：
- 读一个陌生项目的结构
- 根据报错定位相关文件
- 修改代码后运行测试
- 根据测试失败继续修
- 帮忙补一段脚本
- 做一次小范围代码审查
- 把一个需求拆成几步执行
这类任务和普通问答不一样。普通聊天失败了，大不了重新问一次；本地代码代理中途失败，可能已经读了一半项目、改了一部分文件、跑了一半命令，这时候再排查 API 配置就很烦。
所以在让 Codex 接手项目任务之前，最好先用最小请求确认接口能跑通。
二、不要一上来就跑完整项目
很多人配置好模型后，第一件事就是让工具分析整个仓库。
不建议这样。
更稳的顺序是先跑一个非常小的任务：
请只用一句话介绍你自己。或者：
请只阅读 README，并总结项目启动方式。如果这种短请求都失败，说明基础配置还没通，不要急着让它改代码。
我习惯按这个顺序排查：
- 先确认 Base URL
- 再确认 API Key
- 再确认 Model Name
- 最后再看 Codex 的 provider / profile 配置
- 小任务能跑通后，再扩大到项目级任务
三、Base URL 最容易错在 /v1
Base URL 表示请求发到哪里。
常见形式是：
https://www.aifast.club/v1最常见的坑是/v1。
有些工具要求你填完整地址，有些工具会自动拼接路径。配置错了以后，可能会变成下面这种错误地址，注意不要直接复制：
https://www.aifast.club/v1/v1也可能少一段路径，请求到了下面这种不完整地址，同样不要直接复制：
https://www.aifast.club如果你看到 404，不要第一时间怀疑模型不可用，先查 Base URL。
排查时每次只改一个变量。比如先只改/v1，不要同时换 Key、换模型名、换 provider。否则你很难知道到底是哪一步修好的。
四、API Key 不要放进项目仓库
API Key 是身份凭证，Codex 这种本地代理工具尤其要注意。
因为它会读取项目文件，也可能根据任务生成或修改配置文件。如果你把 Key 写进项目目录，一不小心就可能被提交到 Git。
建议：
- 不要把 Key 写进公开仓库
- 不要把 Key 放进截图
- 不要把 Key 写进 README
- 项目级配置尽量不要放敏感信息
- 个人 Key 优先放用户级配置或环境变量
- 团队项目里不要共用个人 Key
遇到 401 时，优先检查：
- Key 是否复制完整
- 前后是否有空格
- Key 是否已经失效
- Key 是否有当前模型权限
- 当前 shell 环境里是不是还有旧 Key
- 项目配置是否覆盖了用户配置
很多时候你以为自己刚刚换了 Key，但工具实际读取的还是旧环境变量。
五、Model Name 不要手打
很多接口问题最后都会落到模型名。
典型报错是：
model not found这个错误不一定说明模型不存在，更多时候是当前配置里的模型名不对。
常见原因：
- 填了展示名称，不是接口模型名
- 大小写不一致
- 少了版本号
- 少了后缀
- 当前 Key 没有该模型权限
- 当前 profile 还引用旧模型
- 模型已经改名或下架
我的习惯是：模型名只从控制台或文档复制，不手打。
如果 Codex 报model not found，可以按这个顺序查：
- 复制控制台里的真实模型名
- 检查 Codex 当前 profile 是否引用旧模型
- 检查 provider 配置里是否有另一个默认模型
- 用同一个模型名在其他客户端发短请求
- 如果其他客户端能跑通，再回头看 Codex 配置
六、用户级配置和项目级配置要分开
Codex 这类工具通常会有用户级配置，也可能会有项目级配置。
可以简单理解为：
用户级配置：个人默认习惯 项目级配置：当前项目的规则和约束例如用户级配置可以放：
- 默认模型
- 默认 provider
- 常用 profile
- 个人偏好
项目级配置更适合放：
- 项目说明
- 项目任务规则
- 是否允许执行某些命令
- 团队约定
但有一点要注意：项目级配置不适合放 API Key。
因为项目目录里的文件很容易被提交、共享、打包或复制。如果里面写了密钥，后面很难控制传播范围。
七、一个最小配置检查模板
接入新接口时，可以先用这个模板对照：
Base URL: https://www.aifast.club/v1 API Key: sk-xxxx Model Name: 从控制台复制真实模型名 Test Prompt: 请用一句话介绍你自己如果你同时测试 Claude、Gemini、DeepSeek、GLM、Kimi、豆包等模型，可以先用支持 OpenAI Compatible 的统一入口做最小验证。
例如 AI快站这类平台，可以把多个模型放在同一套 Base URL / API Key / Model Name 的逻辑里测试。这里重点不是依赖某个平台，而是先把配置变量收敛到最少。
八、几个常见报错的判断顺序
1. 401 Unauthorized
优先查 API Key。
不要先改模型名，也不要先换 Base URL。先确认 Key 是否有效、是否有权限、是否被旧环境变量覆盖。
2. 404 Not Found
优先查 Base URL。
重点看：
- 是否少了
/v1 - 是否重复成了
/v1/v1 - 是否把网页地址当成 API 地址
- provider 是否实际读取了另一个 endpoint
3. model not found
优先查 Model Name。
尤其要注意展示名和真实接口模型名不是一回事。
4. timeout
timeout 不一定是接口不可用。
可能是：
- 项目上下文太大
- 一次读取文件太多
- 模型响应慢
- 网络链路不稳定
- 任务本身拆得太大
先让 Codex 只读一个文件，或者只总结 README。如果小任务能跑通，再逐步扩大范围。
九、我会怎么记录配置
如果同时用 Codex、Cursor、Claude Code、Dify、OpenWebUI，我建议做一张简单表。
| 工具 | 使用位置 | 关键配置 | 主要用途 | 排错优先级 |
|---|---|---|---|---|
| Codex | 本地终端 / IDE | provider、model、Base URL、Key 来源 | 读代码、改代码、跑测试 | 先查 provider 和模型名 |
| Cursor | 编辑器 | Base URL、API Key、Model Name | 高频代码编辑 | 先查 /v1 和模型名 |
| Claude Code | 终端 | 环境变量、模型名 | 项目分析、日志排查 | 先查环境变量 |
| Dify | 工作流平台 | 模型供应商、Base URL、Key | 应用、知识库 | 先查供应商配置 |
| OpenWebUI | 自建面板 | 自定义服务商、模型列表 | 多模型测试 | 先查接口地址 |
这张表不是为了好看，而是为了排错时少猜。
某个工具不能用时，先问五个问题：
- 它实际用的是哪个 Base URL？
- 它读取的是哪个 API Key？
- 它填的是哪个模型名？
- 同一个模型在其他工具里能不能跑通？
- 是工具配置问题，还是接口入口问题？
十、什么时候需要统一接口入口
如果只用 Codex 和一个模型，没必要把事情复杂化。
但如果你同时用：
- Codex
- Cursor
- Claude Code
- Dify
- OpenWebUI
- Cherry Studio
- n8n
- Cline
并且还要测试：
- Claude
- Gemini
- DeepSeek
- GLM
- Kimi
- 豆包
- 图片模型
- 视频模型
- 检索模型
那统一接口入口就会省很多时间。
它的价值不是“换个平台就不会出错”，而是让配置变得可复用、可排查、可同步。
特别是团队里多人共用工具链时，统一 Base URL、模型名来源和配置记录，会比每个人自己摸索稳定得多。
十一、使用 Codex 前的安全提醒
Codex 能读项目，也可能改项目，所以不要完全当聊天窗口看。
我一般会注意几件事：
- 先看它准备改哪些文件
- 修改后检查 diff
- 不让它随便处理敏感配置
- 跑命令前看清楚命令内容
- 大任务拆成小任务
- 不熟悉的项目先只读不改
- API Key 不放项目里
这不是不信任工具，而是本地代码代理本来就应该有边界。
十二、总结
Codex 真正有价值的地方，不是多回答几句话，而是参与本地工程流程：读代码、改代码、跑命令、看测试结果。
但要让它稳定工作，API 配置必须先理顺。
遇到问题可以按这个顺序排查：
- 401 先查 API Key
- 404 先查 Base URL
- model not found 先查模型名
- timeout 先缩小上下文和任务范围
如果你同时使用 Codex、Cursor、Claude Code、Dify、OpenWebUI，建议先把 Base URL、Key 来源、模型名记录清楚。后面无论换 Claude、Gemini、DeepSeek、GLM、Kimi 还是豆包，都不会每换一个工具就重新踩一遍坑。