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

2026-07-08 10:12:45 vibecoding77

Codex 接入第三方模型的核心步骤，是在 ~/.codex/config.toml 中定义自定义 model provider，并把 model_provider 指向这个 provider。桌面端、CLI、IDE extension 的本地任务可以共享这套配置；但 Codex cloud 需要 ChatGPT 登录，不能简单等同于本地第三方 API 配置。

用户真正想问什么

围绕“Codex 怎么接入第三方模型”，真实搜索意图通常分成 4 类。

查询类型	典型问题	最适合的回答形式
定义型	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 支持的第三方模型接入，本质上是“自定义 model provider”。它不是在聊天框里临时粘一个 API key，而是通过配置文件告诉 Codex：模型在哪里、用哪种协议、怎样鉴权。

常见方式有 3 种：

接入方式	适合场景	关键字段
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 manual 明确提醒：自定义 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 authentication，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 不要混用。OpenAI manual 说明，当 requires_openai_auth = true 时，Codex 会忽略 env_key。

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

如果只是想把内置 OpenAI provider 指向某个 LLM proxy，OpenAI manual 提供了更短的写法：

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

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

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

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

可以按 4 步验证：

在 ~/.codex/config.toml 写入 provider 配置。
重启 Codex 桌面端，避免旧进程继续使用旧环境。
新建 Local 或 Worktree 线程。
用只读任务测试，例如“解释当前项目结构，不要修改文件”。

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

模式	是否适合第三方 provider 测试	说明
Local	适合	直接在当前项目目录运行本地 agent
Worktree	适合	在 Git worktree 中隔离改动，仍属于本地任务
Cloud	不按本地 provider 理解	OpenAI manual 说明 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	需要额外维护脚本
写入项目文件	不建议	容易误提交和泄露

OpenAI manual 说明，~/.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 验证

常见问题

Q：Codex 桌面端和 CLI 是两套配置吗？
不是完全两套。OpenAI manual 说明，Codex agent 在桌面端、CLI 和 IDE extension 中会继承配置；但桌面端的 UI 设置、Local/Worktree/Cloud 模式和环境变量读取方式会影响最终表现。

Q：第三方模型配置应该放项目里还是用户目录？
provider、base URL、认证方式和 model provider 相关字段应放在用户级 ~/.codex/config.toml。项目级 .codex/config.toml 适合项目规则、权限、MCP 等可共享配置，不适合放 provider 密钥和入口地址。

Q：Codex cloud 能不能用同一个第三方 provider？
不要把 Codex cloud 当成本地 third-party provider 配置来理解。OpenAI manual 说明，Codex cloud 需要 ChatGPT 登录；API key authentication 更适合本地 CLI、SDK、IDE extension 等工作流。

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

Q：接入第三方模型会不会自动省 token？
不会。第三方模型或 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 后台模板为准。

到此这篇关于Codex接入第三方模型的两种(桌面端和 CLI)的配置方法的文章就介绍到这了,更多相关Codex接入第三方模型内容请搜索脚本之家以前的文章或继续浏览下面的相关文章，希望大家以后多多支持脚本之家！