OpenOx

Codex 怎么配置 API 端点？

更新于 2026-10-25 · openox.cyou

简答：改哪一行取决于连接类型：只替换内置 OpenAI 地址，写 openai_base_url；接代理、网关或本地服务，写自定义 model_provider。Base URL 通常填基础地址，不要手动追加 /responses；端点和认证配置应放在用户级 config.toml 或 profile 中，改完用 codex exec 实际请求验证。

定义：Codex API 端点配置，是通过用户级 config.toml 或 profile 为 Codex 指定请求地址、模型提供商、认证变量和 Responses API 协议的过程。

先看字段对照表：你应该改哪一行？

改哪一行取决于你连接的是什么：只想把内置 OpenAI provider 指向代理或路由，使用 openai_base_url；需要独立的模型、密钥变量或协议设置，使用自定义 model_provider 和 model_providers.<id>。改完可以用一条 codex exec 命令发送最小请求，确认配置是否真的生效。

Codex API 端点配置字段速查
场景应使用的字段填写内容不要混淆的地方
只修改内置 OpenAI provider 的地址openai_base_url服务商要求的基础 URL不要创建 [model_providers.openai] 覆盖内置 provider
代理、路由或第三方网关model_provider、base_url自定义 provider ID、基础 URL、密钥变量通常需要配置 wire_api = "responses"
ChatGPT 登录相关后端chatgpt_base_urlChatGPT 登录使用的后端地址它不是普通 API Key 端点，一般用户不需要修改
Ollama 或 LM Studio 本地模式--oss、--local-provider 或 oss_provider本地 provider 选择本地服务是否支持 Codex 所需协议，要以服务文档为准

OpenAI 的高级配置文档明确区分了内置 provider、ChatGPT 地址、自定义 provider 和本地 OSS provider，可查看Advanced Configuration中的对应说明。

配置文件位置与认证方式

Codex 默认把本地状态保存在 CODEX_HOME 指向的目录中；如果没有设置该变量，默认目录是用户主目录下的 .codex，主要配置文件是 config.toml。因此，macOS 和 Linux 通常编辑：

~/.codex/config.toml

Windows 通常对应：

%USERPROFILE%\.codex\config.toml

如果你设置了 CODEX_HOME，应以该变量实际指向的目录为准。配置目录还可能包含认证文件、历史记录、日志和缓存。相关目录说明见Codex 高级配置文档。

Codex 支持使用 ChatGPT 登录，也支持 API Key。接入代理或网关时，建议先确认对方要求的是 API Key、独立 Token 还是其他认证方式；不要把 ChatGPT 登录凭据当作普通网关密钥使用。API Key 优先放在环境变量或系统密钥管理工具中，不要提交到 Git 仓库。安装、登录方式和 API Key 入口可查看官方Codex README与Authentication。

macOS 或 Linux：当前终端设置变量

export OPENAI_API_KEY="替换为你的 API Key"
export CODEX_HOME="$HOME/.codex"

PowerShell：当前会话设置变量

$env:OPENAI_API_KEY = "替换为你的 API Key"
$env:CODEX_HOME = "$HOME\.codex"

PowerShell：持久保存变量

setx OPENAI_API_KEY "替换为你的 API Key"
setx CODEX_HOME "%USERPROFILE%\.codex"

setx 写入后不会自动更新当前终端，需要关闭并重新打开 PowerShell；密钥也不要直接写进公开项目文件。

方式一：只修改内置 OpenAI provider

如果你只需要让内置 OpenAI provider 通过代理、路由或其他兼容入口发送请求，在用户级 config.toml 中写：

openai_base_url = "https://api.example.com/v1"

这里的地址是占位符，必须替换成服务商文档给出的基础 URL。通常不要手动追加 /responses，因为 Codex 会根据 provider 的协议生成请求路径；最终能否使用，取决于目标端点是否支持 Codex 所需的 Responses API。

官方文档说明，修改内置 OpenAI provider 时应使用 openai_base_url，而不是创建 [model_providers.openai]。如果你把地址指向第三方网关，建议改用 API Key 或单独的自定义 provider，并确认当前登录方式不会把不适用的凭据发送到该地址。字段边界可查看Advanced Configuration 的 provider 配置说明。

方式二：使用自定义 Provider 接代理或网关

当你需要单独设置模型、密钥变量、请求协议或请求头时，使用自定义 provider。下面是一个最小模板：

model = "替换为服务商支持的模型名"
model_provider = "my-gateway"

[model_providers.my-gateway]
name = "My Gateway"
base_url = "https://api.example.com/v1"
env_key = "MY_GATEWAY_API_KEY"
wire_api = "responses"

