Codex接入第三方模型的两种(桌面端和 CLI)的配置方法

Codex接入第三方模型的核心操作，是在~/.codex/config.toml里自定义一个model provider，再把全局的model_provider指向它。桌面端、CLI、IDE扩展的本地任务可以共享这套配置；但Codex Cloud需要ChatGPT登录,跟本地第三方API配置的性质不太一样，得分开看待。

用户真正想问什么

围绕"Codex怎么接入第三方模型"，真实的搜索意图大致可以分成四类：

查询类型	典型问题	最适合的回答形式
定义型	Codex支持第三方模型吗？	先解释provider、base URL、鉴权
操作型	Codex CLI怎么改config.toml？	给出可直接复制的TOML配置
场景型	桌面端能不能跟CLI共用配置？	说明Local、Worktree、Cloud三种模式的差异
排障型	为什么配置后仍然请求失败？	按认证、模型名、路径、配置层逐一排查

这篇文章会覆盖9个高价值查询：Codex能否接入第三方模型、CLI怎么配置、桌面端怎么生效、base_url要不要带/v1、env_key和requires_openai_auth怎么选、API key放哪里、项目配置为什么不生效、Cloud是否支持、常见报错怎么排查。

Codex支持哪些第三方模型接入方式

说到Codex接入第三方模型，本质上并不是在聊天框里临时粘一个API key那么简单，而是通过配置文件告诉Codex三件事：模型在哪、怎么通信、怎么鉴权。

常见的方式有三种：

接入方式	适合场景	关键字段
OpenAI-compatible API	API网关、中转、兼容平台	base_url、wire_api、env_key
LLM proxy	公司内部袋里、审计网关、数据驻留项目	base_url、requires_openai_auth 或自定义 auth
本地模型服务	Ollama、LM Studio、本机实验	base_url、provider名称、本地端口

OpenAI官方文档特别提醒过：自定义provider不能使用openai、ollama、lmstudio这些内置保留的provider ID。建议用清晰的自定义名称，比如gateway、company_proxy、local_test。

CLI怎么配置第三方模型

Codex CLI接入第三方模型时，应该优先修改用户级的~/.codex/config.toml。provider、base URL和鉴权相关的字段，不适合放在项目级的.codex/config.toml里。

方式一：环境变量鉴权

这是最通用的OpenAI-compatible API写法。以一个公开的API Gateway入口为例：

# ~/.codex/config.toml
model_provider = "gateway"
model = "后台显示的模型名"

[model_providers.gateway]
name = "OpenAI-compatible gateway"
base_url = "https://api.fenno.ai"
wire_api = "responses"
env_key = "OPENAI_COMPATIBLE_API_KEY"

然后在shell中设置密钥：

export OPENAI_COMPATIBLE_API_KEY="sk-你的-第三方-API-Key"
codex "解释当前仓库结构，不要修改文件"

这种做法的好处是配置文件里不直接保存密钥；缺点则是每个shell、CI环境或桌面端启动时，都必须能读到对应的环境变量。

方式二：OpenAI authentication

如果provider背后仍然走OpenAI的认证体系，Codex是直接支持的：

[model_providers.gateway]
name = "OpenAI using proxy"
base_url = "https://proxy.example.com/v1"
wire_api = "responses"
requires_openai_auth = true

注意：requires_openai_auth = true与env_key不要混用。官方文档写得很清楚——当requires_openai_auth = true时，Codex会忽略env_key。

方式三：只改内置OpenAI provider的base URL

如果只是想单纯地把内置OpenAI provider指向某个LLM proxy，官方文档提供了一个更简洁的写法：

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

这种写法适合"仍然使用内置OpenAI provider，只替换入口地址"的场景；但如果需要多个provider并存，还是用[model_providers.xxx]来定义更清晰。

桌面端怎么接入第三方模型

Codex桌面端的Local和Worktree任务会继承Codex agent的配置，所以高级的provider设置还是得回到~/.codex/config.toml里处理。桌面端的Settings更适合调整一些常用偏好，复杂的第三方模型配置还是以配置文件为准。

可以按四步来验证：

1. 在~/.codex/config.toml写入provider配置。
2. 重启Codex桌面端，确保旧进程不再使用旧环境。
3. 新建Local或Worktree线程。
4. 用只读任务测试，比如"解释当前项目结构，不要修改文件"。

