接入 Codex

让 Codex CLI 通过 AIGCDesk 调用 AI 模型

本页介绍最短的配置路径：安装 Codex、将模型服务指向 AIGCDesk、填入 API Key，然后验证能否正常启动。

准备事项

• AIGCDesk API Key请先在 AIGCDesk API 控制台的 Token 页面创建一个新的 API Key。建议为 Codex 单独创建一个，不要和其他应用共用。
• 可用的模型名称model 字段必须填写 AIGCDesk 实际开放的名称。当前推荐使用 gpt-5.4。如果你的账号或站点启用了模型别名，请使用别名，而不是后台的原始名称。
• Codex 配置文件位置这套方案使用两个文件：~/.codex/auth.json 存 API Key，~/.codex/config.toml 存服务商配置。如果不想写入 auth.json，也可以改用环境变量。
• 安装前提通过 npm 安装时，需要 Node.js 16+。macOS 也可以直接用 Homebrew；Windows 用户建议通过 Windows 11 + WSL2 中的 Ubuntu 安装。

推荐配置

本地持久化配置（推荐）

如果你希望把密钥直接放在 ~/.codex 目录下，而不是每次都手动导出环境变量，可以把 API Key 写入 auth.json，再把服务商配置写入 config.toml。其中 base_url 需要填写 https://api.aigcdesk.com/v1，因为 Codex 自定义服务商使用 Responses API 接口规范。

~/.codex/auth.json

{
  "OPENAI_API_KEY": "YOUR_AIGCDESK_API_KEY"
}

~/.codex/config.toml

model = "gpt-5.4"
model_provider = "aigcdesk"

[model_providers.aigcdesk]
name = "AIGCDesk"
base_url = "https://api.aigcdesk.com/v1"
requires_openai_auth = true
wire_api = "responses"

为什么可以直接写 auth.json？

auth.json 支持 OPENAI_API_KEY 字段。当服务商配置中设置了 requires_openai_auth = true，Codex 会自动从 auth.json 读取 API Key，不再需要单独配置 env_key。

这套方案更适合个人电脑。请把 ~/.codex/auth.json 当作密码文件来保管，不要提交到代码仓库，也不要通过聊天或工单共享。对于共享机器或企业环境，环境变量通常更安全。

按操作系统配置

macOSWindowsLinux

macOS

适用于 macOS 12+。优先使用 Homebrew 安装；如果团队统一通过 npm 管理命令行工具，请确认本机已安装 Node.js 16+。

步骤 1：安装 Codex

优先使用 Homebrew；如果当前环境只用 npm 管理全局工具，再选下面那条命令。

brew install --cask codex

npm install -g @openai/codex

步骤 2：创建配置目录

Codex 默认从 ~/.codex/ 读取配置和认证文件，目录不存在时先手动创建。

mkdir -p ~/.codex
touch ~/.codex/auth.json
touch ~/.codex/config.toml

步骤 3：写入 API Key 与配置

将上方”推荐配置”中的 JSON 写入 ~/.codex/auth.json，将 TOML 写入 ~/.codex/config.toml，然后收紧文件权限。

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

步骤 4：验证启动

重新打开终端，先确认版本号，再启动 Codex，看能否进入交互界面。

codex --version
codex

Windows

官方建议通过 Windows 11 + WSL2 安装，下面的步骤以 WSL 中的 Ubuntu 为例。如果你的团队已部署了原生 Windows 版本，config.toml 的内容完全相同，直接沿用即可。

步骤 1：准备 WSL2 环境

如果当前电脑还没有 Ubuntu on WSL，请先在 PowerShell 中执行以下命令安装。

wsl --install -d Ubuntu

步骤 2：在 WSL 中安装 Codex

打开 Ubuntu，确认已有 Node.js 16+，然后用 npm 安装 Codex。

npm install -g @openai/codex

步骤 3：创建配置目录并写入文件

以下命令在 WSL 的 Ubuntu 终端中执行。auth.json 存 API Key，config.toml 存服务商配置。

mkdir -p ~/.codex
touch ~/.codex/auth.json
touch ~/.codex/config.toml
chmod 600 ~/.codex/auth.json
chmod 600 ~/.codex/config.toml

步骤 4：写入配置并验证

先写入 ~/.codex/auth.json，再写入 ~/.codex/config.toml，然后执行：

codex --version
codex

Linux

适用于 Ubuntu 20.04+、Debian 10+ 等主流发行版。如果当前环境不便安装 Node.js，也可以从 Codex 官方 Release 页面下载二进制文件，但 npm 方式通常更快完成首次验证。

步骤 1：安装 Codex

确认系统已有 Node.js 16+，再执行 npm 安装。

npm install -g @openai/codex

步骤 2：创建配置目录

配置文件路径为 ~/.codex/config.toml，目录和文件需要先手动创建。

mkdir -p ~/.codex
touch ~/.codex/auth.json
touch ~/.codex/config.toml

步骤 3：写入 API Key 与配置

将上方”推荐配置”中的 JSON 写入 ~/.codex/auth.json，将 TOML 写入 ~/.codex/config.toml，然后收紧文件权限。

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

步骤 4：验证启动

安装后如果终端仍找不到 codex 命令，请重新登录当前 shell，再执行：

codex --version
codex

配置检查清单

• auth.json 里的 API Key 正确且有效如果 OPENAI_API_KEY 为空、复制有误，或对应 Token 已停用、过期、额度用完，Codex 在发起请求时会报错。
• 服务商配置指向了正确的地址确认 base_url、requires_openai_auth = true 与 wire_api = “responses” 均已按推荐配置填写。
• 模型名称与 AIGCDesk 开放的名称一致如果你的账号或站点启用了模型别名，请使用别名，不要直接复制后台的原始名称。

常见问题

model 可以直接写 gpt-5.4 吗？

只要 AIGCDesk 实际开放了这个名称就可以。

如果你的账号或站点启用了模型别名，或者管理员修改过对外名称，请以控制台显示的名称为准。

为什么 base_url 要写成 https://api.aigcdesk.com/v1？

Codex 的自定义服务商配置使用 Responses API 接口规范，因此地址需要包含 /v1 路径前缀。

不想把密钥写进 auth.json，可以怎么做？

改用环境变量即可：

• 保留 model_provider、base_url 和 wire_api
• 删除 requires_openai_auth = true 这一行
• 改为 env_key = “AIGCDESK_API_KEY”
• 通过环境变量提供 API Key

Codex 能启动，但发请求时报 401 或 403，先查什么？

依次检查以下四项：

• auth.json 里的 OPENAI_API_KEY 是否已填写正确
• config.toml 里的 model_provider、base_url、requires_openai_auth 和 wire_api 是否与本页一致
• 对应 Token 是否仍有效、是否还有剩余额度、是否有权使用当前模型
• model 填写的是否是 AIGCDesk 实际开放的名称