然后在当前终端设置密钥并启动：

export MY_GATEWAY_API_KEY="替换为网关密钥"
codex

PowerShell 写法：

$env:MY_GATEWAY_API_KEY = "替换为网关密钥"
codex

model_provider 的值必须与 [model_providers.my-gateway] 中的 ID 完全一致，env_key 的值也必须与当前环境中真实存在的变量名一致。base_url 填基础地址，不要默认拼接完整的 /responses 路径；如果服务商文档规定了不同路径，应以该文档为准。

Codex 自定义 provider 的核心是基础 URL、认证方式和 wire API。官方文档还列出了固定请求头、环境变量请求头和命令式认证等配置，具体字段可查看Custom model providers。

Azure、Ollama 与本地服务的配置边界

Azure provider 示例

官方高级配置文档给出了 Azure provider 的配置形态。项目名、模型名和 API 版本必须替换为你自己的值：

model = "替换为 Azure 部署对应的模型名"
model_provider = "azure"

[model_providers.azure]
name = "Azure"
base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai"
env_key = "AZURE_OPENAI_API_KEY"
query_params = { api-version = "2025-04-01-preview" }
wire_api = "responses"

示例中的地址、部署模型和 API 版本不能直接照抄到生产环境，应以 Azure 项目文档为准。Codex 文档把 wire_api = "responses"作为 Responses API provider 的配置项。

Ollama 或 LM Studio 本地模式

官方文档说明，本地 OSS 模式可以使用 Ollama 或 LM Studio：单次运行可用 --oss 和 --local-provider，也可以用 oss_provider 设置默认本地 provider。

# ~/.codex/config.toml
oss_provider = "ollama"

# 单次运行时选择本地 provider
codex --oss --local-provider ollama

如果本地服务只提供 Chat Completions 或其他协议，不能因为 Base URL 能访问就推断 Codex 一定兼容。需要核对服务端是否提供 Codex 所需的 Responses API、模型调用、工具调用和流式响应能力。Cloudflare 的 Codex 接入说明也明确写出，自定义 provider 只支持 OpenAI Responses API，可查看OpenAI Codex 接入文档。

用 profile 隔离多个 API 端点

如果你需要在 OpenAI、代理网关和本地服务之间切换，可以为不同端点建立独立 profile，而不是反复覆盖同一个文件。当前官方高级配置文档说明，运行 codex --profile profile-name 时，Codex 会加载基础 config.toml，再叠加用户目录下的 profile-name.config.toml；profile 文件使用顶层配置键。

# ~/.codex/gateway.config.toml
model = "替换为网关支持的模型名"
model_provider = "gateway"

[model_providers.gateway]
name = "Gateway"
base_url = "https://api.example.com/v1"
env_key = "GATEWAY_API_KEY"
wire_api = "responses"
export GATEWAY_API_KEY="替换为网关密钥"
codex --profile gateway
codex exec --profile gateway "只回复 ok"

较早配置可能使用 [profiles.<name>] 和顶层 profile 选择器，但官方当前文档说明，Codex 0.134.0 及更高版本的 --profile 不再读取这种旧写法，应改用 ~/.codex/<name>.config.toml。如果本机版本行为不同，以Advanced Configuration和本机 codex --help 输出为准。

配置后如何验证：先做最小请求，再看错误位置

  1. 确认加载位置：检查 CODEX_HOME 是否改变，并确认配置文件确实位于该目录。
  2. 确认配置层级：不要把端点、provider 或 profile 只写进项目级 .codex/config.toml。官方文档说明，项目级配置会忽略包括 openai_base_url、chatgpt_base_url、model_provider、model_providers、profile 和 profiles 在内的部分设置，并在启动时提示警告。
  3. 确认字段对应：model_provider = "gateway" 必须对应 [model_providers.gateway]；env_key = "GATEWAY_API_KEY" 必须对应当前 shell 中已设置的变量。
  4. 确认协议和 URL：Base URL 通常填基础地址，不要手工添加 /responses；自定义 provider 还应确认 wire_api = "responses"和服务端能力一致。
  5. 发送最小请求：使用 profile 时直接运行：
codex exec --profile gateway "只回复 ok"

如果不使用 profile，可运行：

codex exec "只回复 ok"

要查看当前版本支持的诊断、状态或配置选项，不要假定某个固定命令一定存在，直接运行：

codex --help
codex exec --help

成功标准是 Codex 能完成一次最小请求，并且返回内容来自你配置的模型端点。若需要确认请求是否经过网关，可查看网关自己的日志或请求记录；以服务商提供的日志功能为准。

