使用 API 密钥的 Codex CLI——配置、模型与会话成本

Codex CLI 是 OpenAI 开源的终端代码代理，既可以使用 ChatGPT 登录，也可以使用API 密钥。值得理解的是 API 密钥路线：按 token 收费，没有月费，并且这是唯一允许将 CLI 指向其他提供商或其他模型系列的方式。本指南介绍可用的配置、大多数网关会失败的要求、一次会话的成本，以及如何在巴西使用 Pix 付款。

唯一重要的要求

Codex CLI 使用 OpenAI 的Responses API，而且只能使用它：model_providers 块仅接受 wire_api = "responses"。只提供 /v1/chat/completions 的网关无法配置——这就是许多“兼容 OpenAI”的端点在这里失败的原因。Kunavo 在聊天端点之外还提供 POST /v1/responses，因此下面的配置无需调整即可使用。

配置

# ~/.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 永远不会将密钥写入配置文件。

# O Codex lê a chave da variável indicada em env_key.
export KUNAVO_API_KEY="sk-kn-..."     # crie em kunavo.com/app/keys

# Deixe persistente (escolha o arquivo que o seu shell realmente carrega):
echo 'export KUNAVO_API_KEY="sk-kn-..."' >> ~/.zshrc

codex "explique a estrutura deste repositório"

完成注册并充值 $10 后，在控制台中创建密钥——密钥只会显示一次。

在巴西付款——Pix，无需国际信用卡

对于巴西开发者来说，障碍通常很少是 TOML 文件，而是支付方式。直接向 OpenAI 支付 API 费用，需要启用海外购物功能的国际信用卡。在 Kunavo，结账由Stripe处理，Pix会为从巴西付款的用户显示为支付方式——金额以雷亚尔计价并即时到账。偏好使用国际银行卡（Visa、Mastercard、American Express）、Apple Pay 或 Google Pay 的用户仍可使用这些方式。

每 token 的费率以USD计价：使用 Pix 时，Stripe 会在付款时显示换算后的巴西雷亚尔金额；使用信用卡时，换算遵循发卡机构的汇率（请在银行应用中确认 IOF 和国际交易手续费）——Pix 充值步骤请参阅如何使用 Pix 支付 API 指南。钱包是预付费的——最低充值金额为 $10，无订阅、无自动续费，并且余额永不过期。

使用哪个模型

gpt-5-6-sol 是针对代码调优的 GPT，也是此 CLI 的自然默认模型；每 1M token 的价格为 $2.00 / $12.00，相比之下，对应的价格为 $5.00 / $30.00（按 OpenAI 的标价计算——OpenAI 目前收取促销价 $4.00 / $20.00，根据价格页至少持续到 2026年11月21日）。完整费率请参阅价格页面。

在 Codex CLI 中运行 Claude 模型

这通常会让人感到意外：Codex CLI受协议约束，而不是受模型约束。它使用 Responses 格式通信，位于该端点后的任何聊天模型都可以响应。将其指向 claude-opus-5 后，它可以端到端运行——包括工具调用，因此代理仍能读取文件、提出编辑并运行命令。

# Mesmo bloco de provider, outro modelo — sem chave nova, sem config nova.
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 会发送只有原生 Responses 模型才能使用的不透明 reasoning 项目；在发送给非 GPT 上游的过程中，这些项目会被丢弃。模型会失去上一轮的私有草稿，但它所依据的可见转录内容保持不变。实际影响是，长篇推理链的连续性会略有降低，而常见的编辑-运行-修复循环不会受到影响。

如果你明确想使用 Claude，Claude Code就是为此打造的，并且会在无需转换的情况下传递cache_control。但如果你更喜欢 Codex CLI 的沙箱，又想在其后使用 Claude，这种组合是可行的。

一次会话的成本

智能体 CLI 会在每一步重新发送系统提示词、任务历史和文件上下文，因此 token 的累积速度比步骤数量所暗示的更快。典型的一步大约包含 25,000 个输入 token 和 1,200 个输出 token：

也就是说，一次通过 Pix 充值的 $10 大约可以覆盖 8 个包含 20 步的 agentic 任务。而且失败的请求不会收费——会话中途出现 5xx 不会变成账单上的一行。

出现问题时

在归咎于 Codex 之前，先确认密钥和端点确实能够响应：

# Confirme a chave e o endpoint antes de culpar o 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": "Responda OK e nada mais."
  }'

• 404——提供商未实现 /v1/responses，或者 base_url 已经包含 /responses。Codex 会自动追加该路径：base_url 以 /v1 结尾。
• 401——env_key 指定的变量在启动 Codex 的 shell 中为空。请在同一个终端中使用 echo $KUNAVO_API_KEY 检查。
• 402——余额不足：请在 billing 中充值（Pix 会立即到账）。
• model_not_found——模型 slug 不存在于目录中；请在 /models 中检查。

常见问题