Codex 接入

当前 Codex 推荐在用户级 config.toml 中定义自有 Provider，通过环境变量读取 FreedomZ AI 密钥。CLI 和官方 IDE 扩展共用 $CODEX_HOME/config.toml。

1. 准备信息

开始前确认：

1. Key 已绑定支持 OpenAI Responses 的可用分组。
2. GET https://freedomz.cn/v1/models 能看到目标模型。
3. 账户余额或可用服务正常。

2. 安装 Codex

Windows PowerShell：

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
codex --version

macOS / Linux：

curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex --version

也可以使用 npm：

npm install -g @openai/codex

3. 设置密钥

Windows PowerShell 当前会话：

$env:FREEDOMZ_API_KEY = "YOUR_API_KEY"

macOS / Linux 当前会话：

export FREEDOMZ_API_KEY="YOUR_API_KEY"

生产环境建议使用系统凭据库或受控的环境注入方式，不要把密钥直接写入 config.toml。

4. 配置 Provider

配置文件位置：

系统	默认位置
Windows	%USERPROFILE%\.codex\config.toml
macOS / Linux	~/.codex/config.toml

加入以下配置，并把模型 ID 替换为 /v1/models 的真实返回值：

model = "MODEL_ID_FROM_V1_MODELS"
model_provider = "freedomz"
model_reasoning_effort = "xhigh"

[model_providers.freedomz]
name = "FreedomZ AI"
base_url = "https://freedomz.cn/v1"
env_key = "FREEDOMZ_API_KEY"
wire_api = "responses"
request_max_retries = 1
stream_max_retries = 1
stream_idle_timeout_ms = 300000

xhigh 只用于明确支持该推理强度的模型；不支持时改为 high、medium 或模型 要求的值。不要把 Provider 命名为保留的 openai。

为什么限制重试

有限重试可以避免网络抖动导致任务直接失败，同时防止认证或策略错误被反复提交。 401 和 403 出现后仍应立即停止当前任务。

5. 启动与验证

在已经设置环境变量的终端中运行：

codex

发送一个不带工具和附件的测试任务。随后打开 使用记录：

• 有新记录：请求已经经过 FreedomZ AI。
• 没有记录：检查 Codex 是否读取了其他 CODEX_HOME、Profile 或官方登录配置。

官方 VS Code 扩展

官方 Codex IDE 扩展与 CLI 共用 $CODEX_HOME/config.toml。修改后重新加载 VS Code 窗口，再进行测试。不要在扩展中同时保留会覆盖 Provider 的旧配置。

常见错误

现象	优先检查
Missing environment variable	FREEDOMZ_API_KEY 是否在启动 Codex 的进程环境中
401 / invalid api key	Key 是否完整、有效；停止自动重试
404 或路径错误	base_url 是否准确为 https://freedomz.cn/v1
model not found	模型 ID 是否来自当前 Key 的 /v1/models
推理强度报错	将 xhigh 调整为模型支持的值
能对话但站内无记录	检查 Provider、Profile 和官方登录状态

配置字段以 OpenAI Codex 官方文档 和当前 Codex 版本为准。