Codex 接入教程

把 supergpt 的 API 接入 Codex，桌面客户端、命令行和官方 IDE 扩展都可以使用。本文按本站实际地址编写；其他 Sub2API 站点需要换成自己的 API 地址、密钥和模型 ID。

核对日期：2026-10-04。

准备连接信息

1. 打开 API 密钥，创建或选择一把用于 Codex 的密钥。
2. 打开该密钥的「连接信息」，选择 OpenAI Responses。
3. 复制完整密钥、API 基础地址，以及这把密钥所属分组可用的完整模型 ID。可用模型和价格在模型广场核对。

Base URL 填到 /v1 为止。 不要填控制台地址，也不要填完整的 /v1/responses；Codex 会自己追加 /responses。

Codex 需要 Responses 协议以及相应的流式输出和工具调用能力。能调用 Chat Completions，或能在其他聊天软件中对话，不代表已经满足 Codex 的要求。模型是否可用，以该密钥的分组和实际调用为准。官方网关兼容要求

通用配置

这套配置采用 Sub2API 的兼容方式：config.toml 保存服务商信息，auth.json 保存 API 密钥。适合希望桌面端、CLI 和扩展共用配置的用户，不需要每次启动前输入环境变量。Sub2API 配置生成源码

1. 找到用户配置目录

这里的 ~ 是当前用户主目录。若你自行设置过 CODEX_HOME，应检查实际运行客户端使用的目录。使用用户目录中的配置，不要把密钥文件放进项目。

2. 先备份已有配置

完全退出相关客户端。若目录里已有 config.toml 和 auth.json，分别复制一份留作备份，例如 config.before-supergpt.toml 和 auth.before-supergpt.json。

本方式将 Codex 的本地认证切换为本站 API Key，使用同一目录的 CLI 和扩展也会受影响。已有 ChatGPT 登录、其他服务商或钥匙串配置的用户，请保留原文件和设置；只想保留原登录凭据的 CLI 用户，可选后面的环境变量方式。

3. 编辑 config.toml

没有该文件就新建一个纯文本文件。已有配置时合并以下字段，保留其他设置，并删除同名字段的旧值；不要把整段重复追加到文件末尾。

将 YOUR_MODEL_ID 替换为在连接信息中复制的模型 ID。

model = "YOUR_MODEL_ID"
model_provider = "awsb企业中转"
cli_auth_credentials_store = "file"
web_search = "disabled"

[model_providers.supergpt]
name = "awsb企业中转"
base_url = "https://api.supergpt.win/v1"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = false

前四行是顶层配置，必须放在第一个 [配置段] 之前。model_provider 的值与 [model_providers.supergpt] 中的名称对应。

这份兼容配置中的 requires_openai_auth = true 表示读取 Codex 的登录凭据；下面的 auth.json 提供的是本站密钥。它不代表要把请求发到 OpenAI，模型请求的目的地由 base_url 决定。这里不再同时设置 env_key 或 experimental_bearer_token。

首次连接先使用 HTTP/SSE，并关闭联网搜索，减少额外功能对排查的影响。连接成功后，如需搜索或 WebSocket，应先确认当前分组、模型和客户端版本支持。配置字段参考

4. 编辑 auth.json

在同一个目录新建或修改 auth.json，将 YOUR_SUPERGPT_API_KEY 替换成本站的完整密钥：

{
  "OPENAI_API_KEY": "YOUR_SUPERGPT_API_KEY"
}

字段名必须是 OPENAI_API_KEY，不要改成 SUPERGPT_API_KEY；字段值才是 supergpt 的密钥。JSON 使用英文双引号，不要加注释或最后一个逗号。此兼容方式应使用上面的 API Key 对象，不要与旧的 OAuth tokens 字段混合。

cli_auth_credentials_store = "file" 让这套配置明确读取文件凭据。文件和备份都含有密钥，不要提交到 Git、上传到网盘公开目录，或发到客服频道。官方凭据存储说明

macOS／Linux 可限制文件权限：

chmod 700 ~/.codex
chmod 600 ~/.codex/config.toml ~/.codex/auth.json

桌面客户端

官方桌面产品的名称和入口可能随版本变化。当前文档使用 ChatGPT 桌面版中的 Codex；已有独立 Codex 桌面端的用户，也应检查该版本实际读取的配置目录。本文配置针对 Codex 的本地任务。桌面版说明

