Codex CLI

概述

Codex CLI 是 OpenAI 开源的命令行编程代理。它可以读取你的代码库、提出修改建议、执行命令，并根据反馈进行迭代——全部在终端中完成。通过将 Codex CLI 指向 AihubMax，你可以使用 AihubMax 提供的任意 OpenAI 兼容模型。

Codex CLI 支持通过 config.toml 配置文件定义自定义模型提供商，无需修改 Base URL 环境变量即可轻松连接 AihubMax。

前置条件

AihubMax API Key

一个有效的 AihubMax API Key，并确保有权限访问 OpenAI 兼容模型。前往 AihubMax →

Node.js 22+

Codex CLI 需要 Node.js 22 或更高版本。下载 Node.js →

安装与配置

安装 Codex CLI

npm install -g @openai/codex

验证安装：

codex --version

设置 API Key

在配置环境变量前，先前往 AihubMax 控制台创建专用密钥：

打开「API 密钥」页面，点击「创建密钥」。
密钥名称可自定义，便于区分不同 CLI。
分组务必选择「Codex」，这是 Codex CLI 的官方通道，可确保使用 OpenAI 兼容协议以及足够的并发额度。

如果没有选择「Codex」分组，Codex CLI 可能无法调用 AihubMax 的 Codex 兼容模型，或出现速率/功能限制。

下面两种方式二选一即可：使用 CC-Switch 一步到位（自动写入环境变量和 Codex 配置），或通过 手动配置 依次设置环境变量并在下一步编辑 config.toml。Codex CLI 通过 OPENAI_API_KEY 环境变量读取认证信息，将其设置为你的 AihubMax API Key：

CC-Switch（推荐）
macOS / Linux
Windows (PowerShell)

CC-Switch 可以自动写入 Codex CLI 所需的环境变量：

根据你的系统下载并安装最新的 CC-Switch 安装包。
通过以下任一方式将密钥导入 CC-Switch：
- 一键导入（推荐）：在 AihubMax 控制台的密钥列表中，点击对应密钥右侧的下拉菜单，选择 「CC Switch」，配置会自动导入到 CC-Switch 中。
- 手动添加：在 CC-Switch 中手动新增一个「Codex CLI」配置，Base URL 填写 https://api.aihubmax.com/v1，并填入你的 API Key。

导入后，CC-Switch 会在当前 Shell 会话中注入 OPENAI_API_KEY，无需手动编辑配置文件。

在你的 Shell 配置文件（~/.bashrc、~/.zshrc 等）中添加以下内容：

export OPENAI_API_KEY="sk-your-foxapi-api-key"

然后重新加载配置：

source ~/.zshrc  # 或 source ~/.bashrc

为当前用户永久设置环境变量：

[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "sk-your-foxapi-api-key", "User")

重启终端使设置生效。

配置 AihubMax 为模型提供商

如果你在上一步选择了 CC-Switch，工具已经帮你写入 ~/.codex/config.toml，可以直接跳到「开始使用」。仅在手动配置的情况下需要继续本步骤。

创建或编辑 Codex CLI 配置文件：

macOS / Linux
Windows

编辑 ~/.codex/config.toml：

model = "gpt-4.1"
model_reasoning_effort = "medium"
model_provider = "foxapi"

[model_providers.foxapi]
name = "AihubMax"
base_url = "https://api.aihubmax.com/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

编辑 C:\Users\{username}\.codex\config.toml：

model = "gpt-4.1"
model_reasoning_effort = "medium"
model_provider = "foxapi"

[model_providers.foxapi]
name = "AihubMax"
base_url = "https://api.aihubmax.com/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

wire_api 字段必须设置为 "responses"。"chat" 选项已弃用，可能导致意外行为。

配置字段说明：

字段	说明
`model`	默认使用的模型（可通过 `--model` 参数覆盖）
`model_reasoning_effort`	推理努力程度：`"low"`、`"medium"` 或 `"high"`
`model_provider`	自定义提供商名称（必须与 `[model_providers.xxx]` 部分名称一致）
`base_url`	AihubMax 的 API 端点
`env_key`	存储 API Key 的环境变量名称
`wire_api`	使用的 API 协议（必须为 `"responses"`）

开始使用

进入你的项目目录并启动 Codex：

cd /path/to/your/project
codex

或直接运行单次命令：

codex "为注册表单添加输入验证"

验证连接

使用简单的提示测试连接：

codex "请说你好，并确认你正在正常工作"

如果配置正确，Codex 将通过 AihubMax 的 API 返回回复。

模型	适用场景
`gpt-4.1`	复杂的多步骤编程任务（推荐默认选择）
`gpt-4o`	通用编程任务，速度与质量平衡
`o4-mini`	快速、经济的编程辅助

常见问题

错误：401 Unauthorized

确认 OPENAI_API_KEY 是有效的 AihubMax Key。
确认 Key 未过期且账户余额充足。
如果使用 config.toml，确认 env_key 字段与你设置的环境变量名称一致（默认为 OPENAI_API_KEY）。

错误：连接失败

检查 config.toml 中的 base_url 是否设置为 https://api.aihubmax.com/v1（需包含 /v1）。
确认你的网络能够访问 api.aihubmax.com。

模型未找到

确认模型名称正确且在 AihubMax 上可用。
检查你的 AihubMax 账户是否有该模型的访问权限。

配置文件未生效

确认文件位于 ~/.codex/config.toml（macOS/Linux）或 C:\Users\{username}\.codex\config.toml（Windows）。
检查 TOML 语法——确保字符串使用引号包裹，section 标题使用方括号。
确认 model_provider 的值与 [model_providers.xxx] 的 section 名称完全一致。

MCP 服务器

AI 编程工具箱

智能体

概述

前置条件

AihubMax API Key

Node.js 22+

安装与配置

验证连接

推荐模型

常见问题

​概述

​前置条件

AihubMax API Key

Node.js 22+

​安装与配置

​验证连接

​推荐模型

​常见问题

概述

前置条件

安装与配置

验证连接

推荐模型

常见问题