OpenAI Codex 怎么配置 API？安装→认证→Responses 兼容性→首次验证

更新于 2026-11-01 · gpt.boats

简答：OpenAI Codex CLI 的配置顺序是：先安装并确认命令可用，再选择 ChatGPT 登录或 API Key，最后核对模型、Base URL 和 Responses API 兼容性。只支持 `/v1/chat/completions` 的服务，不能直接按 Codex 兼容处理；还要继续确认工具调用、输入输出结构、流式行为和权限。本文资料核验日期为 2026 年 11 月 1 日。

定义：Codex API 配置，是为 Codex CLI 指定认证方式、模型、提供商地址和请求协议，使本地编码代理能够向目标模型服务发起请求。

30 秒决策卡：先判断你该用哪种配置

本文面向需要在本地使用 Codex CLI 的开发者，重点解决“安装后如何接入 API、如何判断兼容接口能不能用”这一个问题。本文是第三方资料整理内容，不是 OpenAI 或 Codex 官方页面；具体模型、权限、区域和计费规则应以当前官方文档及控制台为准。

Codex API 配置决策卡

你的场景	优先选择	先核对什么
本地交互式开发	ChatGPT 登录	账户或工作区是否具备当前 Codex 使用权限
脚本、自动化或 CI	API Key 登录	Key 是否有效、账户是否可调用目标模型
接入兼容网关	自定义提供商	是否提供 Responses API，而不是只有 Chat Completions
出现 401 或 404	先看响应体和最终 URL	凭据、路径、模型名、权限和 Base URL 拼接

最关键的判断：Codex 当前配置参考将提供商协议字段 wire_api 的支持值列为 responses。因此，仅声明“OpenAI 兼容”或仅提供 /v1/chat/completions，都不足以证明可以完整接入 Codex。应继续核对 Responses 请求结构、工具能力、流式事件、模型权限和服务方的兼容说明。可参考Codex 配置参考。

第一步：安装 Codex CLI，先确认命令可用

截至 2026 年 11 月 1 日，OpenAI Codex 官方仓库 README 列出了独立安装脚本、npm、Homebrew 和 GitHub Releases 等路径。安装路径应以当前仓库说明为准，不建议把旧教程中的版本号或下载地址直接复制使用。

macOS 或 Linux 可先使用官方独立安装脚本：

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

Windows PowerShell 可使用：

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

如果你已经使用 Node.js，也可以选择 npm：

npm install -g @openai/codex

macOS 用户还可以选择 Homebrew：

brew install --cask codex

安装后先执行：

codex --version

如果命令不存在，优先检查安装目录是否已经加入当前终端的 PATH，不要仅凭安装脚本没有报错就判断安装完成。官方仓库还说明，独立安装器默认从 OpenAI 的 Codex 发布地址下载，在元数据或资源不可用时回退到 GitHub Releases；安装位置和环境变量以当前脚本为准。可查看Codex 官方仓库 README。

第二步：选择 ChatGPT 登录或 API Key 登录

Codex CLI 当前支持两类个人登录方式：ChatGPT 登录，以及按 API 用量计费的 API Key 登录。二者不是同一种凭据，也不代表完全相同的权限范围。

方案一：ChatGPT 登录

适合本地交互式使用。运行：

codex login

随后按浏览器流程完成登录。官方认证文档说明，Codex CLI 在没有有效会话时会使用这一登录路径。

方案二：API Key 登录

适合脚本、自动化和 CI/CD。先在安全环境中设置示例变量，再通过标准输入交给 Codex：

printenv OPENAI_API_KEY | codex login --with-api-key

macOS 或 Linux 当前终端可使用：

export OPENAI_API_KEY="YOUR_API_KEY"

Windows PowerShell 可使用：

$env:OPENAI_API_KEY = "YOUR_API_KEY"

YOUR_API_KEY 只是示例值，发送请求前必须替换为你自己创建并核对过的 Key。不要把真实 Key 写入 Git、浏览器前端、公开日志、截图或共享脚本。官方认证文档明确说明，API Key 用量按 OpenAI Platform 的标准 API 规则计费，部分依赖 ChatGPT 工作区或云端能力的功能可能受限。

两种认证方式对比

