OpenAI Codex

一份配置，三处通用：在 Codex 桌面客户端、IDE 插件（VSCode/Cursor）和命令行 CLI 中，通过 API易 接入 gpt-5.6-sol / gpt-5.5 / gpt-5.4 等模型。推荐写 config.toml + auth.json，不折腾环境变量。

​

概述

Codex 与 ChatGPT 客户端已合并：2026 年 7 月初，OpenAI 将 Codex 桌面客户端并入 ChatGPT 客户端，两者现在是同一个产品。因此本教程同时适用于 Codex APP 和 ChatGPT 客户端——如果你用的是 ChatGPT 客户端里的 Codex，配置方法完全一样。

OpenAI Codex 是 OpenAI 官方的 AI 编程助手，有三种用法：桌面客户端、IDE 插件（VSCode / Cursor 等）、以及命令行 CLI。三者在底层共用同一份配置（~/.codex/ 目录下的 config.toml 与 auth.json）。

通过 API易接入，本质只有一句话：

把 OpenAI 的入口换成 API易

API易是 OpenAI 兼容接口（透明代理）——配好一次，桌面客户端、插件、终端三处都能用。

🔁 一份配置三处用

桌面 / 插件 / CLI 共用 ~/.codex/，配一次全通

⚡ 最新模型

支持 gpt-5.6-sol / gpt-5.5 / grok-4.5，还可用国产模型

💰 按量计费

与 OpenAI 官方计费方式一致，价格更优

🪟 全平台

Windows / Mac / Linux 通用

先理解再上手：Codex 接第三方 API（如 API易）的关键，是在 ~/.codex/config.toml 里把”模型供应商”指向 API易，并在 ~/.codex/auth.json 里放你的 Key。桌面客户端和 IDE 插件都靠这份文件生效——所以本文以”写配置文件”为主，不推荐折腾环境变量。

​

一、准备工作：拿到 API易 Key

1. 注册 / 登录 API易

   访问 api.apiyi.com 注册或登录你的账号。

2. 创建 API Key

   进入「令牌管理」页面（api.apiyi.com/token），点击「创建新令牌」。

3. 复制密钥

   复制生成的 API Key（格式：sk-***），妥善保存，后面要填进配置文件。

​

选择你的入口

三种入口都可以，配置完全一样，按习惯挑一个即可：

🖥️ 桌面客户端

独立 App，开箱即用，最推荐新手

🧩 IDE 插件

VSCode / Cursor 扩展，边写代码边用

⌨️ 命令行 CLI

终端工作流，适合脚本与自动化

​

二、核心配置（推荐：写配置文件，不折腾环境变量）

下面三种配置方式，任选其一。推荐顺序：手动写文件（最稳）→ 可视化 → 环境变量。

​

方式一 · 手动写 auth.json + config.toml（推荐、最稳）

进入 Codex 的配置目录（没有就新建），在里面放/改两个文件：

🪟 Windows

配置目录：%USERPROFILE%\.codex\（即 C:\Users\你的用户名\.codex\）。

用文件资源管理器进入该目录。

Mac / Linux

配置目录：~/.codex/。

可在终端执行 mkdir -p ~/.codex 进入。

如果 config.toml 已经存在，不要整体覆盖！ 它里面可能已有你之前设置的模型偏好、审批策略、MCP 服务器等。正确做法是先备份、再合并（见下方「如何安全地改已有 config.toml」），只把 API易 需要的几行加进去。auth.json 同理，已有就改 OPENAI_API_KEY 的值即可。

1）auth.json——把 Key 放进去：

{
  "OPENAI_API_KEY": "sk-你的APIYI密钥"
}

2）config.toml——把模型供应商指向 API易：

如果是全新文件，直接写入下面内容；如果已有文件，把”全局键”加到文件最顶部、把 [model_providers.apiyi] 整段加到文件最末尾（原因见下方提示）。

# === 全局（放在文件最顶部）===
model = "gpt-5.4"                 # 默认模型，可按需改成 gpt-5.5 等
model_provider = "apiyi"          # 使用下面定义的 apiyi 供应商
preferred_auth_method = "apikey"  # 用 API Key 认证（不要用 chatgpt 登录）

