Codex CLI 接入 JetAPI 完整教程
Codex CLI 通过 ~/.codex/config.toml 里的 model_providers 段落配置自定义端点。
关键点:base_url 必须带 /v1(与 Claude Code 相反),
认证走 env_key 指定的环境变量。配置完成后运行 codex 即可。
一、准备条件
| 项目 | 要求 | 检查方法 |
|---|---|---|
| Node.js | 18 以上 | node --version |
| Codex CLI | 已安装 | codex --version |
| API Key | sk- 开头,分组支持 Codex/GPT 模型 | 控制台「API Key」页创建 |
安装 Codex CLI:
npm install -g @openai/codex
codex --version
二、关键:base_url 必须带 /v1
Codex CLI 走 OpenAI 协议,它把 base_url 当作目录前缀,自己再拼 /chat/completions 或 /responses。
| 填法 | 实际请求路径 | 结果 |
|---|---|---|
https://api.jetapi.icu/v1 | /v1/chat/completions | ✓ 正常 |
https://api.jetapi.icu | /chat/completions | ✗ 404 |
和 Claude Code 的区别:Claude Code 的
ANTHROPIC_BASE_URL 不带 /v1;
Codex 的 base_url 要带 /v1。两个工具的规则相反,混用必然报错。
三、配置文件写法
编辑 ~/.codex/config.toml(Windows 为 %USERPROFILE%\.codex\config.toml):
model_provider = "jetapi"
model = "gpt-6.1-sol"
[model_providers.jetapi]
name = "JetAPI"
base_url = "https://api.jetapi.icu/v1"
env_key = "JETAPI_API_KEY"
三个字段的作用
| 字段 | 作用 |
|---|---|
model_provider | 指定当前使用哪个 provider,值要等于下面段落名(model_providers.jetapi) |
model | 默认模型,可在运行时用 --model 参数覆盖 |
env_key | 存放 Key 的环境变量名,不是 Key 本身。Codex 启动时读这个变量 |
常见错误:把 Key 直接写进
env_key。该字段要填的是变量名(如 JETAPI_API_KEY),
Key 本身放在环境变量里。
四、设置环境变量
Windows(PowerShell)
# 当前会话
$env:JETAPI_API_KEY = "sk-你的密钥"
# 永久写入(新开终端生效)
[Environment]::SetEnvironmentVariable("JETAPI_API_KEY", "sk-你的密钥", "User")
macOS / Linux
# zsh
echo 'export JETAPI_API_KEY="sk-你的密钥"' >> ~/.zshrc
source ~/.zshrc
# bash
echo 'export JETAPI_API_KEY="sk-你的密钥"' >> ~/.bashrc
source ~/.bashrc
五、选择模型
Codex 分组下可用的模型(具体以定价页为准):
| 模型 | 说明 |
|---|---|
gpt-6.1-sol | 较新的主力模型 |
gpt-6.1-terra | 同代不同规格 |
gpt-6-astra | — |
gpt-6-sol / gpt-6-luna | — |
gpt-5.6-sol / gpt-5.6-terra / gpt-5.6-luna | 上一代 |
gpt-5.5 | — |
gpt-5.4-mini | 轻量模型,成本低 |
运行时临时换模型:
codex --model gpt-5.6-sol
确认哪些模型可用:
curl https://api.jetapi.icu/v1/models \
-H "Authorization: Bearer $JETAPI_API_KEY"
六、验证配置
方式一:直接运行
codex
> 你好
能正常回复即说明连通。
方式二:直接发 API 请求(排除 CLI 层问题)
curl https://api.jetapi.icu/v1/chat/completions \
-H "Authorization: Bearer $JETAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-6.1-sol",
"messages": [{"role":"user","content":"说一句你好"}],
"max_tokens": 20
}'
如果 curl 通但 CLI 不通,问题在 Codex 的配置而不是端点。
方式三:看用量记录
去控制台「查询用量」页,确认刚才那次调用有没有被记录。有记录 = 真的走了 JetAPI。
七、常见错误与排查
| 报错 | 原因 | 解法 |
|---|---|---|
404 not_found |
base_url 少了 /v1 |
改成 https://api.jetapi.icu/v1 |
401 Unauthorized |
环境变量没设,或变量名和 env_key 不一致 |
检查 echo $JETAPI_API_KEY 和配置里的 env_key 是否同名 |
model_not_found |
模型名不在该分组支持范围内 | 用 GET /v1/models 查实际可用名 |
insufficient_quota |
余额 ≤ 0 | 充值后立即恢复 |
| 配置改了但没生效 | Codex 进程缓存了旧配置 | 完全退出后重新启动 |
八、Codex 通道的 token 特点
使用 Codex 系模型时会观察到一个现象:短请求的 token 数远大于实际输入。
例如发送 hi 两个 token,返回的 usage 可能是:
{
"input_tokens": 4418,
"output_tokens": 5,
"cache_read_input_tokens": 4224
}
原因是上游在每次请求中注入了约 4400 tokens 的 system prompt(工具定义、环境信息、审批策略)。
| 项目 | 数值 |
|---|---|
| 固定前置 | 约 4400 tokens |
| 命中缓存比例 | 约 95% |
| 缓存计费折扣 | 按 1/10 价 |
| 等效成本 | 约 600 tokens |
所以:短请求名义单价偏高,长对话里这个固定成本会被摊薄,影响很小。需要更干净计费时可选用直连线路。