认证方式	适合场景	核验重点
ChatGPT 登录	本地交互式开发	工作区、角色权限和当前计划是否支持所需功能
API Key	脚本、自动化和 API 工作流	Key 状态、模型访问权限、API 账户设置

查看当前认证方式可以运行：

codex login status

清除已保存凭据可以使用：

codex logout

这两个命令以及 API Key 登录命令均可在Codex 认证文档中核对。若环境采用工作负载身份认证，登录和退出命令的行为可能不同，应以当前认证方式为准。

第三步：在用户级 config.toml 中配置模型和提供商

用户级配置文件通常位于 ~/.codex/config.toml。项目级配置可放在仓库中的 .codex/config.toml，但官方文档说明，项目级配置只会在项目被信任时加载。配置解析还受命令行参数、项目配置、用户配置、系统配置和内置默认值影响，因此遇到“写了配置却没生效”时，不能只检查文件内容。

下面是示例值配置卡，发送请求前必须核实：

model = "YOUR_RESPONSES_MODEL" model_provider = "custom" [model_providers.custom] name = "Custom Responses Provider" base_url = "https://api.example.com/v1" env_key = "CUSTOM_API_KEY" wire_api = "responses"

model：目标模型 ID，必须从当前提供商文档或控制台复制。
model_provider：指向 model_providers 中的提供商标识。
base_url：提供商基础地址，是否包含 /v1 不能猜测。
env_key：指定从哪个环境变量读取 Key，变量名不一定是 OPENAI_API_KEY。
wire_api：当前配置参考列出的协议值为 responses；这不等于所有 Codex 功能都自动可用。

项目级配置未生效时，先做三个检查：确认当前目录属于目标项目；确认该项目在 Codex 中被信任；确认没有使用命令行 --config 或其他更高优先级配置覆盖文件值。官方配置基础文档列出了项目配置的加载条件和优先级，可查看Codex 配置基础。

第四步：判断兼容接口是否真的适合 Codex

接口兼容性应分成两个层次判断，而不是只看服务商是否写着“OpenAI 兼容”。

Codex 兼容性核验矩阵

核验层次	需要确认的内容	结论
能否建立请求	Base URL、认证方式、模型 ID、Responses 路径和响应结构	只能说明接口可请求
Codex 功能是否完整	工具调用、输入输出结构、流式事件、模型能力和权限	需要逐项核对，不能由“兼容”二字推断
仅支持 Chat Completions	只有 `/v1/chat/completions` 入口	不能直接按 Codex 的 Responses 提供商配置
模型或路径未公开	无法确认模型、权限或最终请求路径	未核实，不要复制占位值运行

官方配置参考把 wire_api 的协议值限定为 responses，OpenAI API 文档则将 Responses API 的请求、响应和流式事件单独列出。因此，第三方网关即使能处理某个 Responses 请求，也仍需继续确认 Codex 使用的工具调用、输入输出字段、流式行为和模型权限。相关 API 结构可参考OpenAI API Reference和Developer quickstart。

最小验证：四项成功判定必须全部满足

配置完成后，不要只看命令是否启动。按以下顺序验证：

运行 codex --version，确认 CLI 已进入当前终端的 PATH。
运行 codex login status，确认认证方式与预期一致。
确认 Key 或自定义变量不为空，但不要打印完整凭据。
在可安全操作的项目目录运行 Codex，先提交只读任务，例如“列出当前目录的主要文件，不修改文件”。

四项成功信号分别是：命令启动成功、认证状态正确、返回实际文本、客户端没有出现模型或协议错误。若需要单独测试 OpenAI API，可参考官方 Responses 请求格式：

curl https://api.openai.com/v1/responses -H "Authorization: Bearer $OPENAI_API_KEY" -H "Content-Type: application/json" -d '{"model":"YOUR_RESPONSES_MODEL","input":"Say this is a test."}'

该示例中的模型名是占位值，URL、模型和 Key 在发送前都必须核实。不要把真实 Key 直接写入公开脚本或容易进入 shell 历史的命令。

常见报错：按凭据→URL→模型→权限→响应体排查

Codex API 配置排查顺序

