Codex 桌面应用部署指南

资源	地址
Codex 桌面应用官网	developers.openai.com/codex/app
Mac/Windows 下载页	chatgpt.com/codex

📋 先看一眼

本文是 Codex 桌面应用（图形界面版）的部署指南。如果你想要的是命令行版本，请看 Codex CLI 部署指南。

桌面应用和 CLI 共用同一套配置文件（~/.codex/），所以下面写的配置流程，CLI 也会自动生效。

关于 Codex 桌面应用

Codex 桌面应用是 OpenAI 推出的图形界面 AI 编程助手，2026 年 3 月起 macOS 和 Windows 都已正式支持。相比 CLI，它多了几个特性：

🖼️ 可视化界面：图形化展示代码生成、文件改动
🌐 应用内浏览：直接在 App 里查看网页
🎨 图像生成：内置图像生成能力
🧠 会话记忆：跨会话保留上下文
🔌 插件系统：通过插件扩展能力
💻 Computer Use：桌面操作能力（实验性）

第一步：下载并安装

🍎 macOS 安装

1. 选对版本

Codex 桌面应用在 macOS 上分两个版本，下载前先确认你的芯片：

Apple Silicon（M1 / M2 / M3 / M4 等）→ 下载 Apple Silicon 版
Intel 芯片（2020 前的 Mac）→ 下载 Intel 版

如何判断？点左上角 → 关于本机 → 看「芯片」一栏：

写「Apple M1」/「Apple M2」等 → Apple Silicon
写「Intel Core i5」/「Intel Core i7」等 → Intel

2. 下载

打开浏览器访问 chatgpt.com/codex，点页面上的下载按钮，选择对应版本（Apple Silicon 或 Intel）。

3. 安装

双击下载下来的 .dmg 文件挂载磁盘镜像
把 Codex 图标拖到「应用程序」文件夹
从启动台或应用程序文件夹打开 Codex（首次打开 macOS 会弹出安全提示，点「打开」继续）

🪟 Windows 安装

方法一：Microsoft Store（推荐）

打开 Microsoft Store 链接，点 「获取」 按钮安装。

方法二：命令行 winget

powershell

winget install Codex -s msstore

系统建议

为获得最佳体验，建议同时安装：

Git
Node.js 18+
Python（如果你写 Python）
GitHub CLI（如果你用 GitHub）

🐧 Linux 安装

⚠️ 注意

Codex 桌面应用目前没有官方的 Linux 版本。 OpenAI 文档说 Linux 版「Planned（计划中）」。

如果你是 Linux 用户，建议：

改用 Codex CLI，功能完整且稳定
或者关注社区方案，比如 codex-desktop-linux（非官方，自负风险）

第二步：配置卡皮巴拉中转服务

⚠️ 关键步骤，必看

Codex 桌面应用默认连接 OpenAI 官方 API。要让它走卡皮巴拉中转，必须先配置 ~/.codex/ 目录下的两个文件，然后再首次启动。

如果你之前已经配置过 Codex CLI，这一步可以直接跳过，因为桌面应用会读同样的配置文件。

配置文件路径