macOS

1. 从官方桌面版入口下载安装。配置文件方式不要求另外安装 CLI。
2. 按 ⌘Q 完全退出客户端，仅关闭窗口不够。
3. 在 Finder 中按 ⌘⇧G，输入 ~/.codex/。如果目录不存在，可在终端运行：

mkdir -p ~/.codex
open ~/.codex

4. 按「通用配置」保存 config.toml 和 auth.json。用文本编辑器时选择纯文本，确认不是 config.toml.txt 或富文本文件。
5. 重新打开客户端，进入 Codex，选择本机文件夹，新建一个本地任务。
6. 核对模型，按后面的「验证是否接入成功」发送测试消息。切换服务商后先使用新任务，避免旧会话继续沿用原模型设置。

Windows

1. 从官方桌面版入口安装 Windows 版本，然后完全退出应用。
2. 按 Win+R，输入 %USERPROFILE%，进入用户目录；创建或打开 .codex 文件夹。
3. 在文件资源管理器中开启「文件扩展名」显示，使用记事本或代码编辑器保存两个配置文件。
4. 保存类型选「所有文件」，编码使用 UTF-8，确认名称恰好为 config.toml 和 auth.json。
5. 重新打开客户端，进入 Codex，选择本机项目并新建任务，再检查本站调用记录。

Windows 桌面程序与 WSL 中的 CLI 通常使用不同的用户目录。只修改 /home/用户名/.codex/，不会自动修改 Windows 的 %USERPROFILE%\.codex\。

Linux

当前官方 Linux 桌面版为预览版，按官方 Linux 安装指南选择发行版和处理器对应的软件包。安装后退出应用，在 Linux 用户的 ~/.codex/ 完成通用配置，再打开 Codex 本地任务。

登录页与已有账号

保存配置后仍停留在登录页，先检查客户端版本、配置目录和文件格式。当前官方桌面版提供 Sign in another way 的 API Key 入口；入口名称可能随版本变化。官方登录说明

仅在登录框填密钥不会自动设置第三方 Base URL。 应先配置 supergpt 服务商，再按该版本的提示使用 API Key；不要为了重试反复覆盖配置或删除整个 .codex 目录。使用钥匙串存储或受组织策略管理的设备，应核对实际生效的凭据来源。

IDE 扩展

这里指 OpenAI 发布的 Codex 扩展，扩展 ID 为 openai.chatgpt。Cursor 自带的聊天面板、Windsurf 自带的助手与此扩展是不同入口。官方扩展指南

1. 在 VS Code、Cursor 或 Windsurf 的扩展市场安装 OpenAI 发布的 Codex。
2. 打开项目，点击 Codex 图标；找不到时，在命令面板执行 Codex: Open Codex Sidebar。
3. 点击 Codex 侧栏齿轮，进入 Codex Settings → Open config.toml，确认编辑的是运行 Codex 的用户配置。
4. 按「通用配置」合并服务商设置，并在同一用户配置目录放置 auth.json。同一台电脑、同一用户已配好桌面版时，一般无需重复写入。
5. 完全退出并重新打开编辑器，新建一个本地 Codex 对话，选择已配置的模型。
6. 若仍要求登录，先检查目录和凭据配置。官方扩展的 API Key 登录入口为 Use API Key；仍需保留前面的自定义服务商设置。

不要把 TOML 粘进 VS Code 的 settings.json，也不需要为了接入 API 修改 chatgpt.cliExecutable。扩展自带运行组件，不要求另装全局 CLI。扩展设置说明

WSL、SSH 与远程开发

配置跟随 Codex 进程实际运行的位置。若扩展在 WSL、SSH 主机或容器中运行，配置和密钥也应放在那个环境的用户目录；本机文件不一定会自动传过去。

Windows 扩展设置 chatgpt.runCodexInWindowsSubsystemForLinux 会影响运行位置。不要同时改两份配置来碰运气，先用扩展的设置入口确认当前环境，再配置对应目录。

Codex CLI

1. 安装并确认版本

已安装 Node.js 和 npm 的用户可执行：

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

macOS 使用 Homebrew 时，也可选 brew install --cask codex。选择一种安装方式即可；其他系统安装和升级步骤见官方 CLI 安装指南。

全局 CLI、桌面版和 IDE 扩展可能内置不同版本的 Codex。升级全局 npm 包，不等于更新桌面版或扩展。

