Codex 手动配置第三方 API：Provider、凭证与验证

Codex配置第三方API的5步流程

适合谁，不适合谁

前置条件

1. Windows 已安装 Codex CLI 或带 Codex 的 VS Code 扩展。
2. PowerShell 中运行 codex --help 与 codex --version 能正常返回。
3. 如果使用小贺API，可以访问 `https://api.xiao-he.top/` 查看当前 API Key、模型名和接入说明；使用官方 OpenAI 账号则按官方登录流程操作。
4. 准备一个无敏感信息的测试目录，用于最后执行只读任务。

第一步：先判断使用官方还是第三方

这一步很关键：不要把官方登录方式和第三方 Provider 配置混在一起。

• 第三方 Base URL：按当前服务的接口说明复制，不猜测后缀。
• API Key：只复制到本机认证流程，不要写进 `config.toml` 的公开示例。
• 模型名：复制控制台当前可用标识，不根据品牌名或旧教程猜测。

只走手动配置路径

本页使用自定义Provider与环境变量提供凭证。选择自动管理时，转到 CC Switch导入与启用教程，无需再执行本文的手动步骤。

第二步：编辑 Codex 的 `config.toml`

Windows 默认路径通常是：

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

官方 OpenAI 登录可以保留默认 Provider，不需要照抄下面的第三方地址。使用小贺API等兼容网关时，再把 `MODEL_FROM_CONSOLE` 替换为控制台当前模型名；`api` 只是本地 provider 名称，可以保持一致。

model_provider = "api"
model = "MODEL_FROM_CONSOLE"

[model_providers.api]
base_url = "https://api.example.com/v1"
wire_api = "responses"
name = "My API provider"
env_key = "MY_API_KEY"

上面是结构示例，example.com不是可调用服务。必须将地址、模型和变量来源改成同一服务的真实配置。若你拿到的配置文件已经包含 `base_url`，不要再额外填写一个 URL；如果服务文档或 Codex 版本要求不同协议，也不要强行照抄 `wire_api`。

第三步：由启动环境提供凭证

上面的 env_key 指向 MY_API_KEY 环境变量。真实Key不写入TOML，也不要用第三方Key覆盖官方登录缓存。下面示例适用于PowerShell 7；隐藏输入可避免明文进入命令历史，但环境变量仍需妥善保护。

$env:MY_API_KEY = Read-Host '输入当前服务的API Key' -MaskInput
try {
  codex
} finally {
  Remove-Item Env:MY_API_KEY -ErrorAction SilentlyContinue
}

在这个终端中启动的CLI可以读取该变量；从桌面另行打开的IDE不一定继承。IDE请按其实际启动环境设置，不用CLI成功推断另一客户端也成功。官方自定义Provider说明。

第四步：诊断配置，再跑一个只读任务

先在当前CLI会话完成下面的只读任务，再对照当前Provider与服务端记录。诊断子命令随版本变化，以本机 codex --help 为准，不将某个可选诊断命令设为成功前提。

在前一步启动的Codex会话中，选择无敏感数据的练习目录并发送以下任务：

只读取当前目录，列出最多10个文件；不修改文件，不安装依赖，不访问外部网站。

怎样判断已经成功？

• 当前Provider能读取其 env_key 指定的变量；不打印完整值。
• 用户级配置中的地址、模型与Responses协议来自同一服务。
• 最小任务能够返回与当前目录相符的结果。
• 任务没有产生你未授权的文件修改。
• 控制台能够看到与测试相符的使用行为或日志时，再做一次交叉确认。

常见报错与检查顺序

`401 Unauthorized`

先重新复制 Key，确认没有空格、换行或截断；再确认当前Provider读取的环境变量名称与服务归属，检查Base URL、协议和账户权限。

`403 Forbidden`

通常表示当前凭证没有请求该资源的权限，或服务策略拒绝请求。不要反复更换随机参数，先查看控制台与服务说明。

`404` 或模型不存在

核对 `model` 是否完全等于控制台当前标识，并确认 Base URL 是否需要版本路径。不要根据文章示例猜模型名。

连接超时或无法连接

分别检查域名能否访问、服务状态、代理或防火墙、系统时间和 DNS。记录完整错误文本后再判断，不把一次 `401` 当作模型调用成功。

修改 `config.toml` 后没有变化

确认文件保存在当前用户的 `.codex` 目录、扩展名不是 `.txt`、TOML 引号和段落正确，并重启正在运行的 Codex 客户端。

PowerShell 直接运行 `codex.exe` 显示 Access is denied

先用 `Get-Command codex` 查看实际启动路径。WindowsApps 启动器在部分环境中不可用时，可从已安装的 VS Code Codex 扩展目录定位其自带二进制；不要下载来历不明的替代程序。

Get-ChildItem "$env:USERPROFILE\.vscode\extensions\openai.chatgpt-*\bin\windows-x86_64\codex.exe" |
  Sort-Object LastWriteTime -Descending |
  Select-Object -First 1 -ExpandProperty FullName

参考资料

• OpenAI Codex Configuration Reference：说明用户级与项目级配置、Provider、Base URL 和环境变量字段。
• OpenAI Codex Authentication：区分 ChatGPT 登录和 API Key 登录，并说明认证缓存与 codex login。
• Codex config.toml 与 Provider 实操说明：将官方登录和第三方兼容网关配置分开讨论。

下一步