Codex CLI 接第三方 API 的常见失败，几乎都不是“协议不支持”，而是被几样假设一起搞错：CLI 版本记错、配置改在错的那一层、Key 还没验证就去动 CLI、或者把一年前的博客片段直接复制到新版本里。先在客户端外验证 API，再改 Codex 配置，是最稳的顺序。
2026-08-09 的隔离测试用 Codex CLI 0.146.0 接入 MonkeyAI，profile 名 monkeyai，Key 写进 $CODEX_HOME/.env。一次真实 codex exec 请求被发到 https://monkeytheme.com/v1/responses，MonkeyAI 按预期返回 401 INVALID_API_KEY（测试用假 Key）。移除 .env 后，错误从 401 变为 Missing environment variable: MONKEYAI_API_KEY，证明 .env 确实被读取。
本教程不验证「任何 Codex CLI 版本都按同一套字段工作」这种强结论。Codex CLI 的 model_provider、model_providers.* 块和 env_key 字段在 0.146.0 有效；更早或更新的版本，字段名可能略有差异，写完配置先打一次 /v1/models 验证。
model_provider、model_providers、env_key、requires_openai_auth 字段名，以 codex --help 与本机 ~/.codex 目录下的样例为准。本页只解决「我要接第三方 API 时，按什么顺序验证、按什么层写配置」。
curl -sS https://monkeytheme.com/v1/models -H "Authorization: Bearer $MONKEYAI_API_KEY"。返回 JSON 而不是 HTML，就说明路由、Key、协议都对。codex --version 看清楚本机装的是哪个版本，不要按一年前博客里的字段名直接抄。.env）、config.toml、还是「独立 profile + .env」。三选一，不要两套都改，否则后面对照日志会很乱。/v1/models 实际返回的名字，不要用旧文档里的别名。codex --profile <name> exec --skip-git-repo-check "Reply with OK only" 跑一条真实请求，看到模型真实返回再宣告完成。--skip-git-repo-check 仅用于这次快速验证，正式开发时应进入项目目录再跑。| 项 | 看什么 | 错的多 |
|---|---|---|
| Base URL | https://monkeytheme.com/v1，必须含 /v1 | 客户端配置里写成了根域名 https://monkeytheme.com，于是请求落到 SPA 首页 |
| CLI 版本 | codex --version 实际返回的字符串 | 按 0.30.x 的博客片段写到 0.146.0 上，字段名已变 |
| 配置层 | 环境变量 / config.toml / 自定义 profile，哪一层真的生效 | 改了 ~/.codex/config.toml，但本机 CODEX_HOME 指向别处 |
| 成功信号 | 一条 codex exec 真的能从目标模型拿到回复 | 看到 config.toml 写好就宣告完成，没真的跑 |
config.toml，但 CLI 实际在用环境变量（或反过来）。两层都改一下，看哪个生效的代价太高。/v1/models 实际返回的 ID，别名在账号里可能根本不存在。codex exec 就宣告完成。配置文件的字面正确不等于运行时正确。可以。Codex CLI 的 model_provider 字段允许指向任意 OpenAI 兼容端点。具体写法取决于本机 CLI 版本和生效的配置层。先打一次 /v1/models 验证 Key 与端点，再去动 Codex 配置。
用当前 Key 直接请求一次 Base URL，例如 https://monkeytheme.com/v1/models，确认路由存在、Key 有效、返回的是 JSON 而不是 HTML。返回 JSON 后再去改 config.toml 或 profile。
三类坑占绝大多数：①CLI 版本对错，字段名照旧文档抄；②配置改在错的那一层（改了 config.toml 但 CLI 实际读的是 .env）；③Model ID 用了别名而不是 /v1/models 返回的实际 ID。第三个最容易发生在「换了端点但没换模型名」的场景。
更细的 monkeyai profile 写法：model_providers.monkeyai 块、env_key 指向 MONKEYAI_API_KEY、wire_api = "responses"、requires_openai_auth = false，以及和 ~/.codex/config.toml 不冲突的目录结构。
Key 看起来对却 401，或者路径正确却 404 时，按这条排错顺序逐项验证：路由 → Key → 模型名 → 协议版本。
为什么 Base URL 一定要带 /v1，客户端省略 /v1 时请求会落到哪，以及为什么把根域名当 Base URL 是错的。
MonkeyAI 当前实测的 /v1 路由矩阵：哪些端点支持、哪些返回 404，哪些请求头被认作认证头。配置前先核这个再写。