桌面应用与界面

CLI 适合习惯终端的人，但很多日常任务——同时盯几个线程、逐块审阅改动、开个内置终端跑测试——在图形界面里更顺手。Codex 的桌面应用就是为这类场景做的：一个窗口里管理多个项目、多个并行任务，每个任务的对话、改动、命令输出都能单独查看。

这一页讲清楚：桌面应用怎么装、怎么打开项目、界面每块区域是干什么的、三种运行方式怎么选、改动怎么审，以及它和 CLI 共用配置这件事（所以 接入 HiveGPT 的配置在桌面端同样生效）。

名称变化

2026 年 7 月 10 日之后，独立的 Codex 桌面应用并入了 ChatGPT 桌面端，成为其中的「Codex」功能。旧版 Codex.app 和新版 ChatGPT 桌面端在 CLI 看来是同一个应用（codex app 两种都能识别并打开）。下文统称「桌面应用」，界面文字以你安装的版本为准。

安装

平台	获取方式	说明
macOS	官网下载 dmg，或在终端运行 codex app	Apple Silicon 和 Intel 机型都有安装包
Windows	官网或 Microsoft Store	codex app 会打开商店安装页
Linux	以官方说明为准	CLI 在 Linux 上会提示桌面端的获取方式

已经装了 CLI 的话，最省事的方式是在项目目录里运行：

cd ~/code/my-project
codex app            # 打开桌面应用并定位到当前目录；没装会先引导安装
codex app ~/code/api # 也可以直接指定目录

在 macOS 上，codex app 找不到应用时会自动下载官方 dmg，校验 OpenAI 的签名后装进「应用程序」文件夹；在 Windows 上会打开 Microsoft Store 的安装页。

反过来，在 CLI 会话里输入 /app，可以把当前会话转到桌面应用里继续（仅 macOS 和 Windows）。

登录与模型来源

桌面应用和 CLI、IDE 扩展读的是同一个 Codex 主目录（默认 ~/.codex，Windows 是 %USERPROFILE%\.codex）：

文件	作用	桌面端是否共用
config.toml	模型、服务地址、沙箱、MCP、Skills 等配置	共用，桌面端自己的界面设置也写在这里的 [desktop] 段
auth.json	登录凭据或 API Key	共用
sessions/	历史会话记录	共用，所以能在 CLI 和桌面端之间接着聊
AGENTS.md、skills/、rules/	全局指令、技能、命令规则	共用

这意味着两种用法：

• 用 ChatGPT 账号登录：第一次打开时选择用 ChatGPT 登录，按浏览器提示完成授权。本地任务、云端任务、GitHub 集成都可以用。
• 用第三方模型接口（比如 HiveGPT）：先按 接入 HiveGPT 生成 ~/.codex/config.toml 和 ~/.codex/auth.json，再打开桌面应用，本地任务就会走 HiveGPT 的 gpt-5.5。如果应用仍停在登录页，选择用 API Key 继续的入口（文案以应用为准）。

第三方 Key 不能用云端功能

用 API Key（包括 HiveGPT 的 Key）时，只有在你电脑上运行的任务可用。「云端」运行方式、chatgpt.com/codex 上的任务、GitHub 里的 @codex 都要求 ChatGPT 账号和对应套餐，详见 云端任务与 GitHub。

改了 config.toml 或 auth.json 之后，完全退出桌面应用再打开，然后新建一个线程，配置才能可靠生效；只在旧线程里继续聊可能还在用旧设置。

界面总览

不同版本的布局会微调，但大致分成三栏：

┌──────────────┬──────────────────────────────┬──────────────────┐
│ 左侧栏        │ 中间：对话与执行过程           │ 右侧面板（可收起） │
│ 新建线程      │  你的消息 / Codex 的计划        │ 改动审阅（diff）   │
│ 搜索          │  执行的命令及输出               │ 终端              │
│ 插件 / 技能   │  修改的文件列表                 │ 浏览器 / 文件预览  │
│ 自动化        │                              │                  │
│ 项目 → 线程   │ ┌──────────────────────────┐ │                  │
│ 设置          │ │ 输入框  @文件 +附件 模型 权限 │ │                  │
└──────────────┴─┴──────────────────────────┴─┴──────────────────┘

左侧栏：项目和线程

• 项目：绑定你电脑上的一个文件夹（通常是一个 Git 仓库）。Codex 在这个项目里的读写、命令都以这个文件夹为工作目录。添加项目就是选一个文件夹。
• 线程：项目下的一次次任务对话。一个项目可以同时开很多线程，每个线程独立运行，互不打断。线程可以重命名、归档，归档后在设置里能找回。
• 不绑定项目的对话：适合问概念、写一段命令，不需要读你的代码。
• 搜索：按关键词找历史线程。
• 插件 / 技能：给 Codex 加能力，比如 GitHub、浏览器、电脑操控、文档处理。技能的写法见 Skills，外部工具接入见 MCP。
• 自动化：定时让 Codex 在某个项目里跑任务，后面单独说。

中间：对话区

你发出任务后，这里会依次出现 Codex 的计划、它读了哪些文件、执行了什么命令（可以展开看输出）、改了哪些文件，最后是总结。执行过程中可以继续输入补充要求，不必等它停下。

输入框里常用的几样：

