Codex CLI 接入指南

OpenAI Codex CLI 是一款在终端中运行的 AI 编程助手。Token101 通过 OpenAI Responses API（/api/v1/responses）完整支持 Codex CLI，这也是 Codex 默认使用的通信协议。

前置条件

• Node.js 18 或更高版本（nodejs.org）
• Token101 API Key — 订阅用户可直接创建；Free 用户需先在 token.ppthub.shop/settings/apikeys 完成 API 激活
• 安装 Codex CLI（见步骤一）

步骤一 — 安装 Codex CLI

npm install -g @openai/codex

如果 npm 下载较慢，可使用国内镜像：

npm install -g @openai/codex --registry=https://registry.npmmirror.com

验证安装：

codex --version

步骤二 — 配置环境变量

Codex CLI 通过两个环境变量定位 API 服务器：

macOS / Linux — 临时设置（当前终端有效）

export OPENAI_BASE_URL="https://token.ppthub.shop/api/v1"
export OPENAI_API_KEY="your-token101-api-key"

macOS — 永久设置（zsh）

echo 'export OPENAI_BASE_URL="https://token.ppthub.shop/api/v1"' >> ~/.zshrc
echo 'export OPENAI_API_KEY="your-token101-api-key"' >> ~/.zshrc
source ~/.zshrc

macOS — 永久设置（bash）

echo 'export OPENAI_BASE_URL="https://token.ppthub.shop/api/v1"' >> ~/.bash_profile
echo 'export OPENAI_API_KEY="your-token101-api-key"' >> ~/.bash_profile
source ~/.bash_profile

Windows — 临时设置（PowerShell）

$env:OPENAI_BASE_URL = "https://token.ppthub.shop/api/v1"
$env:OPENAI_API_KEY = "your-token101-api-key"

Windows — 永久设置（PowerShell）

[System.Environment]::SetEnvironmentVariable("OPENAI_BASE_URL", "https://token.ppthub.shop/api/v1", "User")
[System.Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "your-token101-api-key", "User")

步骤三 — 验证连接

运行以下命令，确认 Codex 可以正常访问 Token101：

codex "Reply with exactly: TOKEN101_OK"

如果配置正确，Codex 将返回 TOKEN101_OK。

步骤四 — 在项目中使用 Codex

进入任意代码项目，开始使用 Codex：

cd ~/my-project

# 让 Codex 解释项目
codex "解释这个项目是做什么的"

# 让 Codex 编写函数
codex "写一个验证邮箱格式的函数"

# 让 Codex 修复 bug
codex "修复 src/utils.ts 第 42 行的 bug"

# 交互模式
codex

指定模型

Token101 支持多种模型，使用 --model 参数指定：

codex --model gpt-5.2 "为 src/auth.ts 编写单元测试"

完整模型列表请参阅支持的模型。

工作原理

Codex CLI 默认使用 OpenAI Responses API（wire_api = "responses"）。当你将 OPENAI_BASE_URL 设置为 Token101 时：

1. Codex 向 https://token.ppthub.shop/api/v1/responses 发送请求
2. Token101 验证 API Key，执行限流和计费逻辑
3. 由 Token101 的路由层将请求转发到底层模型服务商
4. 响应通过相同的管道流式返回

这意味着你能获得 Token101 的全部特性——用量追踪、计费控制、模型路由——同时无需改变使用 Codex 的方式。

可用模型

以下模型可与 Codex CLI 配合使用，通过 --model 参数选择：

完整列表请参阅支持的模型，包含非 OpenAI 模型。

已知限制

• 服务端工具执行：Token101 的 Responses API 是透传适配器——请求原样转发到上游模型服务商。服务端工具（如网页搜索）由上游模型服务商原生执行。
• 推理 Token 计费：推理/思考 Token 与其他端点一样享受自动折扣（Codex 系列 50% 折扣，非 Codex 的 GPT 25% 折扣，均作用于输出费率）。详见 计费。
• 模型名称：Codex 发送的模型名称会原样传递给 Token101。请使用上表中列出的准确模型 ID。旧版 OpenAI 模型名称（如 o3-mini、gpt-4.1）没有映射。

常见问题

报错 Error: 401 Unauthorized

API Key 无效或未设置。

1. 检查 OPENAI_API_KEY 是否已设置：echo $OPENAI_API_KEY
2. 在 token.ppthub.shop/settings/apikeys 确认 Key 状态正常
3. 确保 Key 以 sk- 开头

/api/v1/responses 返回 404

Responses API 端点无法访问。

1. 确认 OPENAI_BASE_URL 以 /api/v1 结尾（不是 /api/v1/responses）：

   echo $OPENAI_BASE_URL
   # 应输出：https://token.ppthub.shop/api/v1

2. 测试健康端点：curl https://token.ppthub.shop/api/health

报错 Error: 502 Bad Gateway

上游模型服务商暂时不可用。

1. 检查状态页是否有正在进行的故障
2. 用 --model gpt-5.2 尝试其他模型
3. 等待几秒后重试，通常是短暂性问题

报错 Error: 429 Too Many Requests

已达到请求频率限制。详见频率限制。

Codex 卡住或超时

1. 检查网络连接
2. 测试连通性：curl -s https://token.ppthub.shop/api/health
3. 先用简单的提示词排查问题

下一步

• 支持的模型 — 查看所有可用模型
• 频率限制 — 了解请求配额
• 计费说明 — 追踪和管理用量
• Claude Code 接入 — 同时使用 Claude Code 时的配置方法