Codex CLI 接入 OpenAI 兼容 API：安装、配置与模型选择

Codex CLI 连接 OpenAI 兼容 API 网关

Codex CLI 是运行在终端里的编程 Agent。它可以读取仓库、修改文件、执行命令，并在任务过程中请求你的确认。除了默认登录方式，Codex 也支持通过自定义 Provider 连接 OpenAI 兼容 API。

这篇文章以 Nbility Codex 配置文档为例，完成一套可以实际运行的配置，并重点解释：

~/.codex/config.toml 应该怎么写；
API Key 放在哪里，为什么不能提交到 Git；
base_url 为什么要使用 /v1；
wire_api = "responses" 是什么意思；
如何选择模型，并排查认证、路径和流式响应问题。

所有示例均使用 YOUR_API_KEY 占位符。

Codex CLI 与 API 网关如何协作

Codex CLI 负责本地工作区和工具调用，API 网关负责模型请求：

代码仓库 → Codex CLI → OpenAI 兼容 API → 模型
               ↑              ↓
          审批与沙箱      鉴权、路由、计费

Codex 是否能读取或修改文件，由本地沙箱和审批策略决定；模型能否响应，则取决于 API Key、Provider、接口协议和模型权限。这两类问题应该分开排查。

第一步：安装 Codex CLI

使用任意一种包管理器即可。Nbility 文档目前给出的安装方式包括：

npm install -g @openai/codex

也可以使用 pnpm：

pnpm install -g @openai/codex

安装后验证：

codex --version
codex --help

如果这里出现 command not found，先检查全局包目录是否在 PATH 中。此时还没有开始请求模型，不需要修改 API 配置。

第二步：准备 Token 和模型

进入 Nbility Token 管理页面创建独立 Token。建议按设备或用途命名，例如：

codex-personal-laptop
codex-workstation
codex-ci-review

独立 Token 更便于停用、轮换和查看消耗。创建时选择支持 Codex 所需模型的分组，并确认账户余额和权限正常。

模型名称不要从旧教程盲目复制。Nbility 当前文档以 gpt-5.3-codex 为配置示例，但完整可用列表应以你的 Token 页面为准。

第三步：配置 `config.toml`

Codex CLI 的 Provider、API Key、模型和地址配置

Codex 用户级配置位于：

~/.codex/config.toml

先创建目录：

mkdir -p ~/.codex

然后写入配置：

model = "gpt-5.3-codex"
model_provider = "nbility"
preferred_auth_method = "apikey"

[model_providers.nbility]
name = "Nbility OpenAI-compatible API"
base_url = "https://api.nbility.ai/v1"
wire_api = "responses"
query_params = {}
stream_idle_timeout_ms = 300000

几个关键字段分别表示：

model：默认模型 ID；
model_provider：选择下面定义的 nbility Provider；
preferred_auth_method：使用 API Key，而不是账户登录；
base_url：OpenAI 兼容接口根路径；
wire_api = "responses"：使用 Responses API 协议；
stream_idle_timeout_ms：流式响应长时间没有新事件时的等待上限。

这里的 Base URL 应带 /v1：

https://api.nbility.ai/v1

它和 Claude Code 使用的 Anthropic Base URL 不同。不同客户端会按各自协议拼接路径，不能把一款工具的地址格式直接照搬到另一款工具。

OpenAI 官方配置参考还说明：Provider 和认证属于机器级配置，项目目录中的 .codex/config.toml 不能覆盖这些敏感的本地 Provider 设置。因此，自定义 Provider 应放在用户级 ~/.codex/config.toml 中。

第四步：保存 API Key

Nbility 当前 Codex 文档使用：

~/.codex/auth.json

内容如下：

{
  "OPENAI_API_KEY": "YOUR_API_KEY"
}

设置更严格的文件权限：

chmod 600 ~/.codex/auth.json

不要把真实 Key 写入：

项目里的 .codex/config.toml；
AGENTS.md；
Shell 脚本模板；
截图、录屏或工单正文；
Git 仓库中的 .env 示例。

如果 Key 曾经进入 Git 历史，仅删除文件并不够，应立即在控制台撤销旧 Token 并创建新 Token。

第五步：做最小化验证

进入一个测试仓库：

cd my-project
git status
codex

首次测试建议使用只读任务：

阅读当前仓库结构，总结项目使用的技术栈，不要修改任何文件。

确认响应正常后，再尝试小范围修改：

检查 README 中是否存在失效的本地链接。先说明发现的问题，得到确认后再修改。