# === API易 供应商定义（放在文件最末尾）===
[model_providers.apiyi]
name = "apiyi"
base_url = "https://api.apiyi.com/v1"
experimental_bearer_token = "sk-你的APIYI密钥"
wire_api = "responses"

先把 sk-你的APIYI密钥 换成你的真实 Key 再保存（就是上一步在 api.apiyi.com/token 复制的那串 sk- 开头的字符）。两个文件里的 Key 要一致。

如何安全地改已有 config.toml（备份 + 合并的最佳实践）

第 1 步：先备份。 改任何配置前，把原文件复制一份，出问题随时能还原：

# Mac / Linux
cp ~/.codex/config.toml ~/.codex/config.toml.bak

# Windows PowerShell
Copy-Item $env:USERPROFILE\.codex\config.toml $env:USERPROFILE\.codex\config.toml.bak

第 2 步：合并，而不是覆盖。 只往已有文件里加 API易 需要的内容：把 model / model_provider / preferred_auth_method 三行放到文件最顶部，把 [model_providers.apiyi] 整段追加到文件最末尾。原有的其它配置原样保留。

TOML 顺序陷阱：在 TOML 里，所有”裸键值对”（如 model = "..."）必须出现在任何 [xxx] 表头之前，否则它会被算进上一个表里。所以全局键放最上面、[model_providers.apiyi] 放最下面，是最不容易出错的写法。

第 3 步：如果只是想临时试一下、又不想动主配置，可以用 profile：新建 ~/.codex/apiyi.config.toml 放上面这套内容，运行时 codex --profile apiyi 即可，互不影响（详见进阶配置）。

字段说明：

• base_url：固定写 https://api.apiyi.com/v1，必须带 /v1，否则 404。
• experimental_bearer_token：把 Key 直接写在供应商块里，请求时作为 Bearer 发送。这是桌面客户端 / IDE 插件 / CLI 三处都确定生效的写法，不依赖环境变量。
• 供应商的认证字段三选一、不能混写：experimental_bearer_token（Key 写在配置里，推荐）/ env_key（从启动进程的环境变量读 Key——注意它不会去读 auth.json，且桌面客户端读不到终端里 export 的变量）/ requires_openai_auth（复用 auth.json 的官方登录态）。按旧版本文档同时写了 env_key + requires_openai_auth 的，请改成本文当前写法。
• wire_api = "responses"：Codex 默认且首选的协议，API易 已支持。个别模型若报 404 / unknown endpoint，改成 "chat" 兜底（见进阶配置）。
• 不要在本文件里写形如 C:\Users\xxx\.codex\... 的绝对路径，换台机器会断。

​

方式二 · cc-switch 可视化配置（图形界面，免手动编辑）

不想手动编辑文件，可以用 CC Switch——一个图形界面工具，点几下就能把 API易 的地址、Key、模型写进 Codex 配置，还能统一管理 Claude Code、Codex、Gemini CLI 等多款工具，一键切换。它也会自动处理上面的备份/合并，新手可优先考虑。

详见 CC Switch 可视化配置。配好后，Codex 的桌面客户端 / 插件 / CLI 都会自动读到这份配置。

​

方式三 · 环境变量（可选，较复杂，不推荐为主路径）

只想临时在终端测试？展开看环境变量方式（不推荐长期用）

Codex CLI 也能读 OPENAI_BASE_URL / OPENAI_API_KEY 两个环境变量：

export OPENAI_BASE_URL="https://api.apiyi.com/v1"
export OPENAI_API_KEY="sk-你的APIYI密钥"

不推荐作为主路径：环境变量方式在新版 Codex 上经常不生效，且桌面客户端 / IDE 插件不读这两个变量——它们只认 config.toml + auth.json。环境变量仅适合 CLI 临时测试，长期使用请用方式一或方式二。

​

三、三处怎么用（优先桌面客户端）

