JetAPI / Codex CLI 接入教程

Codex CLI 接入 JetAPI 完整教程

Codex CLI 通过 ~/.codex/config.toml 里的 model_providers 段落配置自定义端点。 关键点:base_url 必须带 /v1(与 Claude Code 相反), 认证走 env_key 指定的环境变量。配置完成后运行 codex 即可。

一、准备条件

项目要求检查方法
Node.js18 以上node --version
Codex CLI已安装codex --version
API Keysk- 开头,分组支持 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

所以:短请求名义单价偏高,长对话里这个固定成本会被摊薄,影响很小。需要更干净计费时可选用直连线路。

九、相关页面