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)。先看它是否存在:
ls -l ~/.codex/config.toml
Test-Path "$env:USERPROFILE\.codex\config.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,一个请求都不会发出去。看到这句就去核对这两处拼写。
设置环境变量
export KL_API_KEY="你的 Key"
setx KL_API_KEY "你的 Key"
macOS / Linux 想让它对每个终端都生效,把这行加进 ~/.zshrc 或 ~/.bashrc。Windows 用 setx 之后要重开终端,当前窗口读不到新值。
验证
先确认变量读得到,再跑一次最小调用:
echo "${KL_API_KEY:0:6}..." && codex exec "只回复 OK 两个字"
$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:
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 CLI 配置结构:https://github.com/openai/codex(仓库
codex-rs配置模块) - 接口地址与鉴权方式:快速开始
- 报错原文与分层排查:API 报 401、429、超时怎么排查