配好上面的 ~/.codex/ 后，下面三种入口任选。改完配置都要重启对应程序（Codex 只在启动时读一次配置）。

​

1. Codex 桌面客户端（最推荐）

1. 安装并打开 Codex 桌面客户端。
2. 首次打开时选择认证方式：选 apikey（不要选 chatgpt 登录）。
3. 在模型 / 供应商选择处，选中配置里的 apiyi 供应商与目标模型（如 gpt-5.4）。
4. 重启客户端生效。
5. 跑一个最小任务验证（见第四节）。

​

2. IDE 插件（VSCode / Cursor）

1. 打开扩展市场（VSCode 按 Ctrl+Shift+X / Cmd+Shift+X），搜索 Codex — OpenAI's coding agent，点 Install。
2. 安装后左侧边栏出现 Codex 图标，点击打开面板。
3. 首次打开按提示三连：①认证方式选 apikey；②Key 来源选「配置文件 / 环境变量」；③是否启用 AGENTS.md（推荐开启）。
4. 重启编辑器生效。
5. 在 Codex 面板跑最小任务验证。

​

3. 命令行 CLI

先全局安装官方 CLI（需要 Node.js 18+）：

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

进入项目直接启动，或一句话执行任务：

cd /your/project
codex                                  # 交互模式
codex "帮我写一个 Python HTTP Server"   # 直接带任务
codex -q "修复当前项目的构建错误"        # 非交互/静默模式

Mac 用户若遇到全局安装权限问题，推荐用 nvm / fnm 管理 Node 版本，避免 sudo。

​

四、最小验证

配好并重启后，在任一入口里输入一个最小任务：

请用中文在当前项目中创建一个 hello 接口，并附上调用示例。

CLI 用户也可以直接：

codex -q "hello"

能正常返回并给出可执行代码，就说明 API易 链路已经打通。

​

五、模型说明（API易 推荐）

在 config.toml 的 model 字段、或运行时切换即可选用以下模型：

模型	特点	适用场景
gpt-5.6-sol	5.6 旗舰（2026年7月9日 发布）	最难的问题：复杂编码、深度工程分析、Agent 工作流
gpt-5.6-terra	5.6 均衡档	大批量业务任务，性能与成本均衡
gpt-5.6-luna	5.6 快速低价档	摘要、草稿、日常自动化，快且省
gpt-5.5	上代主力模型	复杂代码任务、工程分析、Agent 工作流
gpt-5.4	稳定常用	大多数代码开发、调试、重构（默认推荐）
gpt-5.4-mini	便宜的 5.4 变体	中小规模任务、批量处理、省钱
grok-4.5	xAI 旗舰，原生支持 responses 协议	代码 Agent、复杂任务，OpenAI 系之外的首选
grok-build-0.1	Grok 代码专用，全系最低价	高频代码补全、轻量编程任务

怎么选：日常 → gpt-5.4 或 gpt-5.6-terra；重活 / Agent → gpt-5.6-sol（或 gpt-5.5）；省钱 → gpt-5.6-luna / gpt-5.4-mini；OpenAI 之外想换口味 → grok-4.5。

为什么特别推荐 Grok：xAI 官方 API 本身就是 OpenAI 兼容双端点（Chat Completions + Responses API），所以 Grok 是难得原生支持 /v1/responses 协议的非 OpenAI 模型——在 Codex 里保持 wire_api = "responses" 不用改，把 model 换成 grok-4.5 即可，Codex 的 Agent 能力（工具调用、推理条目等）都按原生协议走。responses 端点在 API易 上以 grok-4.5 实测通过，其余 Grok 型号同架构预期一致，个别遇 404 可按第六节兜底。详见 Grok API 调用指南。

对比 Claude / Gemini：这两家在 API易 上走的是 OpenAI 兼容 chat 模式，不支持 responses 端点——在 Codex 里必须把 wire_api 改成 "chat" 兜底，而 Codex 的 Agent 场景按 responses 协议设计，chat 模式下工具调用等行为可能有不兼容、体验打折。想用 Claude / Gemini 做编程，建议用各自原生工具（Claude Code / Gemini CLI）。

