OpenAI Codex 桌面版

Codex Desktop 是 OpenAI 在 2025 年发布的 Codex 桌面应用 — 把 Codex CLI 的核心引擎封装成带聊天界面的独立 Electron 应用,Mac / Windows / Linux 都有。
跟 Codex CLI 共用同一份配置文件,所以已经配过 CLI 的话,Codex 桌面版可以零配置直接用。

1. 下载安装

去 OpenAI 官网下载:https://codex.openai.com/download

平台	安装包
macOS	`Codex-x.y.z-arm64.dmg`(Apple Silicon)/ `Codex-x.y.z-x64.dmg`(Intel)
Windows	`Codex Setup x.y.z.exe`
Linux	`Codex-x.y.z.AppImage` / `.deb` / `.rpm`

装完桌面会出现一个 Codex 图标(浅色背景上一个绿色 >_ 符号)。

2. 配置 Miloapi 接入

2.1 已经装过 Codex CLI

桌面版直接读 CLI 的配置文件:

文件	macOS / Linux	Windows
主配置	`~/.codex/config.toml`	`%USERPROFILE%\.codex\config.toml`
凭证	`~/.codex/auth.json`	`%USERPROFILE%\.codex\auth.json`

只要 Codex CLI 已经按 miloapi 文档配过,桌面版打开就能用。跳到第 3 步验证。

2.2 没装过 CLI / 想从头配

启动 Codex Desktop 第一次会让你选「Custom Provider」(或叫「Self-hosted endpoint」),填以下:

字段	值
Provider Name	`miloapi`(随便填)
Base URL	`https://www.miloapi.com/v1`
API Key	`sk-xxxxxxxx`(从 API 密钥复制)
Wire API	`responses`(下拉里选,不是 `chat_completions`)
Model	`gpt-5.5`(或其它你 Key 分组支持的 GPT 模型)

如果界面里没有这些字段,Codex 桌面版会把你的输入自动写入 ~/.codex/config.toml 和 ~/.codex/auth.json。也可以直接手编这两个文件,内容跟 Codex CLI 文档完全一致。

⚠️ base URL 必须带 /v1,不带的话所有调用都 404。

⚠️ Key 选 GPT 池(分组 platform=openai),Claude / Gemini 池的 Key 调不通 GPT 模型。

3. 验证

打开 Codex Desktop,在输入框敲:

帮我用 Python 写个 fibonacci

看到流式输出代码块就 OK。点底部「Settings」可以查看 / 切换 Provider。

4. 常用功能

功能	位置
切换模型	输入框上方的「Model」下拉
切换 Provider	设置 → Providers
内置文件编辑	拖文件到对话窗 / `@文件名` 引用
终端 / shell 工具	内置 sandbox,默认只读;改设置允许写
截图作为上下文	Mac:`Cmd+Shift+5` → 拖到对话窗
跨设备同步对话	关掉(走我们网关时,会话不上 OpenAI)

💡 关掉云同步:Codex 桌面版默认会把对话 metadata 同步到 OpenAI。走 miloapi 时这一步会失败(因为没用官方 OpenAI 账号),设置里 Disable cloud sync 关掉就行。

5. 故障排查

现象	处理
启动后一直转圈	Provider 配错。`base_url` 漏了 `/v1`,或者 `wire_api` 不是 `responses`
`401 Unauthorized`	`auth.json` 里 `OPENAI_API_KEY` 不对 / Key 已删 / Key 被禁用
`403 model not allowed`	Key 所在分组不支持这个模型。换 GPT 池的 Key,或在 miloapi 后台改 Key 分组
`429 Too Many Requests`	触发限流,稍等;或换分组 / 提升账户档位
工具调用一直循环	`model_reasoning_effort` 设太低,设置里调到 `high`
Windows 找不到配置目录	`mkdir %USERPROFILE%\.codex` 手动建
桌面版打开看不到自定义 Provider	版本旧。升级到最新 ≥ v0.20

6. 跟 CLI 的关系

	Codex CLI	Codex Desktop
平台	终端	独立 GUI 应用
配置文件	`~/.codex/*.toml/.json`	同一份,共享
Agent 能力	全套	全套
适合	远程服务器、纯键盘党	桌面 + 聊天习惯的用户
资源占用	几十 MB	~300 MB(Electron)

互不冲突,可以同时装。改一份配置两边都生效。