现象	优先检查	避免的误判
401	登录状态、Key 是否为空、是否撤销、认证方式是否匹配	不能仅凭 401 判断是模型或 IP 问题
403	账户、工作区、模型访问资格和区域限制	不能泛化为 Key 一定错误
404	最终 URL、Base URL 是否重复或缺少路径、模型 ID	不能只改模型名而不看响应体
协议字段错误	服务是否真的支持 Responses，以及响应结构是否匹配	不能把 Chat Completions JSON 原样套入 Responses
命令找不到	安装目录、PATH 和当前终端会话	不能只重复安装而忽略 PATH

排错时记录最终请求 URL、状态码、响应体摘要和必要日志，但必须删除 API Key、Cookie 和完整 Authorization 头。OpenAI API 错误文档也建议根据具体错误类型和响应信息排查认证、请求格式、网络连接和超时，不应只根据状态码做固定归因，可查看API 错误代码文档。

环境变量与状态目录：只保留当前确实需要的配置

Codex 的状态目录可通过 CODEX_HOME 调整，官方高级配置文档说明其默认目录为 ~/.codex。该目录可能包含配置文件、历史记录、日志、缓存，以及在文件凭据存储模式下的 auth.json；也可能使用操作系统的密钥环或凭据存储。

常见变量和文件

项目	已核实用途	注意事项
`OPENAI_API_KEY`	常用于 API Key 登录流程	不要提交到仓库或公开日志
`CODEX_HOME`	调整 Codex 本地状态目录	修改后需重新确认配置和凭据位置
`CODEX_INSTALL_DIR`	独立安装脚本使用的安装目录变量	安装后仍需检查该目录是否在 PATH 中
`CODEX_NON_INTERACTIVE`	独立安装脚本使用的非交互安装变量	跳过提示不等于完成认证
`~/.codex/config.toml`	用户级配置文件	适合保存个人默认模型和提供商配置
`.codex/config.toml`	项目级配置层	项目不受信任时可能跳过该层

CODEX_INSTALL_DIR 和 CODEX_NON_INTERACTIVE 的具体安装器行为可从Codex 官方安装脚本核对；状态目录、配置文件和凭据存储方式可参考Codex 高级配置与Codex 认证文档。

常见问题

OpenAI Codex 一定要配置 API Key 吗？

不一定。Codex CLI 支持 ChatGPT 登录，也支持 API Key 登录。本地交互式使用可以先运行 codex login；脚本、自动化或 CI/CD 场景再考虑 API Key。两种方式的权限、数据策略和计费体系不同。

Codex 能直接连接只支持 Chat Completions 的接口吗？

不能直接这样判断。当前配置参考将提供商协议值列为 responses，因此仅支持 /v1/chat/completions 的服务不能直接按 Codex 提供商配置。还应确认 Responses 请求结构、工具调用、流式行为、模型能力和权限。

OPENAI_API_KEY 设置了，Codex 仍提示未认证怎么办？

先运行 codex login status，确认当前认证方式；再确认当前终端能够读取变量但不要打印完整 Key。如果配置了自定义提供商，还要检查 env_key 是否与实际变量名一致。API Key 登录流程可按官方文档使用标准输入传递。

Base URL 要不要手动加 /v1？

不能一概而论。Base URL 应按当前提供商文档填写，最终请求路径必须与 Responses API 入口匹配。多写或少写 /v1 都可能导致 404，应查看最终 URL 和响应体，不要只反复更换模型名。

项目里的 .codex/config.toml 为什么没有生效？

可能原因包括项目未被信任、当前目录不在目标项目范围内，或命令行参数和其他高优先级配置覆盖了文件值。官方配置基础文档说明，不受信任的项目会跳过项目级 .codex 配置层。

Codex 的凭据会保存在哪里？

官方文档说明，Codex 的本地状态默认位于 CODEX_HOME 指向的目录，凭据可能以 auth.json 文件保存，也可能使用操作系统的密钥环或凭据存储。不要把这些文件提交到仓库；具体存储方式应按当前认证配置核对。

Codex 接口能返回文本，是否就代表所有功能都可用？

不代表。返回文本只能说明基础请求可能成功。还要继续测试工具调用、输入输出结构、流式事件、模型能力、权限和错误处理，才能判断是否适合完整 Codex 工作流。