Codex CLI 怎么接入 KL API

Codex CLI 用 config.toml 配置模型提供方:base_url 指向 KL API 的 /v1,Key 走环境变量。(2026-11-22)

适用系统:Windows / macOS / Linux · 更新于

准备工作

  • 已安装 Codex CLI,并且 `codex` 命令能跑起来
  • 一个 KL API 的 API Key(在控制台创建)
  • 知道要用的模型名,见 [模型清单](/models)

配置项对照

Codex CLI 的模型接入只认四个值,先对上再动手:

配置项 应填值
base_url https://agent.kl-api.info/v1
API Key 你的 Key,放环境变量,不要写进 config.toml
model gpt-5(或 模型清单 里其他模型 ID)
wire_api responses(想用 Chat Completions 就填 chat)

注意

Key 只能放在环境变量里。写进 config.toml 会在你提交仓库、分享配置时一起泄露,且无法追回。

写入配置

配置文件位置固定:~/.codex/config.toml(Windows 上是 %USERPROFILE%\.codex\config.toml)。先看它是否存在:

macOS / Linux
ls -l ~/.codex/config.toml
Windows PowerShell
Test-Path "$env:USERPROFILE\.codex\config.toml"

没有就创建,然后把下面这段写进去:

toml
model = "gpt-5"
model_provider = "kl"

[model_providers.kl]
name = "KL API"
base_url = "https://agent.kl-api.info/v1"
env_key = "KL_API_KEY"
wire_api = "responses"

注意

model_provider 的值必须和 [model_providers.kl] 里的名字完全一致,连大小写都算。写错不会回落,CLI 直接退出:Error: Model provider 'klx' not found,一个请求都不会发出去。看到这句就去核对这两处拼写。

设置环境变量

macOS / Linux
export KL_API_KEY="你的 Key"
Windows PowerShell
setx KL_API_KEY "你的 Key"

macOS / Linux 想让它对每个终端都生效,把这行加进 ~/.zshrc 或 ~/.bashrc。Windows 用 setx 之后要重开终端,当前窗口读不到新值。

验证

先确认变量读得到,再跑一次最小调用:

macOS / Linux
echo "${KL_API_KEY:0:6}..." && codex exec "只回复 OK 两个字"
Windows PowerShell
$env:KL_API_KEY.Substring(0,6) + "..." ; codex exec "只回复 OK 两个字"

看到模型回了 OK 就算通了。如果打印出来是空的,说明变量没进当前环境,先解决这一步再查别的。

关于 wire_api

现在只支持 responses,也就是请求走 /v1/responses。

写法 状态
wire_api = "responses" 当前支持,按本文配置即可
wire_api = "chat" 已不再支持,CLI 启动即报错退出

写成 chat 的报错原文是 Error loading config.toml: wire_api = "chat" is no longer supported.,并给出官方说明链接。如果模型只支持 Chat Completions 接口,用下面的方式单独验证它能不能用,别改 wire_api:

bash
curl https://agent.kl-api.info/v1/chat/completions \
  -H "Authorization: Bearer $KL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5","messages":[{"role":"user","content":"你好"}]}'

提示

同一套 base_url 和 Key 同时兼容两种接口路径,区别只在 Codex 客户端这一侧限制成了 responses。所以「模型能不能用」和「Codex 能不能接」是两件事。

验证状态

项目 状态
~/.codex/config.toml 会被读取(写坏一行即报错) 已实测(2026-11-22,codex-cli 0.130.0-alpha.5)
wire_api = "responses" 打到 /v1/responses,带 Bearer 头 已实测
model_provider 与段名不一致会直接报错退出 已实测,原文 Error: Model provider 'klx' not found
wire_api = "chat" 已不被支持 已实测
用真 Key 端到端返回 未验证
macOS / Linux 全流程 未验证

未验证项会在用真 Key 跑通后更新本表,不提前标成「已验证」。

参考来源(核对于 2026-11-22)

常见问题

Codex 改了 base_url 还是连官方地址,为什么?

多半是配置没写到生效位置:Codex 只读 ~/.codex/config.toml,项目目录里的同名文件不会被自动加载。改完先 codex --version 确认命令可用,再重启会话。

Codex 提示 401 lab token denied 怎么办?

三种可能:Key 没写进环境变量、Key 已被禁用、账户欠费。先确认环境变量名和 config.toml 里的 env_key 完全一致,再核对 Key 状态。详见 报错排查。

Codex 报 model not found 是什么原因?

model 值不在服务端模型清单里。别猜名字,直接查 模型清单,填清单里的模型 ID。

Windows 上环境变量怎么设才不会丢?

用 setx 写进用户环境变量后必须重开终端,当前窗口读不到新值。临时用可以用 $env:KL_API_KEY="...",但关窗口就失效。