系统	配置目录
macOS / Linux	`~/.codex/`
Windows	`%USERPROFILE%\.codex\`

需要在这个目录下创建两个文件：

config.toml — 模型和服务商配置
auth.json — API 密钥

macOS / Linux 配置

打开终端：

bash

mkdir -p ~/.codex
cd ~/.codex

写入 `config.toml`

bash

cat > config.toml << 'EOF'
model_provider = "Capybara"
model = "gpt-5.4"
model_reasoning_effort = "xhigh"
disable_response_storage = true
approval_policy = "on-request"
sandbox_mode = "danger-full-access"
model_supports_reasoning_summaries = true

[model_providers.Capybara]
name = "capybara"
base_url = "https://ai.bututrip.fun/v1"
wire_api = "responses"
requires_openai_auth = true
EOF

写入 `auth.json`

bash

cat > auth.json << 'EOF'
{
  "OPENAI_API_KEY": "把你在卡皮巴拉创建的 Codex 密钥粘贴在这里"
}
EOF

Windows 配置

按 Win + R，输入 cmd 打开命令提示符：

cmd

mkdir %USERPROFILE%\.codex
cd %USERPROFILE%\.codex

然后用记事本（或 VS Code）在这个目录下手动新建两个文件：

`config.toml`

toml

model_provider = "Capybara"
model = "gpt-5.4"
model_reasoning_effort = "xhigh"
disable_response_storage = true
approval_policy = "on-request"
sandbox_mode = "danger-full-access"
model_supports_reasoning_summaries = true

[model_providers.Capybara]
name = "capybara"
base_url = "https://ai.bututrip.fun/v1"
wire_api = "responses"
requires_openai_auth = true

`auth.json`

json

{
  "OPENAI_API_KEY": "把你在卡皮巴拉创建的 Codex 密钥粘贴在这里"
}

第三步：首次启动

1. 打开应用

启动 Codex 桌面应用。

2. 选择登录方式

启动后会让你选登录方式：

❌ Sign in with ChatGPT — 这是用 OpenAI 官方账号，不要选
✅ Sign in with API Key — 选这个，使用我们配置的卡皮巴拉密钥

💡 关于 API Key 登录

用 API Key 登录后，部分官方专属功能（如 Cloud threads 云端会话）可能不可用，但核心的 AI 编程功能完整可用。

如果界面要求你输入 Key，把卡皮巴拉的 Codex 密钥粘进去即可。

3. 选择项目目录

登录后，应用会让你选一个项目目录作为工作区。选你想让 Codex 处理代码的文件夹即可，比如某个 GitHub 仓库的根目录。

4. 确认在 Local 模式下

发送消息前，确认顶部的运行模式选的是 Local（本地），而不是 Cloud（云端）。Cloud 模式需要 ChatGPT 账号。

5. 发送第一条消息

试着发一条消息验证：

请简单介绍一下这个项目的代码结构

收到回复就说明配置成功了 🎉。

桌面应用 vs CLI 怎么选

维度	桌面应用	CLI
使用门槛	低，图形界面	中，需要适应命令行
可视化	强，能看到代码 diff、文件树	弱，纯文本交互
集成 IDE	独立窗口	可嵌进 VS Code 的终端
远程使用	不方便	友好（SSH 进服务器即可用）
资源占用	较高（Electron 应用）	极低
自动化脚本	不适合	适合

新手或习惯图形界面 → 桌面应用，老开发者或服务器场景 → CLI。两者可以并存。

常见问题

桌面应用没有改 Base URL 的设置项怎么办？

Codex 桌面应用本身没有图形化的 API 配置入口，必须通过 ~/.codex/config.toml 配置文件来指定中转服务。这就是为什么本文要求你先写配置文件，再启动应用。

装好了 App 但启动后还是连官方？

按以下顺序检查：

完全退出应用（macOS 不要只关窗口，要 Cmd+Q 退出；Windows 在系统托盘退出）
确认 ~/.codex/config.toml 文件存在且 model_provider = "Capybara"
确认 ~/.codex/auth.json 里的 Key 是有效的卡皮巴拉 Codex 密钥
确认 base_url 末尾有 /v1：https://ai.bututrip.fun/v1
重新启动应用

Mac 提示「来自身份不明的开发者」打不开怎么办？

如果是从官方 chatgpt.com/codex 下载的，理论上不会出现。如果出现：

进入 系统设置 → 隐私与安全性 → 安全性
找到关于 Codex 的提示，点 「仍要打开」

桌面应用和 CLI 能同时用吗？

可以，并且推荐这样用。两者共享同一份 ~/.codex/config.toml 和 auth.json，配置一次双享。

想切换到不同提供商怎么办？

最方便的方式：用 CC-Switch 管理多套配置，一键切换。CC-Switch 切换后，桌面应用和 CLI 都会用新的配置。

切换后记得完全退出并重启桌面应用，才能读到新配置。

还有其他问题？

参考常见问题排查。

Claude Code

Codex CLI