Codex Desktop / ChatGPT
Codex Desktop 是 Codex 的桌面图形客户端。通过配置自定义模型提供商（Model Provider），可以在桌面端直接接入模力方舟的大模型，并支持动态拉取模型目录。
OpenAI 现已将原独立的 Codex Desktop 整合进统一的 ChatGPT 桌面端应用（ChatGPT Desktop）（内建 Chat、Work 与 Codex 模式），部分系统或应用商店中客户端显示名称为 ChatGPT。无论应用显示为 Codex 还是 ChatGPT，底层的配置文件路径（~/.codex/config.toml）与配置方式保持一致。
模力方舟支持 Codex 原生 Responses API（wire_api = "responses"），兼容流式输出与工具调用 （Tool Calling）。
如需在终端中使用命令行工具，请参阅 Codex CLI 快速配置。
准备工作与获取访问令牌
-
安装客户端：从 Codex 官方网站 下载并安装客户端（当前已整合为 ChatGPT 桌面端）。
-
获取访问令牌：前往 工作台 -> 设置 -> 访问令牌 创建或复制访问令牌。访问令牌用于服务端鉴权，请妥善保管，不要提交至公开代码仓库。
-
确认默认模型：确定默认启动使用的模型 slug（如
DeepSeek-V4-Flash或DeepSeek-V4-Pro）。平台模型 slug 支持大小写兼容（如deepseek-v4-flash与DeepSeek-V4-Flash均可识别）。
定位配置文件
Codex 的自定义模型配置保存在用户级配置文件 config.toml 中。各系统的默认路径如下：
- Windows
- macOS / Linux
在文件资源管理器或编辑器中打开（不存在则手动创建）：
%USERPROFILE%\.codex\config.toml
在终端或编辑器中打开：
~/.codex/config.toml
若设置了 CODEX_HOME 环境变量，请编辑该目录下的 config.toml。修改前建议备份原文件。
合并配置到 config.toml
在 config.toml 中合并以下配置，并将占位符替换为实际信息：
# 顶层配置：必须放在文件中首个 [表] 声明之前
model = "DeepSeek-V4-Flash"
model_provider = "my-gateway"
[features]
api_key_model_discovery = true
[model_providers.my-gateway]
name = "Moark"
base_url = "https://ai.gitee.com/v1"
wire_api = "responses"
model_catalog_url = "https://ai.gitee.com/v1/models"
experimental_bearer_token = "<你的访问令牌>"
配置字段说明
| 字段 / 占位符 | 说明与填写规则 |
|---|---|
model | 默认模型 slug，如 DeepSeek-V4-Flash 或 DeepSeek-V4-Pro（平台支持大小写兼容） |
model_provider | 启用的提供商 ID，必须与下方 [model_providers.<id>] 键名一致（如 my-gateway） |
[features] 段 | 配置 api_key_model_discovery = true，在桌面端模型选择器中自动拉取服务端模型列表 |
name | 提供商显示名称（如 Moark） |
base_url | 接口地址，配置为 https://ai.gitee.com/v1（如走 /api/v1 路由，亦可填写 https://ai.gitee.com/api/v1） |
wire_api | 通信协议格式，必须设置为 "responses" |
model_catalog_url | 远程模型目录完整地址（必须包含 /models），如 https://ai.gitee.com/v1/models |
experimental_bearer_token | 填入获取到的访问令牌 |
配置合并规则
按 TOML 层级合并，不要直接将整段内容追加到文件末尾：
- 顶层配置位置：
model和model_provider属于顶层键，必须放在文件中第一个[...]表声明之前。已有配置项时直接更新其值。 - 避免重复表声明：已有
[features]段时，将api_key_model_discovery = true合并入原段，不要重复声明[features]。 - 提供商 ID 一致：顶层
model_provider的值必须与[model_providers.xxx]的小节名一致。 - 目录 URL 写全：
model_catalog_url不会自动追加/models，必须填写完整 URL。 - 检查覆盖配置：若配置了
model_catalog_json，它会优先于远程模型目录生效；使用 profile 时，确认所选 profile 未覆盖当前模型设置。
重启与验证
保存后完全退出并重启客户端（关闭聊天窗口并未退出进程，需从系统托盘或任务管理器退出）。
重启后依次测试：
- 模型列表：打开左下角模型选择器，确认能看到远程模型目录，并切换至目标模型。
- 流式输出：发送一句问候，确认能正常流式返回内容。
- 工具调用：在测试工程中发送只读指令（如“列出当前目录文件并简要说明，不要修改文件”），确认工具正常触发并解析。
- 连续追问：就上一轮结果继续提问，确认多轮上下文衔接正常。
常见故障排查
模型未出现在选择列表中
- 检查 TOML 语法：检查是否有重复表头，确认顶层
model、model_provider未被误放进其他配置表内。 - 检查目录 URL：确认
model_catalog_url包含/models且网络可达。 - 清理本地模型缓存：Codex 会在本地缓存模型目录。配置更新后若未出现新模型，在完全退出客户端后删除缓存文件并重启：
- Windows (PowerShell)
- macOS / Linux
Remove-Item "$env:USERPROFILE\.codex\models_cache.json" -ErrorAction SilentlyContinue
rm -f ~/.codex/models_cache.json
若自定义了 CODEX_HOME，删除对应目录下的 models_cache.json。
对话报错或工具调用失败
- 确认访问令牌有效、账户额度充足，且两端无多余空格。
- 确认
wire_api保持为"responses"。 - 如需联系平台排查，请提供客户端版本、模型 slug 与报错信息，不要附带访问令牌。
让 Codex 协助自动配置
如果已在运行 Codex，可复制以下 Prompt 让其按本地环境自动合并配置（将 <你的模型 slug> 替换为实际值）：
请帮我将当前电脑的 Codex Desktop 接入 Moark 自定义模型。
接入参数：
- provider ID：my-gateway
- provider 名称：Moark
- base_url：https://ai.gitee.com/v1
- wire_api：responses
- model_catalog_url：https://ai.gitee.com/v1/models
- model：<你的模型 slug>
- 鉴权字段：experimental_bearer_token，值为我的 Moark 访问令牌
- 功能配置：[features] 下 api_key_model_discovery = true
操作要求：
1. 根据当前系统和 CODEX_HOME 定位用户级 config.toml。
2. 读取现有配置并备份，保留无关配置。
3. 合并配置，不直接将整段 TOML 追加到文件末尾。
4. model 和 model_provider 必须位于顶层、首 个表声明之前；已有配置项或配置段时更新原位置，避免重复定义。
5. 检查 model_catalog_json、profile 或其他配置覆盖问题；发现冲突时说明具体位置和影响，不擅自删除无关设置。
6. 不要在对话、日志或展示的 diff 中输出访问令牌；如果尚未提供令牌，请指导我在本地填写。
7. 修改后检查 TOML 语法，说明实际修改内容；如果当前版本不支持某个配置项，请明确说明，不猜测替代项。
8. 提示我完全退出并重启客户端，不要自动退出当前应用。
9. 指导我验证模型列表、基础对话、本地只读工具调用和连续追问。
京公网安备11011502039387号