Codex 桌面版读的是本地配置文件 ~/.codex/config.toml,Windows 上对应 %USERPROFILE%\.codex\config.toml。官方明确写了「ChatGPT 桌面应用、Codex CLI、IDE 扩展和 SDK 读取同一套本地配置层」,所以配第三方模型提供方不需要装插件。唯一硬约束是协议:接口必须兼容 Responses API。下面把配置文件位置、4 种接法、字段含义和排查顺序讲清。
Codex桌面版的入口与配置文件位置
Codex 的官方入口页在 chatgpt.com/codex,桌面应用的下载与快速上手指引都从这一页进。官方列出的使用形态一共五个:ChatGPT 桌面应用、ChatGPT 网页版、Codex CLI、IDE 扩展、Codex 云端。 这五个形态里,桌面应用、CLI、IDE 扩展共用同一份本地配置,所以本文的配置对三者都生效,只有云端的配置逻辑不同。config.toml 的落点分三处,写错地方是"配了没反应"的头号原因:
| | |
|---|
| ~/.codex/config.toml;Windows 为 %USERPROFILE%\.codex\config.toml | |
| | |
| $CODEX_HOME/配置档名.config.toml | 用 --profile 配置档名 切换,适合多套接口来回切 |
根目录本身可以用环境变量改:CODEX_HOME 默认是 ~/.codex,它管着配置、凭据、日志、会话和技能。设了它,那个目录必须已经存在,否则 Codex 找不到状态目录。除此之外,~/.codex 下还会出现凭据文件、会话记录,以及下面要重点说的 .env。
注意区分:用户级配置决定"用哪个模型提供方",项目级配置决定"这个仓库里 Codex 怎么干活",前者不能下放到项目级。这是官方刻意的安全设计——避免仓库里的文件把你的密钥指向别处。
配置第三方模型提供方的操作步骤
- 先确认桌面应用里那份 Codex 的版本。官方排错文档写明:桌面应用与 CLI 可能包含不同的 Codex 版本,所以会出现"CLI 里能用、桌面版里没有"的情况。CLI 侧执行 codex --version;macOS 桌面应用内置的那份在 /Applications/Codex.app/Contents/Resources/codex,同样可以加 --version 查询。
- 打开(没有就新建)用户级配置文件:macOS 与 Linux 是 ~/.codex/config.toml,Windows 是 %USERPROFILE%\.codex\config.toml。
- 在文件顶部指定模型与提供方,再写一节 [model_providers.<自定义id>],填入 base_url 和你自己的密钥变量名。TOML 有个坑:顶层键必须写在所有表之前,把 model 写到某个 [表] 后面会解析失败。
- 把密钥值放进 env_key 指定的那个环境变量里,不要直接把密钥写进 config.toml。
- 重启应用后再新建任务。官方对桌面应用与 IDE 扩展有一句专门提示:这两个形态可能读不到 shell 里的环境变量,需要把所需变量写进 ~/.codex/.env,然后重启应用或扩展。
- 验证:CLI 里执行 /status 看当前生效的提供方;桌面应用则在重启后新建任务,用输入框下方的模型选择控件确认。
4种接法对应的字段与示例
接第三方接口有四条路,复杂度递增,按需选一条就行:
| | |
|---|
| 接口本身就是 OpenAI 兼容的服务,或走自有网关、数据驻留节点 | |
| | [model_providers.<id>] 加 model_provider |
| 跑本地模型,官方内置 Ollama 与 LM Studio | |
| | model_provider = "amazon-bedrock" 加 AWS 区域 |
第一和第二条是主流。第一种最省事,官方原话说:如果只是要把内置的 OpenAI 提供方指向一个 LLM 代理、路由器或已启用数据驻留的项目,直接设 openai_base_url 就行,不必另建提供方。
第二种是功能最全的写法,下面这套结构对应官方示例的字段布局(把尖括号部分换成你自己的值):
字段本身有一张完整的对照表,下面是官方配置参考里逐条列出的项:
| | |
|---|
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | 该提供方是否使用 OpenAI 鉴权,默认 false |
| | |
| | |
| | 流式空闲超时,默认 300000 毫秒(5 分钟) |
| | 该提供方是否支持 Responses API 的 WebSocket 传输 |
supports_standalone_web_search | | 是否支持独立的联网搜索端点,自定义提供方默认 false |
| | |
auth.timeout_ms / auth.refresh_interval_ms | | 取令牌命令超时默认 5000,主动刷新间隔默认 300000 |
关于 wire_api 这一行要单独强调:值只能填 responses,而它指的是 Responses API 协议,不是早期那种对话补全协议。这是接第三方接口最容易翻车的地方——很多服务只提供兼容对话补全的端点,接上去会因为协议不通而直接失败,而且这类问题往往表现为"连上了但没反应",不容易一眼看穿。接之前先跟服务方确认一句:是否支持 Responses API 协议。
鉴权方式与项目级配置的限制
鉴权分两条线。用 ChatGPT 账号登录,走的是订阅权益;用 API 密钥,走的是按量计费。官方文档写明桌面应用、CLI 和 IDE 扩展对这两种登录方式都支持,只有 Codex 云端必须用 ChatGPT 登录。
自定义提供方的密钥不通过固定环境变量传递,而是由你写在 env_key 里的那个变量名决定——Codex 读的是这个配置项指向的名字。这条设计让多个提供方可以各用各的密钥变量,互不干扰。
需要从外部凭据系统动态换取令牌时,可以用 [model_providers.<id>.auth] 配置一条取令牌命令。这条命令不接收标准输入,必须把令牌打印到标准输出;Codex 会去掉首尾空白,把空令牌视为错误,并按你设的刷新间隔主动刷新(设成 0 则只在鉴权失败后重试一次)。
有一条互斥规则要注意:命令式鉴权不能和 env_key、experimental_bearer_token、requires_openai_auth 同时出现。另外官方把 experimental_bearer_token 标为不推荐的开发期用法,正路还是 env_key 或命令式取令牌。
项目级配置的限制见下方注意事项第三条。想让多个项目用不同接口,正确做法是用户级的配置档文件加 --profile 参数,而不是往仓库里塞配置。
需要核对字段原文时,官方有两页可以直接查:进阶配置页 developers.openai.com/codex/config-file/config-advanced 讲机制与示例,配置参考页 developers.openai.com/codex/config-file/config-reference 列全部键值。两页都支持在路径后加 .md 取纯 Markdown 原文。
配置不生效与报错的排查顺序
按下面这个顺序查,能覆盖绝大多数"配了没反应":
| | |
|---|
| 改的是项目级 .codex/config.toml,提供方相关键被忽略 | 把配置搬到用户级 ~/.codex/config.toml,重启应用 |
| 桌面应用与 IDE 扩展可能读不到 shell 的环境变量 | 把变量写进 ~/.codex/.env,然后重启应用或扩展 |
| 两边 Codex 版本不同,或配置目录根本不是同一份 | 分别查版本号;Windows 与 WSL 场景核对 CODEX_HOME |
| 接口协议不是 Responses API,或流式响应被中间层缓冲 | 向服务方确认协议;必要时调大 stream_idle_timeout_ms |
| | 调 request_max_retries、stream_max_retries(上限均为 100)与空闲超时 |
| | |
| | 用 http_headers 或 env_http_headers 补上 |
| | 按官方建议改为 RemoteSigned,改前先读一遍微软的执行策略说明 |
| | 以管理员身份启动 ChatGPT 桌面应用,Codex 会继承该权限级别 |
| 官方自某个版本起把 Linux 沙箱换成了 bubblewrap | |
排查用的日志位置也一并记下:会话记录在 $CODEX_HOME/sessions(默认 ~/.codex/sessions),归档会话在 ~/.codex/archived_sessions,macOS 上的应用日志在 ~/Library/Logs/com.openai.codex/ 下按年月日分目录。分享日志前先自己过一遍,确认里面没有敏感信息。
配置第三方接口前要确认的事
- 只用你有权使用的接口。合理场景是自己搭的网关、公司自有的云上模型服务、官方云厂商托管的模型,或本地跑的模型。来源不明的共享密钥、他人转卖的接口额度一律别接——一是通常违反服务条款,二是密钥随时可能失效或被盗用,三是你送进去的代码和密钥会经过不受你控制的第三方。
- 接口必须兼容 Responses API 协议。协议不匹配时不会降级到其他协议,细节见上文 wire_api 那一段。
- 项目级配置不能放提供方信息。官方会忽略仓库内 .codex/config.toml 里的 model_provider、model_providers、openai_base_url、chatgpt_base_url 等键,并在启动时打警告。反过来说,也别把密钥写进任何会被提交到代码仓库的文件。
- 内置提供方 ID 不可占用。openai、ollama、lmstudio 是保留 ID,自定义提供方必须另起名字;amazon-bedrock 是内置提供方,只支持嵌套的 AWS 配置档与区域两项覆盖。
- Windows 桌面版与 WSL 里的 CLI 默认不共享配置。桌面版用 %USERPROFILE%\.codex,WSL 里的 CLI 用 Linux 家目录下的 ~/.codex,两边各读各的。要让它们一致,可以双向同步,或者在 WSL 里把 CODEX_HOME 指到 Windows 那份目录。
- 桌面版与 CLI 的 Codex 版本可能不同。官方排错文档明确说明两者可以打包不同版本,新功能或实验特性可能先到 CLI。所以"桌面版里没这个选项"不等于版本落后,先分别查一遍版本号再下判断。
- 换接口就换了数据边界。用 ChatGPT 账号登录时,用量遵循所在工作区的权限与数据留存设置;改用 API 密钥后,遵循的是对应 API 组织的留存与数据共享设置。接第三方提供方后,输入内容的处理规则由那一方决定,官方文档不覆盖这部分。
- 一个时间点要记牢。官方模型页写明 GPT-5.5 将于 2026 年 10 月 14 日在 Codex 及 ChatGPT 全量套餐中退役(不适用于 OpenAI API),用 ChatGPT 登录的人要在到期前切到 GPT-5.6 Sol;如果你有多处配置写死了模型名,记得一起改。
Codex配置第三方接口常见问题
Q:桌面版能配第三方接口吗?
A:能。官方文档写明 ChatGPT 桌面应用、Codex CLI、IDE 扩展和 SDK 读取同一套本地配置层,模型提供方就写在这套配置里。
Q:配置文件到底放哪?
A:用户级是 ~/.codex/config.toml,Windows 是 %USERPROFILE%\.codex\config.toml。项目级的 .codex/config.toml 不能改模型提供方。
Q:为什么我配了没生效?
A:两个高频原因——写到了项目级配置里(提供方键会被忽略),或者密钥变量在桌面应用里读不到(需要写进 ~/.codex/.env 并重启应用)。
Q:接口要满足什么协议?
A:Responses API。wire_api 只接受 responses 这一个值,也是省略时的默认值,不匹配不会自动降级。
Q:密钥怎么写才安全?
A:用 env_key 指定一个环境变量名,密钥值放在变量或 ~/.codex/.env 里,不要写进 config.toml,更不要提交到代码仓库。
Q:能同时配多个提供方吗?
A:可以。每个提供方占一节 [model_providers.<id>],各用各的密钥变量,用 model_provider 或配置档加 --profile 切换。
Q:接本地模型怎么配?
A:官方内置了 Ollama 与 LM Studio,把 oss_provider 设成对应值,再用 --oss 会话跑本地模型即可,不必另建自定义提供方。
Q:能拿公司的 AWS 托管模型吗?
A:可以。amazon-bedrock 是内置提供方,配 AWS 配置档与区域两项即可;不填配置档就走标准 AWS 凭据链。
Q:桌面版和命令行结果不一样是怎么回事?
A:两者可能打包不同的 Codex 版本,功能会先到其中一个;在 Windows 上还多一层——桌面版读 %USERPROFILE%\.codex,WSL 里的命令行默认读 Linux 家目录,两边配置和会话都不同步。
模型名、字段默认值和退役时间表都会随官方更新调整,配置前先在官方配置参考页核对当期字段与取值即可。
回到实际使用上,Codex桌面版配置第三方API这件事最省事的路径是:先用 openai_base_url 试通,确认接口确实兼容 Responses API,再按需升级成完整的自定义提供方配置。