OpenAI Codex CLI 接入兼容 API：Responses 协议完整教程¶

最后核验：2026-09-21

适用范围：当前版本 Codex CLI

关键前提：自定义提供方必须支持 OpenAI Responses API

[!NOTE] 本文适用于任何符合对应协议的 API。还没有测试 Key 时，可查看教程配套 API。

需要先判断 Base URL、模型和验证顺序时，可查看 NexoToken Codex API 与 Base URL 专题；本文继续保留完整 CLI 配置与排错步骤。

需要逐项核对 config.toml 时，可配合 NexoToken Codex config.toml 配置专题使用。

需要在本机持续观察 Codex 任务进度、Token、费用精度和验证状态时，可查看 Agent Doctor by NexoToken。它不会替代 Codex，也不会要求上传完整项目。

直接回答：Codex API Key 配置的关键是把密钥放入环境变量，在 config.toml 中声明模型提供方、Base URL 与 Responses 协议，然后用 /status 和最小任务核对实际生效配置。还没确定服务是否适配时，先看 API 中转站选择与使用指南。

1. Codex CLI 是什么¶

Codex CLI 是在终端中工作的编程代理，可以检查代码、修改文件、运行命令、执行测试和做代码审查。

这篇教程使用 Codex 官方的 model_providers 配置连接自定义 API。不要照搬只修改 OPENAI_BASE_URL 的旧教程；当前官方配置支持为每个提供方分别指定 Base URL、Key 环境变量和协议。

2. 接口兼容性必须先确认¶

Codex 自定义提供方当前使用 responses 协议。服务商至少需要正确实现：

POST /v1/responses

只支持 /v1/chat/completions 的接口不能直接用于本教程。即使普通聊天客户端可用，也不代表 Codex 的工具调用、流式事件和 Responses 输入输出格式完整兼容。

可以在纽智中转站创建 API Key，并选择明确标注支持 Codex/Responses 的模型。

3. 安装 Codex CLI¶

以下地址来自 Codex 官方安装说明。高安全环境建议优先使用 npm / Homebrew，或先下载并审阅安装脚本，再决定是否执行。

macOS / Linux 官方安装器¶

curl -fsSL https://chatgpt.com/codex/install.sh | sh

npm¶

先安装当前 LTS 版 Node.js，然后执行：

npm install -g @openai/codex

Homebrew¶

brew install --cask codex

Windows¶

Codex CLI 的 Windows 支持仍可能受版本和项目工具链影响。优先在 WSL 2 中按 Linux 方式安装；如需在 PowerShell 中尝试，可先安装 Node.js LTS，再执行：

npm install -g @openai/codex

依赖 Bash、Linux 权限语义或 Linux 构建工具链的项目更适合在 WSL 2 内安装并运行。安装后重新打开终端。

4. 验证安装¶

codex --version
codex --help

如果找不到命令：

npm 安装：检查 npm 全局 bin 目录是否在 PATH；
官方安装器：重新打开终端；
Windows：确认是在安装时使用的同一环境中运行，避免把 WSL 和 PowerShell 混用。

5. 设置 API Key 环境变量¶

本教程把 Key 放在自定义变量 NEXO_API_KEY 中。变量名可以自定义，但必须与后面 env_key 完全一致。

macOS / Linux / WSL¶

export NEXO_API_KEY="你的APIKey"

Windows PowerShell¶

$env:NEXO_API_KEY = "你的APIKey"

Windows CMD¶

set NEXO_API_KEY=你的APIKey

第一次先使用临时变量。确认配置成功后，再决定是否写入 shell 配置或系统凭据管理工具。

6. 创建 Codex 配置文件¶

用户级配置路径：

macOS/Linux/WSL：~/.codex/config.toml
Windows：%USERPROFILE%\.codex\config.toml

写入以下内容，并替换三处示例值：

model = "从模型列表复制的模型ID"
model_provider = "nexotoken"
model_reasoning_effort = "medium"

[model_providers.nexotoken]
name = "NexoToken"
base_url = "从控制台复制的ResponsesBaseURL"
env_key = "NEXO_API_KEY"
wire_api = "responses"

配置说明：

字段	含义
`model`	实际发送给接口的模型 ID
`model_provider`	选择下面定义的提供方 ID
`model_reasoning_effort`	可选思考等级，放在顶层；示例 medium 不是平台强制默认值
`base_url`	Responses API 的 Base URL，通常以 `/v1` 结尾，以控制台说明为准
`env_key`	Codex 从哪个环境变量读取 Key
`wire_api`	当前自定义提供方只支持 `responses`

