Codex API 密钥是指任何可以让 Codex CLI 按 token 计费、而不是使用 ChatGPT 方案的密钥:可以是来自 platform.openai.com 的 OpenAI API 密钥,也可以是 Kunavo 的 provider 密钥,例如 sk-kn-;Codex 会在 model_providers 块中从 env_key 指定的环境变量读取它。 Provider 必须提供 Responses API——这是下面唯一的要求。
Codex CLI 是 OpenAI 的开源终端代码代理,可以使用 ChatGPT 登录或 API 密钥运行。值得理解的是 API 密钥路线:它按 token 计费且无月费,而且只有这条路线允许你将 CLI 指向其他 provider——甚至完全不同的模型家族。本指南介绍实际配置、最容易让网关出问题的唯一要求,以及一次会话的真实成本。
唯一重要的要求
与大多数工具相比,Codex CLI 对自定义端点更加严格。它的 model_providers 块包含一个 wire_api 键,并且只接受一个值:responses。这意味着自定义 provider 必须在 POST /v1/responses 提供 OpenAI 的 Responses API——而不是更常见的 /v1/chat/completions。大多数 OpenAI 兼容网关只提供后者,因此无论你给它什么 base_url,都无法驱动 Codex CLI。
Kunavo 提供两种接口,因此下面的配置可以直接使用。
配置
Codex 会读取 ~/.codex/config.toml。两个顶层键用于选择模型和 provider;provider 块描述如何连接到它:
# ~/.codex/config.toml
model = "gpt-5-6-sol"
model_provider = "kunavo"
[model_providers.kunavo]
name = "kunavo"
base_url = "https://api.kunavo.com/v1"
env_key = "KUNAVO_API_KEY"
wire_api = "responses"注意该文件中没有什么:密钥本身。env_key指定一个环境变量,Codex 会在启动时从那里读取密钥——因此配置文件可以安全地提交或共享。
# Codex reads the key from the variable named by env_key.
export KUNAVO_API_KEY="sk-kn-..." # create at kunavo.com/app/keys
# Persist it (pick the file your shell actually loads):
echo 'export KUNAVO_API_KEY="sk-kn-..."' >> ~/.zshrc
codex "explain the structure of this repository"在注册并充值 $10 后,在控制台中创建密钥。密钥只显示一次,请立即保存。如果 codex 已在另一个 shell 中运行,请重启它——它会在启动时读取变量,而不是每次请求时读取。
调试前先验证
如果出现问题,请先确认问题来自密钥、端点还是 CLI。一个请求即可确定:
# Confirm the key and the endpoint before blaming Codex.
curl https://api.kunavo.com/v1/responses \
-H "Authorization: Bearer $KUNAVO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5-6-sol",
"input": "Say OK and nothing else."
}'返回 JSON 表示密钥和端点正常,剩余问题位于 config.toml。返回 401 表示密钥错误,或该变量在当前 shell 中为空。在 model 上返回 404 表示 slug 与目录不匹配。
应该设置哪个模型
model 的值只是同一端点上的 slug,因此切换只需修改一个词——无需新密钥,也无需新的 provider 块。
| 任务 | 模型 | Kunavo 输入 / 输出(每 100 万 Token) |
|---|---|---|
| 代码专用默认模型 | gpt-5-6-sol | $2.00 / $12.00 |
| 最困难的重构和调试 | claude-opus-5 | $3.50 / $17.50 |
| 日常 agentic 编码 | claude-sonnet-5 | $1.40 / $7.00 |
| 快速编辑和问答 | claude-haiku-4-5 | $0.70 / $3.50 |
gpt-5-6-sol 是针对编码调优的 GPT,是此 CLI 的自然默认选择,价格为每 1M token $2.00 / $12.00,而 OpenAI 官方价目为 $5.00 / $30.00——不过,OpenAI 目前收取促销价 $4.00 / $20.00,至少持续到 2026年11月21日。所有模型的完整价格见价格页面。
在 Codex CLI 中运行 Claude 模型
这会让很多人感到意外:Codex CLI受协议约束,而不是受模型约束。它使用 Responses wire 格式,端点后面的任何聊天模型都可以响应。将它指向 claude-opus-5 后即可端到端运行——包括工具调用,因此代理仍会照常读取文件、提出修改和运行命令。
# Same provider block, different model — no new key, no new config.
model = "claude-opus-5"
model_provider = "kunavo"
[model_providers.kunavo]
name = "kunavo"
base_url = "https://api.kunavo.com/v1"
env_key = "KUNAVO_API_KEY"
wire_api = "responses"网关会将 Responses 请求转换为 Anthropic Messages API,再将回复转换回 Responses 形式。需要诚实说明的一点是:Codex 会发送不透明的 reasoning 项,只有原生支持 Responses 的模型才能使用这些项;它们在发送到非 GPT 上游时会被丢弃。模型会失去上一轮的私有草稿,但它所依据的可见记录仍然完整。实际上,长推理链会因此损失一些连续性,而普通的编辑—运行—修复循环完全不会受到影响。
这是否是个好主意,与它是否可行是两个问题。如果你明确想使用 Claude,Claude Code 是为此构建的,并会将 cache_control 原样传递而不进行转换。但如果你更喜欢 Codex CLI 的沙箱,并希望在其后使用 Claude,这种组合也是可行的。
会话成本
Agentic CLI 会在每一步重新发送 system prompt、任务历史和最新文件上下文,因此 token 的累积速度比步数所暗示的更快。典型的一步大约包含 25,000 个输入 token 和 1,200 个输出 token:
| 单位 | token(输入 / 输出) | gpt-5-6-sol | 按 OpenAI 官方价目 |
|---|---|---|---|
| 一次代理式步骤 | 25,000 / 1,200 | $0.024 | $0.061 |
| 一个 20 步任务 | 约 500k / 约 24k | ~$0.48 | ~$1.21 |
| 高强度的一天(5 个此类任务) | — | ~$2.42 | ~$6.05 |
由于不同模型家族的输出费率差异远大于输入费率,输出占比较高的任务会改变排名——请将自己的数字输入成本计算器,不要依赖单个示例。失败的请求不收费。
API 密钥路线何时优于订阅
ChatGPT 方案以固定月费打包 Codex 使用量;API 密钥只对实际运行的内容收费。如果你集中编码而不是每天编码,希望获得每个密钥的支出上限和使用情况可见性,而不是不透明的额度,或者想使用订阅不提供的模型,密钥路线更有优势。如果你是每天高强度使用者,它就不占优势——在这种用量下,固定费率很难被超越。两条路线并不冲突:Codex profile 允许你同时保留两者,并按任务切换。
故障排除
| 症状 | 原因 |
|---|---|
每个请求中的 404 | Provider 不提供 /v1/responses,或者 base_url 已经包含该路径——它应以 /v1 结尾。 |
401 Unauthorized | env_key 指定的变量在启动 Codex 的 shell 中为空。导出变量后请重启 shell。 |
| 找不到模型 | Slug 与目录不匹配。Slug 使用连字符:gpt-5-6-sol,而不是 gpt-5.3-codex。 |
wire_api 被拒绝 | 只接受 "responses"。使用 "chat" 的配置无法加载。 |
| 配额不足 | 钱包余额低于请求估算金额。请在充值与账单中充值。 |
常见问题
如何在 Codex CLI 中使用 API 密钥?
在 ~/.codex/config.toml 中添加一个 [model_providers.NAME] 块,包含 base_url、env_key 和 wire_api = "responses",然后将 model_provider 设置为该名称。Codex 会从 env_key 指定的环境变量中读取密钥——不会将密钥存储在配置文件中。使用 Kunavo 时,base URL 是 https://api.kunavo.com/v1,密钥是在 kunavo.com/app/keys 创建的 sk-kn- 密钥。
Codex CLI 可以使用自定义 API 端点而不是 OpenAI 吗?
可以,但提供商必须在 POST /v1/responses 提供 OpenAI Responses API。Codex CLI 的 model_providers 块只接受 wire_api = "responses",因此只提供 /v1/chat/completions 的网关无法配置。Kunavo 同时提供两者,因此可使用上面的配置块。
运行 Codex CLI 需要 ChatGPT Plus 或 Pro 订阅吗?
不需要。Codex CLI 可以使用 ChatGPT 方案登录,也可以使用 API 密钥运行。API 密钥路线按 token 计费且无月费;如果你不是每天编码,而是集中进行,这种形式更便宜,而且只有这条路线允许你将 CLI 指向其他 provider 或模型家族。
Codex CLI 能运行 Claude 模型吗?
可以,通过提供 Responses API 的网关实现。Codex CLI 受协议约束,而不是受模型约束:它使用 Responses wire 格式,端点后面的任何聊天模型都可以响应。将 Codex CLI 指向 Kunavo 并设置 model = claude-opus-5 后,它可以端到端运行,包括工具调用——网关会在 Responses 与 Anthropic Messages API 之间进行转换。
为什么 Codex CLI 使用自定义 provider 时返回 404?
几乎总是因为 provider 未实现 POST /v1/responses,或者 base_url 已经包含 /responses 路径。Codex 会自行追加路径,因此 base_url 应以 /v1 结尾。如果返回 401,则表示 env_key 指定的环境变量在启动 Codex 的 shell 中为空。
Codex CLI 将 API 密钥存在哪里?
它不会存储。env_key 指定一个环境变量,Codex 会在启动时从环境中读取密钥,因此 config.toml 不包含任何机密,可以安全提交。
需要 ChatGPT 订阅吗?
不需要。密钥是登录方式的完整替代方案,也是唯一支持自定义 provider 或非 GPT 模型的路线。
这适用于 IDE 扩展中的 Codex 吗?
扩展与 CLI 共享 ~/.codex/config.toml,因此使用相同的 provider 块。编辑后请重启编辑器。
可以同时保留 OpenAI 和网关吗?
可以——定义多个 [model_providers.*] 块,并使用 model_provider 进行切换;或者将每个块包装在 Codex profile 中,按运行选择。
这与 Claude Code 相比如何?
Claude Code 会读取 ANTHROPIC_BASE_URL 并使用 Messages API,因此将它指向网关只需设置三个环境变量,无需配置文件。完整比较——扩展功能、沙箱、成本结构——见 Claude Code 与 Codex CLI。由于 Codex 受协议而非模型约束,同一端点后使用 Claude 模型只需改一行;Anthropic Claude API 价格表列出了该路线的每 token 价格。