Codex CLI Guide

Codex CLI 自定义 Provider 配置

Codex CLI 可以通过配置文件接入自定义 model provider。配置前先确认 `openai_base_url`、`base_url`、模型 ID、`wire_api`、token 扣费和隐私政策。

测试前核对

  • 公开记录 OpenAI-compatible `/v1` API。
  • 模型名和 coding 模型支持情况可核对。
  • input/output token 价格、失败请求扣费和退款规则清楚。
  • 测试前能看到隐私政策和日志保存说明。

配置前检查

  • 确认平台明确支持 OpenAI-compatible API，而不是只提供网页聊天。
  • 确认是否支持你要用的 GPT、DeepSeek、Qwen、Gemini 或其他 coding 模型。
  • 确认 Base URL、模型名、API Key、流式输出和错误码格式。
  • 确认计费是否按 input/output tokens 分开计算，以及失败请求是否扣费。
  • 查看隐私政策、日志保存、退款规则和客服渠道。

最小环境变量测试

先用临时环境变量隔离端点和鉴权问题。长期自定义 provider 应按当前 Codex 配置格式写入用户级配置，不要直接复制未知版本的 shell 片段。

OPENAI_API_KEY="your-gateway-api-key"
OPENAI_BASE_URL="https://example.com/v1"
OPENAI_MODEL="provider-model-id"

内置 OpenAI Provider 的快捷配置

如果只是把 Codex 内置 OpenAI provider 指向代理或数据驻留端点，官方 advanced config 使用 `openai_base_url`。不要定义 `[model_providers.openai]`，因为内置 provider ID 不能被覆盖。

openai_base_url = "https://example.com/v1"

自定义 provider 配置核对

公开 Codex 配置示例和 provider 文档通常会用 `~/.codex/config.toml` 持久化自定义 provider。复制 TOML 前，先确认 provider 需要的 wire API、模型 ID 和密钥保存方式。

  • 使用 provider 专属的 `model_provider` id，不要默认把内置 OpenAI provider 当成通用代理配置。
  • 确认 provider 需要 `wire_api = "responses"` 还是 `wire_api = "chat"`；Codex 编程工作流通常更要关注 Responses 风格兼容。
  • 优先用 `env_key` 读取环境变量，例如 `EXAMPLE_API_KEY`，不要把真实 key 写进 TOML。
  • 如果项目内 `.codex/config.toml` 提示 `model_provider` 不支持或被忽略，把 provider 定义移到用户级 `~/.codex/config.toml` 后再测试。
  • 把最小环境变量测试和长期 profile 配置分开，避免同时排查 provider、profile、模型名多个问题。
  • 把 provider 凭证放在环境变量或用户级配置中。不要让不可信项目内配置把凭证或代码流量重定向到未知 provider。
model = "provider-model-id"
model_provider = "example_gateway"

[model_providers.example_gateway]
name = "Example Gateway"
base_url = "https://example.com/v1"
env_key = "EXAMPLE_GATEWAY_API_KEY"
wire_api = "responses"

小额测试流程

  1. 先用公开示例仓库或无敏感代码片段测试，不要直接接入私有业务仓库。
  2. 测试代码解释、跨文件修改、长上下文、流式输出和错误恢复。
  3. 记录延迟、成功率、扣费、输出质量和模型是否疑似掉包。
  4. 如果要长期使用，把不同平台的 token 成本统一换算后再比较。

选择建议

GPT/Codex 工作流最看重的是 OpenAI-compatible 兼容性、模型质量、上下文长度、响应速度和稳定扣费。低价只是其中一项，不能替代隐私和稳定性。

生产环境、客户代码、密钥和商业机密建议走官方 API、云厂商渠道或自建网关。中转平台更适合非敏感项目、小额验证和模型实验。

常见问题

Codex CLI 中转站一定要支持 OpenAI-compatible API 吗？

通常需要。Codex CLI 和大多数 GPT 编程工具更容易接入 OpenAI-compatible API，因此要优先确认 Base URL、模型名、鉴权方式和流式输出是否兼容。

低价 GPT/Codex 中转站可以直接用于生产项目吗？

不建议直接用于生产项目。应先用小额余额、无敏感代码和固定测试集验证稳定性、扣费规则、模型质量和隐私说明。

如何比较不同 Codex API 中转站的价格？

把所有平台统一换算成每 1M input tokens 和每 1M output tokens 的成本，再结合失败请求是否扣费、上下文缓存、最低充值和退款规则比较。

Codex 中转配置应该先用环境变量还是 config.toml？

调试新中转时先用最小环境变量测试。只有在 provider 已确认 Base URL、模型 ID、wire API、流式输出和鉴权行为后，再迁移到 `~/.codex/config.toml` 做长期配置。