05 · Codex CLI 接入 Freecode#

Codex 使用 Responses 接口。本文用独立的 Freecode 环境变量认证，不需要把密钥写进 config.toml。

1. 安装#

已有受支持的 Node.js 环境时：

npm install -g @openai/codex
codex --version

也可按 Codex 官方 CLI 指南 选择其他安装方式。

2. 配置用户级 config.toml#

自定义供应商放在用户级配置文件中。已有文件时合并相关项，不要覆盖 MCP、项目或其他供应商配置，也不要重复定义同名 TOML 表。

#:schema https://developers.openai.com/codex/config-schema.json
model_provider = "freecode"
model = "gpt-6.1-sol"
model_reasoning_effort = "high"

[model_providers.freecode]
name = "Freecode"
base_url = "https://api.freecode.cc/v1"
wire_api = "responses"
env_key = "FREECODE_API_KEY"
requires_openai_auth = false

Base URL 需要带 /v1，但不要加 /responses。这里使用 env_key 读取 Freecode 密钥，所以 requires_openai_auth 设为 false；不要把另一套 auth.json 认证方式混进同一个供应商配置。

3. 设置密钥#

macOS / Linux / WSL，先在当前终端设置，再从这个终端启动 Codex：

export FREECODE_API_KEY="sk-your-freecode-api-key"
codex

Windows PowerShell：

$env:FREECODE_API_KEY = "sk-your-freecode-api-key"
codex

要长期使用，可把变量配置到自己的系统环境或受保护的本机配置中；新开的终端需重新读取。IDE 中使用时，确保启动 IDE 的进程也能读取该变量。

4. 验证#

在项目目录启动 Codex，核对供应商为 freecode、模型为 gpt-6.1-sol，发送一句话或让它读取项目并概括结构。收到真实回复后，在 使用日志 核对记录。

推理强度由模型实际能力决定；如果调整为其他模型，请按该模型的支持范围设置。先验证基础对话，再按实际分组支持情况启用搜索、图像等附加能力。

5. 常见问题#

• 提示 FREECODE_API_KEY 未设置：在启动 Codex 的同一个终端设置变量。
• 401：检查变量里是否为完整 Freecode 密钥，以及密钥是否仍有效。
• 404：确认地址是 https://api.freecode.cc/v1，没有重复 /v1 或多加 /responses。
• 模型不可用：检查精确 ID、密钥分组和模型允许列表。
• 仍走其他供应商：检查用户级 model_provider，以及是否有 CC Switch 或启动参数覆盖配置。

更多排查见 常见问题。

参考：原 Codex 指南、官方高级配置、官方认证说明。配置已结合实际读取的 OpenAI 官方文档核对。