openai、ollama、lmstudio 是 Codex 内置提供方 ID，不要拿它们作为自定义表名覆盖。这里使用独立 ID nexotoken。

6.1 设置思考等级：CLI、CI 与 API¶

本节于 2026-09-13 核对官方参数文档与 NexoToken 当前转发代码；不是对每个模型、每个等级的付费调用认证。

已有配置示例中的 model_reasoning_effort = "medium" 就是思考等级。要改成更深入的推理，在同一位置改为：

model_reasoning_effort = "high"

它必须位于 config.toml 顶层、所有 [表名] 之前，不能写在 [model_providers.nexotoken] 内。同一层不要重复添加该字段。用户级文件通常位于 ~/.codex/config.toml；设置了 CODEX_HOME 时以该目录为准，Windows 默认在 %USERPROFILE%\.codex\config.toml。

只覆盖本次 CLI 或 CI 任务¶

完成前面的 provider、Base URL 和环境变量配置后，在 Bash、zsh 或 PowerShell 中执行：

codex -c 'model_reasoning_effort="high"'

codex exec -c 'model_reasoning_effort="high"' "解释项目结构，不修改文件"

这里的 -c 是配置覆盖参数，不是模型名的一部分。CI 从平台的 Secret 管理中注入 NEXO_API_KEY，不要在流水线正文写入真实密钥。命令行覆盖只影响本次启动；项目配置、profile 和当前会话选择也可能影响最终设置。确认客户端版本支持该值，并检查实际生效配置，不能仅凭回答长短判断思考等级。

等级如何选择¶

等级	使用方向
`low`	简单任务，优先速度
`medium`	日常任务的均衡起点
`high`	更复杂的分析和代码任务，可能增加耗时与 Token 用量
`xhigh`	仅在模型和客户端明确支持时使用

none、minimal、max、ultra 等值不能当作所有模型通用的选项；客户端界面名称也不一定等于 API 值。不要给 GPT-4o、图片或音频模型套用此参数。省略配置不代表固定使用 medium：客户端可能自行发送默认值；请求未携带该字段时，平台不统一补充思考等级。

直接调用 API 时怎么写¶

以下是完整请求体示例；替换模型 ID，并配合前文的 Base URL、Bearer 鉴权使用。所选模型必须支持对应接口与思考等级。

Responses：POST /v1/responses

{
  "model": "YOUR_RESPONSES_MODEL",
  "input": "Explain binary search briefly.",
  "reasoning": { "effort": "high" },
  "stream": true
}

Python SDK 在 client.responses.create(...) 中添加 reasoning={"effort": "high"}。

Chat Completions：POST /v1/chat/completions

{
  "model": "YOUR_CHAT_MODEL",
  "messages": [{ "role": "user", "content": "Explain binary search briefly." }],
  "reasoning_effort": "high",
  "stream": true
}

Python SDK 在 client.chat.completions.create(...) 中添加 reasoning_effort="high"。两个接口字段结构不同，不要混用，也不要在 API 请求中发送 model_reasoning_effort。

NexoToken 是否透传¶

原生 Chat Completions 与 Responses 转发保留客户端提交的思考字段，不统一强制为 high 或 medium。
部分兼容处理会把 minimal 转为 none；特定 GPT-5.6 上下文压缩子请求会把 max 转为 xhigh，不能承诺所有路径逐字透传。
跨协议转换不保证等价保留思考设置。GPT 模型优先使用其支持的原生接口，Codex CLI 使用 Responses。
透传不等于模型支持。请求成功也不能单独证明实际采用了指定等级；以模型能力、接口响应及可用的用量信息综合核验。
平台网页聊天目前没有主动发送思考等级；CLI 与 API 可以按上述方式明确指定。

遇到参数不支持错误，先确认模型 ID、接口与客户端版本，再改用已支持等级或移除可选参数。不要只换字段名反复重试。

参考：Codex 配置参考、Codex CLI 参数、OpenAI 模型参数指南。

7. TOML 常见语法错误¶

正确：

model = "模型ID"

[model_providers.nexotoken]
base_url = "https://示例地址/v1"

容易出错的情况：

使用中文引号；
同一字段写两次；
把 [model_providers.nexotoken] 写成 JSON 花括号；
Base URL 后误加 /responses；
model_provider 的值与表名不一致；
把真实 Key 直接写入 config.toml。

官方不建议把 bearer token 明文写进配置，应使用 env_key。

8. 启动第一个会话¶

进入一个 Git 项目：

cd /你的项目目录
codex

第一次建议使用只读任务：

请只分析这个项目的目录结构和启动方式，不要修改文件，不要安装依赖。

进入会话后运行：

/status

