Codex CLI 接入第三方 API 快速教程：auth.json 与 config.toml 配置

Codex CLI 是面向终端的代码助手。安装后，你可以在本地项目目录中启动 codex，让它阅读代码、生成补丁、解释报错或完成小型重构。

如果你希望 Codex CLI 通过 NixAPI 调用 OpenAI 兼容模型，只需要在用户目录下写入两份配置文件：auth.json 放 API Key，config.toml 指定模型供应商和接口地址。

---

环境准备

先确认本机满足基本运行条件：

• Node.js 22 或更高版本
• npm 10 或更高版本
• 可以访问 https://nixapi.com/v1
• 一个 NixAPI API Key

没有 Key 的话，先打开 NixAPI 控制台 创建。模型名称建议从 NixAPI 支持的模型列表页 复制，避免拼写错误。

Windows 用户建议优先使用 WSL 或 Git Bash。Codex CLI 在类 Unix shell 下的体验通常更稳定。

---

第一步：安装 Codex CLI

macOS / Linux

npm install -g @openai/codex
codex --version

如果全局安装提示权限不足，可以按你的 Node.js 管理方式处理权限，或在 macOS 上临时使用：

sudo npm install -g @openai/codex

也可以用 Homebrew：

brew install codex

Windows

先安装 Node.js 最新 LTS 版和 Git Bash。然后在 PowerShell、CMD 或 Git Bash 中执行：

npm install -g @openai/codex
codex --version

如果提示找不到 codex 命令，通常是 npm 全局安装目录没有加入 PATH。修复 PATH 后重新打开终端。

---

第二步：创建 Codex 配置目录

Codex CLI 会读取用户目录下的 .codex 文件夹：

• macOS / Linux：~/.codex
• Windows：C:\Users\你的用户名\.codex

macOS / Linux 可以直接执行：

mkdir -p ~/.codex
touch ~/.codex/auth.json ~/.codex/config.toml

Windows 如果手动创建文件，注意不要保存成 auth.json.txt 或 config.toml.txt。

---

第三步：写入 auth.json

打开 ~/.codex/auth.json，写入：

{
  "OPENAI_API_KEY": "nix-your-api-key"
}

把 nix-your-api-key 换成你的真实 NixAPI API Key。

注意不要在 Key 前后留下空格，也不要把 Key 放进项目仓库。这里的配置是用户级配置，不需要放到某个代码项目里。

---

第四步：写入 config.toml

打开 ~/.codex/config.toml，写入：

model_provider = "nixapi"
model = "gpt-5.4"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.nixapi]
name = "NixAPI"
base_url = "https://nixapi.com/v1"

字段说明：

• model_provider：当前使用的供应商 ID，需要和 [model_providers.nixapi] 对上
• model：Codex CLI 默认使用的模型
• base_url：NixAPI OpenAI 兼容接口地址，必须写 https://nixapi.com/v1
• preferred_auth_method：使用 API Key 鉴权
• disable_response_storage：关闭响应存储，适合本地开发场景

如果你想换成其他模型，可以改成：

model = "claude-sonnet-4-20250514"

更多可用模型以 NixAPI 支持的模型列表页 为准。

---

第五步：启动并验证

进入任意项目目录，执行：

codex

在 Codex CLI 里输入一个简单任务：

请帮我写一个解析 CSV 文件的 Node.js 工具函数，并说明边界情况。

如果能正常返回代码和解释，说明 Codex CLI 已经通过 NixAPI 调用模型。

---

常见问题

1. 报 Invalid auth

检查 ~/.codex/auth.json 是否是合法 JSON，OPENAI_API_KEY 是否写对，以及 Key 是否来自 NixAPI 控制台。

2. 报连接失败

确认 base_url 是：

base_url = "https://nixapi.com/v1"

也可以用 curl 单独测试：

curl https://nixapi.com/v1/models \
  -H "Authorization: Bearer nix-your-api-key"

3. 模型不可用

模型 ID 和平台支持列表不一致。打开 NixAPI 模型价格页 复制准确模型名，再更新 config.toml。

4. 需要登录 OpenAI 官方账号吗？

不需要。这里使用的是 API Key 鉴权，Codex CLI 会读取 auth.json 中的 Key。

---

小结

Codex CLI 接入 NixAPI 的关键是两份文件：auth.json 管密钥，config.toml 管模型和接口。完成配置后，之后在任意项目目录运行 codex，都可以复用同一套 NixAPI 接入方式。