Codex 客户端（桌面 App / IDE 扩展）

本页介绍桌面 App 和 IDE 扩展。终端用法见 Codex CLI 接入。模型名称从全部模型 ID 查询；Codex 专用列表以 GET https://modelfold.ai/openai/v1/models 为准。

Agent 调用会消耗积分

Agent 会携带系统提示、工具定义和项目上下文，首次请求可能比普通聊天消耗更多积分。先用短消息确认接入，再开始项目任务。

下载安装与客户端区别

以下官方入口核对于 2026-11-10：

客户端	安装入口与范围
桌面 App 中的 Codex	官方桌面入口目前跳转到 ChatGPT desktop app 文档；从该页下载 macOS / Windows 版本，进入 Codex。已有独立 Codex App 的用户仍按下面的本地 provider 配置；具体界面以安装版本为准。Linux 安装入口也在该官方页。
VS Code / Cursor / Windsurf	从 OpenAI 官方 IDE 页面选择编辑器，安装官方 Codex 扩展；打开 Codex 侧栏。Cursor 自带的模型设置不等于 Codex 扩展设置。
终端	使用 Codex CLI。

本文配置的是本机 Codex 的模型请求，不是给 ChatGPT 普通聊天或云端任务填第三方 Key。JetBrains / Xcode 有各自集成，本文不把 VS Code 扩展的步骤套用到它们。

共用配置文件，不需要另找网关表单

OpenAI 的网关接入说明明确要求桌面 App 读取本机 config.toml，保存后重启；配置说明确认 CLI 和 IDE 共用配置层。

系统 / 环境	用户级配置路径
macOS / Linux	`~/.codex/config.toml`
Windows	`%USERPROFILE%\.codex\config.toml`
WSL / 远程开发	在实际运行 Codex 的 Linux / 远程环境里配置；不要只改宿主 Windows 文件。

若设置了 CODEX_HOME，请检查实际使用的配置目录。先备份原文件，再合并下方字段，不要覆盖其他设置或重复定义 TOML 表。

IDE 扩展可从右上角齿轮进入 Codex Settings → Open config.toml。桌面 App 有 Settings 界面，但本次查到的官方设置页没有说明可直接填写第三方 Base URL / Key 的表单；按官方网关流程编辑文件即可，不能把“登录 ChatGPT”当成接入 ModelFold。

配置 ModelFold

先到控制台 → API Keys创建 Key。推荐 GPT‑6.1 Sol：本次线上 Codex 列表 ID 为 gpt-6.1-sol，接口返回的模型名为 gpt-6-1-sol。配置使用列表 ID；以后模型变化时查询全部模型 ID和 Codex 专用列表，不要自行把点替换成横线。

把下面内容合并到用户级配置。model、model_provider、web_search 必须位于第一个 TOML 表之前：

toml

model = "gpt-6.1-sol"
model_provider = "ModelFold"
web_search = "disabled"

[model_providers.ModelFold]
name = "ModelFold"
base_url = "https://modelfold.ai/openai/v1"
env_key = "MODELFOLD_API_KEY"
wire_api = "responses"
requires_openai_auth = false
supports_websockets = false
model_catalog_url = "https://modelfold.ai/openai/v1/models"

Codex 自动拼接 /responses，不要把完整接口路径填进 base_url。
env_key 是变量名，不能填 Key 本身；请求使用 Authorization: Bearer。
requires_openai_auth = false 使用 ModelFold Key 认证；本配置不需要用 ChatGPT 凭证认证网关。
先使用 HTTP/SSE，并关闭联网搜索；本页没有验证 WebSocket、联网搜索或其他托管工具。
model_catalog_url 获取 Codex 专用模型元数据。如果原配置有 model_catalog_json，它优先于远端目录；不要让旧目录遮住新模型。仅含 .data[].id 的普通模型列表不足以描述自定义模型能力。参见官方模型目录说明。

让客户端进程拿到 Key

只在一个终端里执行 export，不保证从 Dock / 开始菜单打开的 App 或已启动的编辑器能读到变量。不要把真实 Key 写进项目仓库。

macOS

在终端里设置（将占位符换成自己的 Key）：

bash

export MODELFOLD_API_KEY="mf-你的Key"
launchctl setenv MODELFOLD_API_KEY "$MODELFOLD_API_KEY"

完全退出桌面 App 或 VS Code / Cursor 后重新打开。launchctl setenv 作用于当前用户的登录会话，注销 / 重启后需要重新设置；只关窗口不算退出。此命令是给 GUI 进程传递变量，不会修改 Codex 配置文件。

Windows（PowerShell）

powershell

$env:MODELFOLD_API_KEY = "mf-你的Key"
[Environment]::SetEnvironmentVariable("MODELFOLD_API_KEY", $env:MODELFOLD_API_KEY, "User")

第一行对当前终端有效，第二行保存用户变量。完全退出客户端后重新打开；仍读不到时注销 Windows 再登录。WSL 需在 WSL 内另外设置变量。

Linux / 从终端启动 IDE

bash

export MODELFOLD_API_KEY="mf-你的Key"
code .
# Cursor 用户改用 cursor .

启动前先完全退出已有编辑器进程，避免命令复用未继承变量的旧进程。桌面启动器的环境取决于发行版；确保变量进入实际客户端进程。

怎么确认生效

保存配置、完全退出并重开客户端，然后开始一个新会话，发送“只回复 gateway-ok”。再到控制台调用记录核对时间与模型；仅看到回复不能证明走了哪个服务商。此操作会消耗积分。

2026-11-10 验证范围： 使用专用测试 Key，按上述配置的地址、模型与 Bearer 认证直接调用 https://modelfold.ai/openai/v1/responses：

检查	结果
普通响应	HTTP 200，`status: completed`
HTTP/SSE 流式	HTTP 200，有文本增量和 `response.completed`
工具调用	返回 `function_call` 和合法 JSON 参数
工具结果回传	携带 `function_call_output` 后 HTTP 200，正常完成

本次使用 API / 配置文件模拟，没有启动桌面 App 或 IDE GUI；不把协议验证等同于所有客户端版本的界面验收。测试工具只返回固定文本，没有执行项目命令。

常见问题

现象	检查方法
缺少 MODELFOLD_API_KEY	变量必须进入客户端进程；按上面的系统步骤配置并完全重启。
401	核对 Key 是否有效，不要给变量值额外加 `Bearer` 。
404 / 模型不可用	`base_url` 只写到 `/openai/v1`；模型使用专用列表里的 ID，检查是否被旧模型目录覆盖。
仍走 OpenAI / 仍提示账号登录	确认读到了正确配置、`model_provider` 与表名一致，顶层字段没有放进表内；检查项目或受管配置覆盖。
402 / 积分不足	在 ModelFold 控制台补充积分。
配置后旧会话仍用旧模型	完全重启，开启新会话并检查调用记录。
工具 / 插件不可用	模型网关只负责推理；MCP、插件、云端任务和其他服务需各自配置与授权。

继续阅读：Codex CLI · 全部模型 ID · 常见问题排查。

Codex 客户端（桌面 App / IDE 扩展） ​

下载安装与客户端区别 ​

共用配置文件，不需要另找网关表单 ​

配置 ModelFold ​

让客户端进程拿到 Key ​

macOS ​

Windows（PowerShell） ​

Linux / 从终端启动 IDE ​

怎么确认生效 ​

常见问题 ​