2. 连接并启动

按「通用配置」保存两个文件。然后打开要使用的项目目录，运行：

codex

进入后使用 /status 检查当前服务商和模型，再发送测试消息。若使用上述文件认证方式，无需再执行默认的 codex login 浏览器登录流程。

仅 CLI 使用环境变量

如果只使用命令行，希望保留已有登录凭据，可用此方式替代前面的文件认证配置。两种方式选一种，不要拼在一起。

备份用户 config.toml，将其中对应字段调整为下面的内容，保留其他设置和原来的 auth.json。将 YOUR_MODEL_ID 换成实际模型 ID；env_key 填的是变量名，密钥在下一步设置。

model = "YOUR_MODEL_ID"
model_provider = "awsb企业中转"
web_search = "disabled"

[model_providers.supergpt]
name = "awsb企业中转"
base_url = "https://api.supergpt.win/v1"
wire_api = "responses"
env_key = "SUPERGPT_API_KEY"
requires_openai_auth = false
supports_websockets = false

macOS／Linux，在同一个 Bash 或 Zsh 终端设置密钥并启动：

export SUPERGPT_API_KEY='YOUR_SUPERGPT_API_KEY'
codex

Windows PowerShell：

$env:SUPERGPT_API_KEY = 'YOUR_SUPERGPT_API_KEY'
codex

占位符需要替换；带有真实密钥的命令可能留在 shell 历史中，不要分享终端记录。临时变量只对当前终端和由它启动的程序有效，不能据此认定从 Dock 或开始菜单打开的桌面客户端也能读取密钥。官方网关接入说明

环境变量方式保留认证文件，但修改默认服务商仍会影响读取同一 config.toml 的其他客户端。切回原服务商时，恢复备份的配置即可。

验证是否接入成功

1. 完全重启实际要使用的客户端，在一个新建的本地任务中检查模型。CLI 可用 /status。
2. 发送一条简短消息，例如：

只回复 supergpt-ok，不调用工具，不修改文件。

3. 打开本站使用记录，按密钥和时间核对本次请求、模型与扣费记录。首次测试也可能产生正常调用费用。
4. 再发一条追问，检查多轮上下文。需要编程功能时，可让它读取一个专门准备的测试文件并概括内容，确认实际工具调用也能完成。

能回复文字只是第一步；本站出现对应记录，才能确认请求经过本站。 不要通过询问模型「你是谁」来验证路由。基础对话成功也不等于图片、搜索、MCP、长上下文或全部工具都可用，这些能力需要分别核对。

本地服务商配置不会自动把 ChatGPT 网页、云端任务或所有插件流量转到本站，也不会替你购买或解锁 ChatGPT 订阅功能。API 模型费用以本站分组规则和账单为准。本地与云端认证区别

常见问题

新版本 CLI 可用 codex doctor 检查本地配置，并在会话里用 /debug-config 查看配置来源；旧版本不认识命令时，先核对版本及官方说明。排查资料请脱敏，尤其不要公开 auth.json。官方诊断入口

恢复原来的配置

退出桌面端、编辑器和 CLI，将备份的 config.toml、auth.json 恢复到原位置，再启动客户端。如果原来使用系统钥匙串，也要恢复原来的 cli_auth_credentials_store 设置。

如果只是把 supergpt 字段合并进旧文件，删除本次新增的服务商段，并把默认模型、服务商、凭据存储和搜索设置改回原值；此前没有认证文件的用户可以只移除本次创建的 auth.json。不要删除整个 .codex，里面还可能有会话和其他设置。

资料与验证范围

本文结合本站连接信息、Sub2API 配置生成逻辑和 OpenAI 官方文档编写。兼容文件认证与环境变量认证已在独立测试目录中，使用 Codex CLI 0.143.0 及本机桌面版内置的 Codex 0.159.2 验证：能向测试网关的 /v1/responses 发送所选模型与正确 Bearer 凭据，并接收流式完成响应。

上述验证使用本地模拟接口，没有调用真实生产模型；桌面版内置组件测试不等同于所有桌面 UI、Windows／Linux 系统和 IDE 版本均已端到端实测。接入后请按本文验证步骤检查自己的客户端和分组。

参考：网关接入、配置参考、身份认证、桌面版、IDE 扩展、Sub2API 源码。