API快连 apikl.ai
首页 控制台

Codex 安装与国内使用教程（2026）：Base URL 与 API Key 设置（CLI / 桌面版 / VS Code）

更新于

这篇把 Codex 接入 API 快连一次讲全：安装、Codex Base URL 和 API Key 怎么填、config.toml 每一行是什么意思、Key 怎么长期生效、桌面版和 VS Code 插件怎么配、怎么验证，以及常见报错怎么排查。不需要 ChatGPT Plus 订阅，也不需要 OpenAI 官方账号。

📌
一句话答案：Codex 走 OpenAI 兼容协议，Base URL 填 https://apikl.ai/v1（要带 /v1），API Key 填控制台创建的 sk-...；推荐写进 ~/.codex/config.toml 的自定义服务商，比只设环境变量更稳。
项目填写内容说明
Base URLhttps://apikl.ai/v1带 /v1，后面不要再加 /responses 或 /chat/completions
API Keysk-...在 控制台 创建，分组选 GPT 类分组
配置文件~/.codex/config.tomlCLI、桌面版、VS Code 插件共用这一份
接口协议wire_api = "responses"新版 Codex 默认值
推荐模型gpt-5.6-sol先用它测通，再按需要换

准备工作

  • Node.js 18 或更高版本（用 npm 安装 Codex 时需要），没装的看 Node.js 环境安装教程。
  • 一个 API 快连密钥：登录 控制台 新建，分组选 GPT 类分组（例如 GPT-Pro）。Claude 分组的密钥调不了 GPT 模型。

第一步：安装 Codex CLI

BASH
npm install -g @openai/codexcodex --version

能输出版本号就装好了。国内下载慢时先切换 npm 镜像：npm config set registry https://registry.npmmirror.com。只用桌面版或 VS Code 插件的话可以跳过这一步，但下面的 config.toml 仍然要配。

第二步：Codex Base URL 到底填什么

  • 正确：https://apikl.ai/v1，带 /v1，末尾不加斜杠和其他路径。
  • 错误 1：https://apikl.ai，少了 /v1。这是 Claude Code 的写法，用在 Codex 上会 404。
  • 错误 2：https://apikl.ai/v1/responses 或 /v1/chat/completions。Codex 会自己拼接路径，多写会 404。
  • 错误 3：只设置了 OPENAI_BASE_URL 环境变量。较新版本的 Codex 会忽略它，请求仍然发往官方地址，结果报 401。请用下面的 config.toml。
💡
一句话记忆：Codex 走 OpenAI 兼容协议，所以带 /v1；Claude Code 走 Anthropic 协议，所以不带 /v1。

第三步：写 config.toml（推荐做法）

配置文件位置：macOS / Linux 是 ~/.codex/config.toml，Windows 是 C:\Users\你的用户名\.codex\config.toml。没有就新建，写入：

~/.codex/config.toml
model = "gpt-5.6-sol"model_provider = "apikl" [model_providers.apikl]name = "API 快连"base_url = "https://apikl.ai/v1"env_key = "OPENAI_API_KEY"wire_api = "responses"
这一行作用
model默认使用的模型
model_provider = "apikl"让 Codex 使用下面定义的 API 快连服务商，而不是官方 OpenAI
base_url接口地址，必须带 /v1
env_key从哪个环境变量读取密钥。这样密钥不用写进配置文件，更安全
wire_api = "responses"使用 Responses 接口，新版 Codex 的默认方式
⚠️
旧教程里的 wire_api = "chat" 在新版 Codex 中已被弃用，可能直接报错，请改成 responses。如果你的配置文件里已有其他内容，只修改或追加上面几行，不要整个覆盖。

第四步：设置 Codex API Key

先在当前终端临时设置（马上能用）

macOS / Linux
export OPENAI_API_KEY="sk-你的密钥"codex
Windows · PowerShell
$env:OPENAI_API_KEY="sk-你的密钥"codex

让 Codex API Key 长期生效

上面的写法只对当前窗口有效，关掉就没了。想一次设置、以后每次打开都能用：

macOS / Linux（写入 ~/.zshrc，Linux bash 用户改成 ~/.bashrc）
echo 'export OPENAI_API_KEY="sk-你的密钥"' >> ~/.zshrcsource ~/.zshrc
Windows · PowerShell（新开终端生效）
setx OPENAI_API_KEY "sk-你的密钥"
🔒
密钥等同于密码：不要发到群里、截图里或提交到公开代码仓库。用 env_key 引用环境变量，就是为了不把密钥写进配置文件。

第五步：验证是否接通

BASH
codex exec "用一句话介绍你自己"

能返回一句回复就说明接通了。也可以直接运行 codex 进入交互界面发消息。接通之后的日常用法（常用命令、权限模式、AGENTS.md、codex exec），看 Codex CLI 使用教程。

想判断是密钥问题还是 Codex 配置问题，可以绕开 Codex 直接请求一次接口（macOS / Linux）：

BASH · 直接测试接口
curl https://apikl.ai/v1/responses \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"gpt-5.6-sol","input":"你好"}'

返回 JSON 且有回复内容，说明密钥和网络正常，问题出在 Codex 配置；返回 401 说明密钥不对。

Codex 桌面版 / VS Code 插件怎么配

Codex 桌面版和 VS Code 插件读取的是同一份 config.toml，按上面第三步配好后，彻底退出再重新打开即可生效。下载安装、权限模式和桌面版常见问题，看 Codex 桌面版教程。