Codex API 端点配置排错表
现象优先检查可能位置处理方式
401 或认证失败env_key、环境变量名称、密钥有效性本地环境或网关认证重新导出正确变量，确认网关要求的认证方式，不要把 ChatGPT 登录凭据当作 API Key
404 或路径不存在base_url 是否多写、少写或误加 /responsesBase URL 或上游路由按服务商文档恢复基础 URL，并确认目标端点提供 Responses API
模型不存在model 的名称和部署方式Provider 或上游模型替换为该端点实际支持的模型名；模型 ID 以服务商文档为准
配置不生效CODEX_HOME、文件名、当前目录和 profile本地配置层级将 provider 相关字段移到用户级配置或正确的 profile 文件，并用 codex --profile 启动
Responses API 不兼容wire_api 和服务端协议网关或上游接口确认服务端提供 Responses API；仅支持 Chat Completions 的端点不能直接按本文模板使用
流式输出中断或超时网关超时、流式响应和上游连接网关或上游服务先用最小请求复现，再查看网关日志和服务端文档，不要仅通过修改 Base URL 猜测原因

常见问题

Codex 的 API 端点应该填到哪一行？

只替换内置 OpenAI provider 的地址，填写 openai_base_url。如果要新增代理、网关、Azure 或本地 provider，则使用顶层 model_provider，并在 [model_providers.<id>] 中填写 base_url、env_key 和必要的 wire_api。

Base URL 要不要填写完整的 /responses？

通常不要。填写服务商要求的基础 URL，由 Codex 根据 provider 协议生成请求路径。若服务商文档明确规定特殊路径，应以该文档为准，不要直接照抄其他服务的地址。

chatgpt_base_url 和 openai_base_url 有什么区别？

openai_base_url用于修改内置 OpenAI API provider 的基础地址；chatgpt_base_url用于 ChatGPT 登录相关的后端地址。它们不是同一个入口，一般配置 API Key 或代理网关时不应把两者混用。

为什么把配置写进项目目录却没有生效？

项目级 .codex/config.toml主要用于项目范围的配置。官方文档明确说明，涉及端点、认证、provider 和 profile 的部分键会被忽略并提示警告。请把这些字段移到用户级 CODEX_HOME/config.toml或用户级 profile 文件。

旧版 profile 写法还能用吗？

较早版本可能在主配置中使用 [profiles.<name>]和顶层 profile。当前官方文档说明，Codex 0.134.0 及更高版本的 --profile使用独立的 ~/.codex/<name>.config.toml文件。遇到版本差异时，以官方配置文档和本机 codex --help为准。

DeepSeek、Kimi 等服务能不能照这个方法配置？

只有在服务商明确提供与 Codex 所需 Responses API 兼容的端点时，才可以按自定义 provider 的方式尝试配置。模型名、认证变量、Base URL 和兼容能力必须以服务商文档为准；仅提供其他 API 协议的服务不能直接套用 wire_api = "responses"。

本文为独立技术整理，不代表 Codex 官方；第三方服务的价格、状态和兼容性以其公开文档或状态页为准。

常见问题

Codex 的 API 端点应该填到哪一行？

只替换内置 OpenAI provider 的地址，填写 openai_base_url；新增代理、网关、Azure 或本地 provider 时，使用 model_provider 和 [model_providers.<id>] 中的 base_url、env_key 及必要的 wire_api。

Base URL 要不要填写完整的 /responses？

通常不要。填写服务商要求的基础 URL，由 Codex 根据 provider 协议生成请求路径；特殊路径以服务商文档为准。

chatgpt_base_url 和 openai_base_url 有什么区别？

openai_base_url 用于内置 OpenAI API provider，chatgpt_base_url 用于 ChatGPT 登录相关后端地址。配置 API Key 或代理网关时不要混用。

为什么配置写进项目目录却没有生效？

项目级 .codex/config.toml 会忽略部分端点、认证、provider 和 profile 字段。请把这些设置移到用户级 CODEX_HOME/config.toml 或独立 profile 文件。

旧版 profile 写法还能用吗？

较早版本可能使用 [profiles.<name>]；当前官方文档说明，Codex 0.134.0 及更高版本使用 ~/.codex/<name>.config.toml，并通过 codex --profile <name> 启动。

DeepSeek、Kimi 等服务能不能照这个方法配置？

只有服务商明确提供与 Codex 所需 Responses API 兼容的端点时，才可以按自定义 provider 尝试配置；模型名、密钥变量和兼容能力以服务商文档为准。

参考资料

  1. Advanced Configuration | ChatGPT Learn（learn.chatgpt.com）
  2. Codex CLI README | openai/codex
  3. OpenAI Codex · Cloudflare AI Gateway docs
  4. config_toml.rs | openai/codex