操作	用途
输入 @	引用项目里的文件，或调用已安装的插件
+ 或拖拽	附加图片、截图、文件
模型选择	切换模型和推理强度，HiveGPT 默认是 gpt-5.5，其他可选项以列表为准
权限 / 审批	选择只读、默认（可改工作区、联网和越界要批准）、完全访问
运行方式	本地 / Worktree / 云端，见下一节
语音	口述任务

权限选项和 CLI 的 /permissions 是同一套概念：「默认」相当于 workspace-write 沙箱加按需审批，「完全访问」相当于不设沙箱也不问。各档含义见 沙箱与审批。

右侧面板

右上角的按钮可以展开右侧面板，常用的有：

• 改动审阅：以 diff 显示文件变化，可以只看最近一轮的改动，也可以看整个工作区相对 Git 的全部改动。
• 终端：每个项目一个内置终端，自己跑 npm test、git log 不用切窗口。
• 浏览器 / 预览：打开本地开发服务器的页面、预览生成的图片、Markdown、PDF 等。前端调试时可以让 Codex 直接在内置浏览器里看页面，详见 电脑操控。

三种运行方式

新建线程时，在输入框附近选择任务在哪里跑：

方式	改动落在哪里	适合	需要
本地（Local）	直接改项目文件夹	小改动、需要你马上看到效果	无
Worktree	项目的一个 Git worktree，独立分支	同时让多个线程改同一个仓库；不想弄乱当前工作区	项目是 Git 仓库
云端（Cloud）	OpenAI 的云端容器，结果是 diff 或 PR	长任务、并行多次尝试、电脑可以关	ChatGPT 账号，仓库在 GitHub

Worktree 是并行开发的关键：每个线程拿到自己的目录和分支，三个线程同时改同一个仓库也不会互相覆盖。完成后可以在应用里提交、推 PR，或者把改动交回本地工作区继续测试。原理和命令行用法见 Worktree 与并行任务。

Worktree 里为什么缺依赖？

Git worktree 只包含被 Git 跟踪的文件。node_modules、.env、构建产物这类被 .gitignore 忽略的东西不会出现在新 worktree 里。桌面应用支持为项目配置「本地环境」：新建 worktree 时自动执行的初始化脚本（比如 pnpm install），以及放在顶部的常用操作按钮（比如「启动开发服务器」「跑测试」）。具体入口在项目设置里，以应用为准。

审阅和提交改动

桌面应用最实用的地方是审阅流程。一个典型的循环：

1. 在线程里描述任务，等 Codex 跑完。
2. 打开右侧的改动审阅，先切到「最近一轮」看它这次改了什么。
3. 对不满意的代码块可以直接撤销，或者在那一行写评论，然后让 Codex 按评论再改。
4. 在内置终端里自己跑一遍测试。
5. 满意后在应用里提交、推送，或者创建 PR（需要本机已配置好 Git 和 GitHub 凭据）。

几条习惯：

• 每轮只给一个目标，审阅时才看得过来。
• 改动多的时候，先让 Codex 用一两句话说明每个文件为什么改，再看 diff。
• 不要跳过审阅直接提交，尤其是在「完全访问」权限下跑出来的结果。

自动化

自动化让 Codex 按计划在某个项目里定时跑任务，比如每天早上总结昨天的提交、每周检查依赖更新、定期跑一遍测试并尝试修复失败用例。创建时设置：

• 在哪个项目里跑、用什么提示词
• 执行频率
• 用什么权限（建议只读或默认，不要给完全访问）

有结果的运行会出现在收件箱里等你查看，没有发现的会自动归档。自动化依赖桌面应用在运行、项目文件夹在磁盘上，电脑睡眠或应用关闭时不会执行。

与 CLI 搭配使用

桌面应用和 CLI 不是二选一：

场景	更顺手的形态
同时跑多个任务、需要逐块审阅	桌面应用
SSH 到服务器、在容器里工作	CLI
写脚本、CI 里自动跑	codex exec，见 非交互模式与 CI/CD
边写代码边问	IDE 扩展

因为配置和会话共用，你可以在 CLI 里开始一个任务，用 /app 转到桌面应用里审阅；也可以在终端里用 codex resume 接着桌面应用里的会话聊。

常见问题

打开项目后 Codex 说没有权限改文件？ 检查输入框旁的权限选项是不是「只读」。另外，Codex 对项目有「信任」的概念：未被信任的目录里，.codex/config.toml 这类项目级配置会被加载但不生效。如果项目级配置没起作用，先确认这个项目已被标记为信任（CLI 首次在该目录启动时会询问）。

桌面端用的模型和 CLI 不一样？ 两者读同一个 config.toml，但线程里手动切换过的模型只对该线程生效。新建线程看看；也可以检查是否有 -p 指定的配置档或项目级 .codex/config.toml 覆盖了设置。

怎么看版本？ CLI 用 codex --version，桌面应用在菜单的「关于」里看。两边版本差太多时，新功能可能只在其中一边出现，更新到最新即可。

小结

• 桌面应用现为 ChatGPT 桌面端里的 Codex 功能，codex app 可以直接打开或安装它。
• 它和 CLI、IDE 扩展共用 ~/.codex 下的配置、凭据和会话，HiveGPT 的接入配置同样生效。
• 本地、Worktree、云端三种运行方式里，云端需要 ChatGPT 账号，第三方 Key 只能跑本地和 Worktree。
• 多线程并行时用 Worktree 隔离；每轮改动都在右侧审阅面板看过再提交。
• 自动化适合周期性的只读或低风险任务，依赖桌面应用保持运行。

下一步：IDE 扩展