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	自建面板	自定义服务商、模型列表	多模型测试	先查接口地址