也支持国产 / 任意 OpenAI 兼容模型：API易 聚合了大量模型，凡是支持 OpenAI 兼容调用方式的都能在 Codex 里用——例如智谱 glm-5.2。只需把 config.toml 的 model 字段（或运行时 -m）换成对应模型 ID 即可。

​

切换模型的 4 种方式

① 启动时临时指定（CLI）：

codex -m gpt-5.5
codex --model gpt-5.4 "帮我检查这个项目的代码结构"

② 非交互模式指定（CLI）：

codex -q -m gpt-5.4 "修复当前项目里的构建错误"

③ 会话内切换：在交互面板里输入 /model，按提示选择。

④ 配置默认模型（永久生效）：编辑 ~/.codex/config.toml，把 model 改成想要的，保存后重启：

model = "gpt-5.5"

​

六、进阶配置

自定义系统提示词（instructions.md）

编辑 ~/.codex/instructions.md，定义编码风格、输出语言、项目规范，例如：

- 代码注释使用中文
- 遵循项目的 ESLint 配置
- 提供详细的解释说明

项目级 AGENTS.md

在项目里运行 codex /init 会生成 AGENTS.md，记录项目结构与规范。如需 Codex 默认用中文交流，加一行：

本项目请始终用中文跟用户交流。

协议兜底：wire_api 改 chat

wire_api = "responses" 是 Codex 默认且首选的协议，多数模型直接可用。若某个模型返回 404 / unknown endpoint，把 config.toml 里对应供应商的 wire_api 改成 "chat"（走 /chat/completions）再试。

多套配置切换（profiles）

在 ~/.codex/ 下新建 <名字>.config.toml（例如 openai.config.toml 放官方配置），运行时用 codex --profile <名字> 切换。便于在 API易 与其它供应商之间快速切换。

常用参数

codex -h          # 查看完整帮助
codex -m <模型>   # 指定模型
codex -q          # 非交互/静默模式
codex --full-auto # 自动执行（谨慎使用）

​

七、排障

1. 报 Missing environment variable: OPENAI_API_KEY（桌面客户端 / 插件最常见）

明明写好了 auth.json + config.toml、也重启了应用，还是弹 Missing environment variable: OPENAI_API_KEY——原因是供应商块里写了 env_key = "OPENAI_API_KEY"（旧版本文档的写法）。

env_key 的语义是从启动 Codex 的进程环境变量里取 Key，它不会去读 auth.json（auth.json 只服务于 OpenAI 官方登录态）。而桌面客户端 / IDE 从 Dock / 启动器打开时，不继承你在终端里 export 的变量（.zshrc 里的 export 对 GUI 应用无效），所以无论重启多少次都找不到这个变量。

修法（推荐）：编辑 ~/.codex/config.toml，删掉供应商块里的 env_key（如有 requires_openai_auth 也一并删掉），换成把 Key 直接写进去：

[model_providers.apiyi]
name = "apiyi"
base_url = "https://api.apiyi.com/v1"
experimental_bearer_token = "sk-你的APIYI密钥"
wire_api = "responses"

改完重启应用即可。

备选（坚持用 env_key 时）：把变量设为系统级——macOS 执行 launchctl setenv OPENAI_API_KEY "sk-你的Key" 后重启应用（开机后需重设）；Windows 执行 setx OPENAI_API_KEY "sk-你的Key" 后重启应用。仅用 CLI 的话，在 shell 配置里 export 即可。

2. 确认 auth.json / config.toml 的路径和内容无误

• auth.json 必须是合法 JSON，且 OPENAI_API_KEY 是你真实的 sk- 开头 Key。
• config.toml 必须能被 TOML 正确解析（注意引号、缩进）。
• 路径在 Windows %USERPROFILE%\.codex\、Mac/Linux ~/.codex/。

3. 确认 Key 有效、有可用额度

去 API易 控制台确认 Key 没过期、账户有余额 / 额度。

4. 确认 base_url 带 /v1

