Codex 桌面应用

Codex App 是官方推荐的桌面客户端，提供完整功能和流畅的多项目并行体验。

下载与安装

Codex App 支持 macOS（Apple Silicon）和 Windows。

下载地址

下载地址：https://chatgpt.com/codex

平台下载方式
macOS官网下载或 Homebrew
Windows官网下载安装包

Homebrew 安装

# macOS 使用 Homebrew
brew install --cask codex

首次使用

安装完成后，按以下步骤开始：

  1. 打开 Codex App
  2. 使用 ChatGPT 账号或 OpenAI API Key 登录
  3. 选择一个项目文件夹
  4. 发送第一条 Prompt 开始使用

如果使用 API Key 登录，部分云端功能可能不可用。

界面结构

Codex App 主要包含以下区域：

区域功能
项目侧边栏管理多个项目，快速切换
线程列表显示所有会话，支持筛选和归档
审查面板查看 Codex 所做的文件更改
终端面板每个线程独立的内置终端
技能选择器浏览和启用自定义技能

三种运行模式

每个线程可以选择三种运行模式：

模式说明适用场景
Local在本地项目目录工作日常开发、直接查看结果
Worktree在独立 Git worktree 中工作隔离变更、并行开发
Cloud在云端隔离环境运行远程委派、并行处理

模式选择

在创建新线程时，在输入框下方选择模式：

  • Local：直接在当前目录工作，变更立即可见
  • Worktree：创建独立分支，完成后可合并到 Local
  • Cloud：任务在云端运行，结果通过 PR 或报告呈现

Worktree 模式使用 Git worktree 技术，允许同时在不同分支工作。

Review 模式

Review 模式让你查看和审批 Codex 所做的更改。

审查面板功能

功能说明
Diff 查看显示所有文件变更的详细对比
内联评论在特定代码行添加评论
Chunk 操作按代码块选择接受或拒绝
整体提交创建 Git commit 或推送更改

切换审查视图

审查面板支持两种视图：

  • 所有更改：显示项目的 Git 状态，包括非 Codex 的更改
  • Last turn 更改：只显示最近一轮 Codex 的更改

审查操作

# 快捷键操作
Cmd + Option + B    # 切换审查面板
Cmd + Shift + P     # 打开命令菜单

# 审查流程
1. 查看文件变更
2. 点击代码块接受/拒绝
3. 添加评论说明
4. 提交或推送

Automations（自动化）

Automations 让你安排 Codex 定期在后台运行任务。

使用前提

  • Codex App 正在运行
  • 选择的项目在磁盘上可用

创建自动化

  1. 打开侧边栏 Automations 面板
  2. 点击 "New Automation"
  3. 配置触发频率和任务描述
  4. 设置沙箱模式

自动化示例

任务描述
技能自动创建扫描会话文件，更新技能使其更有效
每日简报分析最近提交，生成变更摘要
Bug 监控检查 telemetry 错误，尝试自动修复

自动化任务结果会添加到 Triage 收件箱，无结果时自动归档。

Worktrees 管理

Codex App 内置 Git worktree 支持。

Worktree 优势

  • 并行处理多个任务而不互相干扰
  • 保持主分支干净
  • 后台运行任务时专注前台工作

Handoff 流程

Handoff 允许在 Local 和 Worktree 之间切换线程：

  1. 在 Worktree 中完成任务
  2. 创建 commit 和 PR
  3. 选择 Handoff 到 Local 继续测试

Worktree 只继承 Git 中的文件，.gitignore 中的文件不会随线程移动。

本地环境配置

通过 Local Environments 定义 worktree 的设置脚本和常用操作。

设置脚本

创建新 worktree 时自动运行的脚本：

设置脚本示例

# .codex/setup.sh
npm install        # 安装依赖
npm run build      # 构建项目

Actions（操作）

定义常用任务，在顶部操作栏快速访问：

Action说明
启动开发服务器运行 npm run dev
执行测试运行测试套件
代码格式化运行 prettier

快捷键

快捷键功能
Cmd + Shift + P命令菜单
Cmd + N新建线程
Cmd + Shift + [ / ]切换线程
Cmd + Option + B切换审查面板
Cmd + J切换终端
Ctrl + M语音输入
Cmd + O添加项目

常见问题

Q: App 与 CLI/IDE 如何同步？

当在同一项目中使用 App 和 IDE 扩展时，它们会自动同步 Auto Context 和活跃线程。

Q: 如何找到归档的线程？

在 Settings 中查看 Archived Threads，选择 Unarchive 恢复。

Q: Worktree 代码与本地不同？

Worktree 只继承 Git 中的文件。需要设置脚本安装依赖和构建。

Q: App 和 CLI 版本不同导致功能差异？

检查版本：CLI 用 `codex --version`，App 用菜单 About。