桌面端需要特别区分三种运行模式：

模式	是否适合第三方provider测试	说明
Local	适合	直接在当前项目目录运行本地agent
Worktree	适合	在Git worktree中隔离改动，仍属于本地任务
Cloud	不能按本地provider来理解	官方文档说明，Codex cloud需要ChatGPT登录

如果你在CLI上能跑通，但桌面端不生效，常见原因是桌面端启动时没有读取到shell环境变量。更稳妥的做法是使用系统级环境变量、keyring/credential store，或者改用provider后台明确支持的鉴权模板。

base_url要不要带/v1

base_url是否带/v1，完全取决于provider的路由设计和Codex当前模板。不建议直接把其他工具的配置原封不动地复制到Codex里。

场景	常见写法	判断标准
Codex custom provider	根域名或/v1都有可能	以provider后台模板和实际测试为准
OpenAI-compatible SDK	多数使用/v1	看SDK文档
内部LLM proxy	由网关服务定义	看公司网关路由
本地模型服务	常见为本地/v1接口	看本地服务文档

排障时建议做最小化测试：只保留一个provider、一个模型名和一个API key，先跑一个只读的prompt。能返回结果后，再加入sandbox、MCP、web search、worktree等其他变量，一步步排查。

API key应该放哪里

API key不建议直接写进文章、仓库或项目级配置。Codex支持多种鉴权方式，具体选哪种要看你的使用场景。

放置方式	适合场景	风险
env_key + 环境变量	本地开发、CI、临时切换	桌面端可能读不到shell环境
Codex登录缓存 / credential store	OpenAI authentication	注意保护~/.codex/auth.json
命令式鉴权	企业内部token helper	需要额外维护脚本
写入项目文件	不建议	容易误提交和泄露

官方文档特别强调，~/.codex/auth.json里可能包含访问令牌，应该像保护密码一样对待它，不要提交到Git、工单或聊天记录里。

常见报错怎么排查

Codex接第三方模型失败时，建议按"配置层、认证、模型名、接口路径、运行模式"的顺序来排查。不建议一上来就同时改多个字段。

现象	常见原因	处理方式
配置不生效	写到了项目级.codex/config.toml	provider设置放到~/.codex/config.toml
401 / unauthorized	API key错误或鉴权方式混用	检查env_key与requires_openai_auth
404 / model not found	模型名与后台不一致	复制provider后台显示的模型名
timeout	网络、网关、袋里问题	先用curl或provider测速入口验证
CLI可用但桌面端不可用	桌面端没读到环境变量	重启app，改用更稳定的凭据存储
Cloud不按预期走第三方模型	把cloud当成本地provider	改用Local/Worktree验证

常见问题

可以说既是一套又不完全是一套。官方文档说明，Codex agent在桌面端、CLI和IDE扩展中会继承配置；但桌面端的UI设置、Local/Worktree/Cloud模式以及环境变量的读取方式，都会影响最终表现。

provider、base URL、认证方式这些跟model provider相关的字段，应该放在用户级的~/.codex/config.toml里。项目级的.codex/config.toml适合放项目规则、权限、MCP等可以共享的配置，不适合放provider密钥和入口地址。

不要把Codex cloud当成本地third-party provider来理解。官方文档说得很清楚，Codex cloud需要ChatGPT登录；API key authentication更适合本地CLI、SDK、IDE扩展这些工作流。

模型名应该以provider后台实际显示的为准。不要照搬旧文章里的模型ID，也不要假设OpenAI官方模型名一定能在第三方网关中使用。

不会。第三方模型或API网关主要改变的是模型入口、计费和可观测性；真正要减少token消耗，还得靠缩小任务范围、限制文件数量、先读后改、明确测试命令、减少反复试错这些基本功。

参考资料与时效性

• OpenAI Codex manual，2026-07-03抓取：Authentication、Config basics、Custom model providers、Codex app features、Codex app settings。
• api.fenno.ai/coding-plan公开页面，2026-07-03抓取：页面标题显示为AI API Gateway，公开配置包含api_base_url: "https://api.fenno.ai"。

Codex的配置字段、模型名称、第三方provider模板和API网关路由都可能变化，正式接入前，还是应以OpenAI当前文档和provider后台模板为准。时效性是这类配置指南的生命线。