OpenAI Codex 接入

Codex 支持在用户级 config.toml 中声明自定义模型提供方。本页将 FlashCoding.AI 配置为 Responses 协议 provider，并用环境变量提供 API Key，避免把密钥写入 TOML。

适用场景

• 使用 Codex CLI 或 Codex 桌面端，希望通过 FlashCoding.AI 调用控制台中的模型。
• 需要让多个项目共用一份本机 provider 配置。
• 已有 Codex 配置，希望在保留其他设置的同时增加 FlashCoding.AI provider。

前置条件

开始前准备好：

1. 已安装并能启动当前版本的 Codex。
2. 从 FlashCoding.AI 控制台创建的 API Key。下文统一写作 sk-your-key。
3. 从控制台复制的完整模型 ID。下文统一写作 your-model-id。
4. 目标模型和渠道支持 OpenAI Responses 协议。

Codex 读取的是用户级配置：

• macOS / Linux：~/.codex/config.toml
• Windows：%USERPROFILE%\.codex\config.toml

自定义 provider 放在用户级配置中，是因为 Codex 对项目级 .codex/config.toml 中 provider 项的处理有限。项目可以保留自己的其他设置，但本页的 model_providers.flashcoding 应写入用户级文件。字段含义可对照 Codex 官方配置参考。本页不创建 auth.json。

操作步骤

1. 设置 API Key 环境变量

macOS / Linux：

export FLASHCODING_API_KEY="sk-your-key"

Windows PowerShell：

$env:FLASHCODING_API_KEY = "sk-your-key"

真实密钥只放在环境变量或受保护的密钥管理工具中。不要把它写进 config.toml，也不要提交到 Git。

2. 打开用户级配置文件

macOS / Linux 可先确保目录存在：

mkdir -p ~/.codex

Windows PowerShell 可先确保目录存在：

New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex" | Out-Null

如果 config.toml 已存在，请先阅读并保留其中与本次接入无关的设置。把下面的顶层字段和 provider 段合并进去，不要直接覆盖整份文件：

model = "your-model-id"
model_provider = "flashcoding"

[model_providers.flashcoding]
name = "FlashCoding.AI"
base_url = "https://flashcoding.ai/v1"
env_key = "FLASHCODING_API_KEY"
wire_api = "responses"
requires_openai_auth = false
supports_websockets = false

配置中的 env_key 是环境变量名称，不是 API Key 本身。provider id 为 flashcoding，因此顶层的 model_provider 也必须写作 flashcoding。

合并现有 TOML

同一文件中不要重复声明 model、model_provider 或 [model_providers.flashcoding]。若已有同名字段，请修改原值；重复键会导致 TOML 解析失败。

3. 核对模型与协议

将 your-model-id 替换为控制台显示的完整模型 ID。这里的 wire_api 必须是 responses，Base URL 必须是 https://flashcoding.ai/v1。

requires_openai_auth = false 表示该 provider 不依赖 OpenAI 登录状态；鉴权由 FLASHCODING_API_KEY 提供。supports_websockets = false 让客户端使用普通 HTTP 流程。

4. 从同一终端启动 Codex

codex

在新会话中发送一个不涉及文件修改的测试请求：

请只回复：Codex 连接成功

环境变量只对当前终端及其子进程生效。若从桌面快捷方式启动，需要确保桌面进程也能读取 FLASHCODING_API_KEY，否则先在终端中完成验证。

成功验证

接入成功时应满足：

• Codex 能返回测试内容，且不要求通过 OpenAI 账户登录后才能调用。
• 会话使用 provider flashcoding 和你从控制台复制的模型 ID。
• FlashCoding.AI 控制台的使用记录中出现对应 Responses 请求。
• 最终请求地址以 https://flashcoding.ai/v1 为基础，没有重复的 /v1/v1。

常见错误

提示缺少 FLASHCODING_API_KEY

确认变量名与 env_key = "FLASHCODING_API_KEY" 完全一致，并从设置变量的同一个终端启动 Codex。新开的终端不会继承另一个终端会话中的临时变量。

Codex 仍要求 OpenAI 登录

检查 model_provider = "flashcoding" 是否位于 TOML 顶层，以及 provider 段是否包含 requires_openai_auth = false。不要通过创建或修改 auth.json 解决自定义 provider 的鉴权问题。

TOML 解析失败

检查引号、段名和重复键。尤其不要在已有 [model_providers.flashcoding] 段后再次添加同名段；应编辑现有段中的值。

401 或 API Key 无效

重新设置 FLASHCODING_API_KEY，确认真实密钥没有多余空格且未被停用。env_key 后面只能写变量名，不能把 sk-your-key 或真实密钥直接写入 TOML。

404、协议错误或响应无法解析

核对 base_url = "https://flashcoding.ai/v1" 和 wire_api = "responses"。不要把 Base URL 写成完整的 /v1/responses 路径，也不要把 wire_api 改成 Chat Completions 的请求格式。

WebSocket 连接失败

确认 supports_websockets = false。基础接入不需要启用 WebSocket；若客户端仍尝试连接，完全退出并重启，让它重新加载用户级配置。

模型不存在或不可用

从控制台重新复制完整模型 ID，确认当前密钥、分组和渠道允许通过 Responses 协议调用该模型。不要沿用其他客户端中的简称。

下一步

• 查看 Responses 的最小请求：阅读 OpenAI 兼容接口。
• 了解为什么这里的地址带 /v1：查看 Base URL 与协议。
• 请求仍然失败：按故障排查保留错误正文、请求时间和模型 ID。