⚠️
macOS 上从程序坞或启动台打开的桌面应用读不到 ~/.zshrc 里的环境变量，所以终端能用、桌面版却报 401 很常见。解决办法二选一：用下面的 CC Switch 配置；或在终端执行 launchctl setenv OPENAI_API_KEY sk-你的密钥 后重开桌面版（电脑重启后需要重新执行）。

用 CC Switch 配置（推荐给不想改文件的用户）

  1. 先彻底退出 Codex 桌面版，避免它占用或覆盖配置文件。
  2. 打开 CC Switch，切到 Codex 页，添加自定义服务商。
  3. 按下表填写 Base URL、API Key 和模型名，保存后点「测试」。
  4. 测试通过后启用这个服务商，再打开 Codex 桌面版，发一个简单任务确认能回复。
字段填写
服务商类型OpenAI Compatible / 自定义
Base URLhttps://apikl.ai/v1
API Keysk-你的密钥
模型gpt-5.6-sol

怎么选模型、怎么切换

  • gpt-5.6-sol：默认推荐，稳定，适合日常编码。
  • gpt-6.1-sol / gpt-6-sol / gpt-6-astra：更新的型号，适合更复杂的任务。
  • gpt-5.6-terra：单价更低，适合简单、批量的任务。
  • 切换方法：启动时加 -m 模型名，会话中输入 /model，或修改 config.toml 里的 model。

各模型实时价格看 模型广场。用量记录里出现你没手动选的模型名，通常是 Codex 客户端自己发起的后台请求（例如压缩上下文、自动审查），并不是线路乱跳。

国内怎么用

  • 不需要 ChatGPT Plus / Pro 订阅，也不需要 OpenAI 账号，按实际用量计费。
  • 国内多数网络可以直接访问 apikl.ai，一般不需要额外开代理。网络不稳定或长任务超时时，可以换成不经过 CDN 的直连线路 https://dc.apikl.ai/v1，同样带 /v1。
  • Codex 启动时如果弹出 ChatGPT 登录界面，说明没用上自定义服务商，检查 config.toml 里的 model_provider 是否是 apikl。

在 Codex 中通过 API 快连生成图片

📌
使用第三方 API 时，不要依赖 Codex 内置的 Image Gen：它按 OpenAI 官方账号和工作区权限校验，可能返回 403 Forbidden，而且请求不会进入 API 快连。用 API 快连密钥生图，请改为让 Codex 调用 gpt-image-2 的 /v1/images/generations 接口。各分组模型名、4K 和图生图写法见 GPT Image 2.5 生图 API 接入教程。

在 Codex 使用的同一个终端里设好 OPENAI_API_KEY，然后把这段提示词复制给 Codex：

提示词
不要调用 Codex 内置 Image Gen。请在终端调用 OpenAI 兼容的图片生成接口：Base URL: https://apikl.ai/v1Endpoint: /v1/images/generationsModel: gpt-image-2从 OPENAI_API_KEY 环境变量读取密钥，不要打印或展示密钥。根据我的要求生成图片，将结果保存到当前项目，并返回文件路径。

也可以先用命令直接验证图片接口：

BASH
curl -sS "https://apikl.ai/v1/images/generations" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"gpt-image-2","prompt":"电商产品图，白色棚拍背景，柔和灯光，无文字无水印，主体居中","size":"1024x1024"}'
💡
gpt-image-2 在这个接口不支持透明背景，请改用白色或其他纯色背景。即使内置 Image Gen 仍返回 403，也不代表图片接口不可用，以上面命令的结果为准。

常见报错与解决办法

401 invalid_api_key / Unauthorized

  • 请求可能仍然发往 OpenAI 官方：确认 config.toml 里有 model_provider = "apikl"。
  • 运行 Codex 的那个终端里没有 OPENAI_API_KEY：新开终端，或按上文设置长期生效。
  • 桌面版报 401、终端正常：是桌面应用读不到环境变量，看上面「桌面版」一节。
  • 更多情况看 401 invalid_api_key 怎么解决。

404 / model not found

  • Base URL 少了 /v1，或多写了 /responses 等路径。
  • 模型名写错，或密钥所在分组不是 GPT 分组。详细排查看 model not exist 怎么解决。

stream disconnected / 反复「重新连接」

网络抖动或上游短时波动导致流式连接中断，Codex 会自动重连。偶尔出现属正常；持续出现可以换一个模型、检查本地代理，或联系客服。

413 Payload Too Large

单次请求太大，通常是会话里堆了很多截图或大文件。新开一个会话再继续即可。

上下文经常被自动压缩

Codex 在上下文快满时会自动压缩历史，这是正常机制。任务切换时开新会话，可以减少压缩次数，也更省钱。

403 insufficient balance / 余额不足

余额用完或较低时，同时运行多个任务会提前触发余额不足提示，充值或减少并发即可。

常见问题

Codex 国内能用吗？

能。按本文把 Codex 的服务商指向 API 快连即可，不需要海外账号和信用卡。

为什么设置了 OPENAI_BASE_URL 不生效？

较新版本的 Codex 不再读取这个环境变量，用 config.toml 的自定义服务商（第三步）最稳。

Codex 和 Claude Code 能用同一个密钥吗？

一般不能。密钥绑定在分组上：GPT 分组的密钥调 GPT 模型，Claude 分组的密钥调 Claude 模型。两个都用就各建一个。Claude Code 的配置看 Claude Code 配置教程。

CLI、桌面版、VS Code 插件要分别配置吗？

不用。三者共用 ~/.codex/config.toml，配一次即可；只有桌面版在 macOS 上需要额外处理环境变量（见上文）。

✅
还没有密钥？去控制台创建 →  ·  看模型价格 →  ·  想图形化配置？看 CC Switch 配置教程