最常见的连接错误 / 超时 / 404 都是因为漏了 /v1。正确：https://api.apiyi.com/v1。其次排查本地代理与 DNS。

5. 改完配置必须重启

Codex（CLI / 插件 / 桌面客户端）都只在启动时读一次配置。改完 auth.json / config.toml 一定要重启对应程序。

6. 仍不稳定：把 wire_api 改成 chat

个别模型在 responses 协议下不兼容时，把对应供应商的 wire_api 改成 "chat" 再试。

​

八、常见问题

为什么能用 API易 接入 Codex？

因为 API易完全兼容 OpenAI API 协议——Codex 看到的 https://api.apiyi.com/v1 和 https://api.openai.com/v1 在请求/响应格式上一致，仅替换 Base URL 即可。

为什么发一个 hello，输入的 tokens 却上万？

这通常是正常现象：Codex 启动时会读取你当前项目的部分文件做初始化（目录结构、AGENTS.md、相关源码等），把它们作为上下文一起发给模型。所以即使你只说一句 hello，输入 tokens 也可能上万。

怎么减少？

• 在空目录或一个很小的项目里测试最小任务，上下文自然就小。
• 给明确的小任务并指定具体文件（如「只看 app.py，加一个 hello 接口」），缩小 Codex 主动扫描的范围。
• 验证性的小任务用更便宜的模型（如 gpt-5.4-mini）来跑。

提示 command not found: codex

确认已正确安装：

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

若仍报错，检查 npm bin -g 路径是否在 PATH 中。

API Key 无效（401 / Invalid Key）

1. 确认用的是 API易 Key（以 sk- 开头），不是 OpenAI 官方 Key。
2. 确认 auth.json 里的 Key 没填错、没多空格。
3. 改完配置重启对应程序。

连接错误 / 超时 / 404

最常见原因：Base URL 没带 /v1。正确写法：https://api.apiyi.com/v1。其次排查本地代理与 DNS。

能用哪些模型？

• OpenAI 系列：✅ 完整支持（推荐 gpt-5.6-sol / gpt-5.6-terra / gpt-5.6-luna / gpt-5.5 / gpt-5.4）。
• Grok 系列：✅ 原生支持 responses 协议，grok-4.5 无需改 wire_api 直接可用，详见 Grok API 调用指南。
• 国产 / 其它 OpenAI 兼容模型：API易 支持，如 glm-5.2，改 model 字段即可。
• 注意：Claude / Gemini 在 API易 上只有 OpenAI 兼容 chat 模式、不支持 responses 端点，在 Codex 里须把 wire_api 改成 "chat"，工具调用等 Agent 行为可能有不兼容。想用 Claude / Gemini 做编程，建议用对应原生工具（如 Claude Code / Gemini CLI）。

桌面客户端 / 插件没生效，怎么办？

桌面客户端和 IDE 插件只读 ~/.codex/config.toml + auth.json，不读环境变量。请确认这两个文件配置正确，认证方式选了 apikey，并重启程序。

适合生产吗？

• CLI / 客户端：适合开发期效率工具。
• 生产：建议直接调用 API（更可控、可监控、可灰度）。

如何卸载或停用 API易 配置？

卸载 CLI：

npm uninstall -g @openai/codex

停用 API易 配置：删除或还原 ~/.codex/config.toml 与 auth.json 即可（卸载桌面客户端 / 插件则在各自界面操作）。

​

九、总结

这类接入本质就一句话：

把 OpenAI 的入口换成 API易

核心就是在 ~/.codex/ 配好一次：auth.json 放 Key，config.toml 把 base_url 指向 https://api.apiyi.com/v1。配好后，桌面客户端、IDE 插件、命令行三处都能用。剩下都是锦上添花——选模型、写提示词、自定义 instructions.md / AGENTS.md。

​

相关资源

API易控制台

管理 API 密钥与查看用量

CC Switch 可视化配置

图形界面一键配置 Codex / Claude Code

Claude Code 集成

用 Claude 系列做命令行编程

模型对比

所有可用模型与定价