Codex 从检查仓库、提出修改到审批后应用变更

每次任务结束后都应该检查：

git status
git diff --check
git diff

API 接通并不等于修改一定正确。Codex 是执行工具，最终仍需通过测试、构建和代码审查验证结果。

模型应该怎么选

模型选择主要看任务难度、速度和成本：

日常小改动

适合速度较快、成本较低的编程模型，例如：

解释代码；
修改文案；
补充简单测试；
定位单文件错误；
生成重复性样板代码。

跨文件功能和重构

需要更强的规划与上下文能力，例如：

跨模块重构；
复杂类型错误；
数据库迁移；
并发和状态问题；
大型 PR 审查。

不要把“更贵”直接等同于“每个任务都更好”。更实用的方法是：日常任务使用性价比模型，困难任务再临时切换强模型。

临时测试其他模型时，可以使用 CLI 的配置覆盖能力，而不必反复编辑文件。具体参数以当前版本的 codex --help 和官方 CLI Reference 为准。

审批和沙箱不要随意关闭

Codex CLI 能执行命令和修改文件，因此 Provider 配置之外，还要关注本地安全策略。

推荐从保守设置开始：

让 Codex 在执行高风险命令前请求确认；
限制可写目录；
不在含有生产密钥的目录里直接启动；
修改前保持 Git 工作区干净；
不使用来源不明的项目指令或脚本；
执行安装、删除和网络上传命令前人工检查。

官方 CLI 支持通过 --ask-for-approval 控制审批策略，也可以用 --cd 指定工作目录。不要为了省一次确认就长期关闭安全边界。

常见错误排查

Codex CLI API 认证、路径、模型和流式响应排查

`401 Unauthorized`

优先检查：

[ ] ~/.codex/auth.json 是否存在
[ ] JSON 是否有效
[ ] 字段名是否为 OPENAI_API_KEY
[ ] Key 是否复制完整，前后是否有空格
[ ] Token 是否被禁用或过期
[ ] Codex 是否读取了预期的 CODEX_HOME

不要通过 cat ~/.codex/auth.json 截图求助。只确认文件存在和 JSON 可解析即可。

`404 Not Found`

通常是 Base URL 或协议不匹配。本文配置应使用：

base_url = "https://api.nbility.ai/v1"
wire_api = "responses"

如果错误地址已经包含重复的 /v1/v1，说明客户端和配置都追加了版本路径。若请求到了不存在的 /chat/completions 或 /responses，则应核对当前 Provider 的 wire_api 及网关兼容能力。

`model not found`

检查 model 是否与 Token 页面展示的完整 ID 一致。常见原因包括：

模型名拼写错误；
使用了已下线的旧模型；
Token 分组不支持该模型；
切换了 Provider，却仍使用另一渠道的模型名。

`429 Too Many Requests`

可能是请求频率、并发、额度或上游容量限制。应降低并发、等待后有限重试，并检查 Token 状态。不要无限循环重试 Agent 任务，因为每次重试都可能产生新的上下文和费用。

一直等待或流式响应中断

检查：

终端网络是否能访问 api.nbility.ai；
代理是否支持长连接和流式响应；
stream_idle_timeout_ms 是否过短；
上游模型是否暂时没有可用容量；
公司网络是否缓存或中断 SSE。

可以适当增加空闲超时，但超时不是越长越好。错误路径或失效 Token 不会因为等待更久而恢复。

修改配置后没有生效

关闭当前 Codex 会话并重新启动。还应确认：

printf '%s\n' "${CODEX_HOME:-$HOME/.codex}"

如果设置了 CODEX_HOME，Codex 读取的可能不是默认 ~/.codex。同时检查命令行 -c key=value 覆盖项，因为它们的优先级高于配置文件。

配置完成后的检查清单

[ ] Codex CLI 可以正常启动
[ ] Provider 放在用户级 ~/.codex/config.toml
[ ] base_url 使用 https://api.nbility.ai/v1
[ ] wire_api 使用 responses
[ ] API Key 只保存在本地认证文件或 Secret 中
[ ] 模型名来自当前 Token 的可用列表
[ ] 首次请求使用只读任务
[ ] 修改后检查 git diff 并运行测试
[ ] 高风险命令保留人工审批

如果你还没有 Token，可以从 Nbility 快速开始创建账户和 API Key，再按照 Codex 集成文档完成配置。遇到无法自行定位的问题，可以在工单页面提交脱敏后的错误码、时间和配置片段。