检查：

Provider 是否为 nexotoken；
Model 是否为你配置的模型 ID；
当前目录是否正确；
权限和沙箱是否符合预期。

9. 首次写入测试¶

不要直接在重要仓库做第一次写入。可以创建一个临时 Git 仓库：

mkdir codex-test
cd codex-test
git init
printf '# Codex Test\n' > README.md
git add README.md
git commit -m "chore: initial checkpoint"
codex

然后输入：

在 README.md 末尾增加一行“配置验证成功”，完成后展示 diff，不要提交。

检查 diff 正确后再进入真实项目。

Windows PowerShell 如果没有 printf，可用以下命令创建测试文件：

New-Item -ItemType Directory codex-test
Set-Location codex-test
git init
Set-Content -Path README.md -Value "# Codex Test"
git add README.md
git commit -m "chore: initial checkpoint"
codex

10. 权限与沙箱建议¶

用户级配置可使用较保守的默认值：

approval_policy = "on-request"
sandbox_mode = "workspace-write"

workspace-write 允许在工作区内修改，但限制工作区外写入；
on-request 会在需要时请求确认；
不建议为了省确认步骤长期使用不受限制权限；
执行数据库、部署、删除文件和发布操作前必须人工复核。

11. 为项目添加 AGENTS.md¶

在仓库根目录运行 /init 可以生成 AGENTS.md。它适合记录：

项目启动与测试命令；
包管理器要求；
代码风格；
禁止修改的目录；
完成任务前必须执行的检查。

不要把 API Key、数据库密码或私人信息写进 AGENTS.md，因为它通常会提交到仓库。

12. 常用命令¶

命令	用途
`codex`	在当前目录启动
`codex --version`	查看版本
`codex resume`	恢复之前的会话
`codex exec "任务"`	非交互执行单个任务
`/status`	查看会话配置
`/model`	选择模型与推理强度
`/permissions`	查看或调整权限
`/review`	审查代码改动
`/init`	为项目生成 AGENTS.md

自动化中使用 codex exec 前，先在交互模式验证模型、权限和输出。不要把可写权限的 Codex 暴露给不可信的公开输入。

13. 常见错误排查¶

Missing environment variable / Key 未设置¶

env_key 写的是 NEXO_API_KEY，环境变量也必须同名。确认变量存在，但不要打印完整 Key：

test -n "$NEXO_API_KEY" && echo "Key 已设置" || echo "Key 未设置"

PowerShell：

if ($env:NEXO_API_KEY) { "Key 已设置" } else { "Key 未设置" }

401 Unauthorized¶

Key 复制不完整；
Key 已失效；
打开了新终端但没有重新设置临时变量；
env_key 拼写错误。

403 / 模型无权限¶

确认 Key 分组、模型分组和模型 ID 匹配，并检查余额或免费额度适用范围。

404 Not Found¶

Base URL 是否以服务商要求的 /v1 结尾；
是否误写成完整 /v1/responses；
服务端是否真的提供 Responses API；
是否把网站控制台地址当成 API 地址。

400 / Unsupported parameter / Invalid event¶

这是协议兼容性问题的常见表现。Codex 需要 Responses 流式事件、工具调用及相关字段。更新 Codex 后，用明确支持 Codex 的模型重试；普通 Chat Completions 能用不能证明 Responses 完整兼容。

模型 ID 无效¶

复制准确模型 ID，区分大小写。显示名称、昵称和模型 ID 不是一回事。

请求中途断开¶

使用短任务和小仓库重试；
降低上下文规模；
暂时关闭额外 MCP 工具；
更新 Codex；
保留请求 ID 和时间点，联系服务商排查。

14. 升级和回退配置¶

升级 Codex：

npm install -g @openai/codex@latest

Homebrew：

brew upgrade --cask codex

如果要恢复官方登录方式：

从 config.toml 删除或注释自定义 model_provider 和对应表；
清除自定义 Key 环境变量；
运行 codex login；
用 codex login status 和 /status 双重确认。

15. 官方资料¶

常见问题 FAQ¶

为什么 `config.toml` 写好了仍走官方登录？¶

通常是配置文件位置、provider 名称或环境变量未被当前终端加载。先运行 codex login status 和 /status，不要只根据界面猜测。

Chat Completions 可用，Codex 为什么仍报错？¶

Codex 的自定义提供方通常需要 OpenAI Responses API。仅支持 /v1/chat/completions 的服务不能因此视为完整兼容。

求助时请提供 Codex 版本、操作系统、错误码、模型 ID、Base URL 是否含 /v1 和 /status 的非敏感部分。API Key 必须完全遮住。