Codex App 深度指南：多智能体的指挥中心

Codex App 是专为多智能体并行工作设计的桌面客户端。与 CLI 的单线程交互不同，App 让你在一个窗口内同时管理多个项目、运行多条线程、配置后台自动化，并通过内置 Git 工具完成从编码到 PR 的完整闭环。

本篇将全面拆解 App 的每一项核心功能，帮助你把 Codex 从 "一个聊天窗口" 升级为 "编码团队的指挥中心"。

一、多项目管理：一个窗口，多个 Codebase

Codex App 支持在同一个窗口内添加多个项目（Project），每个项目对应一个代码仓库或目录。

项目管理要点

如果你用过 CLI，可以这样类比：一个 App 项目 ≈ 在某个目录下启动一次 codex 会话，但 App 允许你同时打开多个这样的"会话"。

二、线程模式：Local / Worktree / Cloud

每条线程（Thread）在创建时需要选择运行模式，这是 App 最核心的工作流决策之一：

模式选择决策树

三、Worktree 工作流：Git Worktree 隔离并行任务

Worktree 是 App 实现多智能体并行的基石。它利用 Git 的 worktree 机制为每条线程创建一份独立的文件副本，所有变更互不干扰。

3.1 Worktree 基本概念

3.2 创建 Worktree 线程

3.3 两种 Worktree 工作路径

路径 A：完全在 Worktree 中完成

适合 worktree 中已安装好依赖（通过 Local Environment setup script），可以直接验证和提交：

1. Codex 在 worktree 中完成编码
2. 点击 Create branch here 将 detached HEAD 转为命名分支
3. Commit → Push → 在 App 内直接创建 PR
4. 使用 Open 按钮在 IDE 中打开 worktree 目录进一步检查

路径 B：Handoff 回 Local

适合需要在你日常的 IDE 环境和开发服务器中验证变更：

1. Codex 在 worktree 中完成编码
2. 点击线程头部的 Hand off → 移动到 Local
3. 在你的本地 IDE 和开发环境中审查、测试
4. 如果需要 Codex 继续后台工作，可以再次 Hand off 回 Worktree

3.4 何时用 Worktree vs Local

3.5 多智能体并行编码最佳实践

1. 每条线程一个聚焦任务 — 不要在一条线程里塞多个不相关的需求
2. 为并行线程选择 Worktree — 确保互不干扰
3. 善用 Local Environment — 为 worktree 配置 setup script，确保依赖自动安装
4. 定期清理 — Archive 完成的线程，Codex 会自动清理对应的 worktree
5. 用 Skills 统一规范 — 多条线程引用相同的 Skill 可确保编码风格一致

3.6 Worktree 磁盘管理

Worktree 默认存放在 $CODEX_HOME/worktrees，每个 worktree 包含完整的文件副本和依赖，会占用不少磁盘空间。

• 自动清理：Codex 默认保留最近 15 个 Codex-managed worktree
• 不会被自动删除的：pinned 线程的 worktree、运行中的线程、permanent worktree
• 快照恢复：删除前 Codex 会保存快照，重新打开线程时可选择恢复
• 调整上限：在 Settings 中修改保留数量或关闭自动删除

四、内置 Git 工具：从 Diff 到 PR

App 内置了完整的 Git 工作流，无需切换到终端或外部 Git 客户端。

4.1 Diff 面板

通过 Cmd+Option+B 切换 Diff 面板，它反映的是 Git 仓库的真实状态——不仅是 Codex 的变更，还包括你自己手动修改的文件和所有未提交变更。

查看范围可切换为：

• Uncommitted changes（默认）— 所有未提交的变更
• All branch changes — 与 base branch 的完整 diff
• Last turn changes — 仅最近一轮 Codex 的变更
• Unstaged / Staged — 在 Local 模式下可切换

4.2 内联评论（Inline Comments）

直接在 Diff 中对特定行留下反馈，Codex 能精准理解上下文：

1. 打开 Review 面板
2. 悬停在目标行 → 点击出现的 + 按钮
3. 写下你的修改意见并提交
4. 完成所有评论后，回到线程发送消息（如 "Address the inline comments"）

4.3 Stage / Revert

在 Review 面板中可以在三个粒度上操作：

4.4 Commit、Push 与创建 PR

对于 Local 和 Worktree 线程，你可以直接在 App 内：

• Commit 已暂存的变更
• Push 到远程仓库
• Create Pull Request — 直接在 GitHub 上创建 PR

五、Automations（自动化）

Automations 是 App 独有的功能——让 Codex 在后台定时或按触发条件自动执行任务，结果放入 Inbox 供你审阅。

5.1 工作原理

• 自动化在 Codex App 运行时后台执行（App 需要保持打开）
• 对于 Git 仓库，可选择在 Local 或 Worktree 中运行
• 结果分为两类：有发现（进入 Triage 收件箱）或无发现（自动归档）
• 可自定义模型和推理力度（reasoning effort），或使用默认值

5.2 自动化 + Skills 组合

使用 $skill-name 语法在自动化中显式调用 Skill：

Run $recent-code-bugfix on recent commits and report findings.

这使得自动化可以复用团队共享的 Skill 定义，保持一致性。

5.3 常见自动化场景

5.4 自动化安全模型

自动化使用你的默认沙箱设置，需要特别注意权限：

自动化默认使用 approval_policy = "never"（除非管理员通过 requirements.toml 禁止）。

5.5 测试与维护建议

1. 先手动测试 — 在普通线程中运行自动化的 Prompt，确认效果
2. 审查前几次输出 — 刚调度的自动化，前几次运行要仔细检查
3. 及时归档 — Archive 不需要的运行记录，若使用 Worktree 模式会同时清理磁盘
4. 避免过高频率 — 频繁调度 + Worktree 模式 = 大量磁盘占用

六、Review 模式：App 内的代码审查

App 的 Review 功能基于 Git 仓库，提供可视化的代码审查体验。

6.1 触发方式

• 在 Composer 中输入 /review
• 或直接打开 Review 面板查看 Diff

6.2 审查范围

6.3 审查工作流

1. /review 触发 Codex 自动审查代码
2. Codex 的审查意见以内联评论形式显示在 Diff 面板中
3. 你可以对具体行添加自己的评论，补充修改要求
4. 回到线程发送 "Address the inline comments" 让 Codex 修改
5. 满意后 Stage → Commit → Push → Create PR

七、Local Environments：环境配置即代码

Local Environments 解决了一个关键问题：Worktree 是全新目录，缺少 node_modules 等未被 Git 追踪的依赖。

7.1 Setup Scripts（启动脚本）

当 Codex 创建新 Worktree 时自动执行的脚本，用于安装依赖和构建：

npm install
npm run build

• 配置路径：项目根目录 .codex/ 文件夹
• 可区分平台：分别为 macOS / Windows / Linux 定义不同脚本
• 可提交到 Git：团队成员共享相同的环境配置

7.2 Actions（快捷操作）

Actions 定义常用任务，显示为 App 顶栏的快捷按钮：

• Actions 在 App 的集成终端中执行
• 同样支持平台特定脚本
• 每个 Action 可选择关联图标以便识别

八、Commands：键盘快捷键与斜杠命令

8.1 键盘快捷键

8.2 Slash Commands

在 Composer 中输入 / 调出命令列表：

此外，已启用的 Skills 也会出现在斜杠命令列表中。你也可以用 $skill-name 语法直接调用 Skill。

8.3 Deeplinks

Codex App 注册了 codex:// URL scheme，支持从外部直接打开特定功能：

九、集成终端、浮动窗口、语音输入与 IDE 同步

9.1 集成终端

每条线程包含一个内置终端，作用域限定在当前项目或 Worktree 目录：

• 切换：Cmd+J 或顶栏终端图标
• 清空：Ctrl+L
• Codex 可读取终端输出 — 它能查看运行中的 dev server 状态或失败的构建日志

常见用法：

git status
git pull --rebase
npm test
npm run lint

9.2 浮动窗口（Pop-out Window）

将活跃的线程弹出为独立浮动窗口，可以拖到屏幕任意位置：

• 非常适合前端开发：浮动窗口放在浏览器旁边，实时迭代
• 支持 Always on top — 始终置顶显示

9.3 语音输入

按住 Ctrl+M（Composer 可见时）开始语音输入，松开后 Codex 自动转录。你可以编辑转录文本后再发送。

9.4 IDE 同步

如果你同时安装了 Codex IDE Extension，且 App 和 IDE 在同一个项目中：

• 自动同步 — 两端自动建立连接
• Auto context — App 自动追踪你在 IDE 中正在查看的文件，可以用 "What's this file about?" 这样的模糊引用
• 线程互通 — App 中的线程在 IDE Extension 中可见，反之亦然
• 开关控制 — 如果不确定 App 是否包含了 IDE 上下文，可以关闭 Auto context 后重新提问对比结果

十、设置详解

通过 Cmd+, 打开 Settings 面板。

10.1 设置分类总览

10.2 审批与沙箱

10.3 防休眠

由于 Codex 任务可能运行较长时间，Settings 中提供了 "Prevent sleep while running" 开关——启用后 App 会阻止电脑进入休眠状态，确保后台线程和自动化不被中断。

十一、其他实用功能

图片输入

• 拖拽图片到 Composer 作为上下文（按住 Shift 拖入）
• 可以让 Codex 查看系统截图——结合截图工具，Codex 能验证前端 UI 的输出效果

Web 搜索

Codex 内置 Web 搜索工具：

• Local 任务：默认使用搜索缓存
• Full access 沙箱：默认使用实时搜索结果
• 可在 config.toml 中禁用或切换搜索模式

MCP 支持

App、CLI、IDE Extension 共享 MCP 配置。在任一端配置的 MCP 服务器自动对其他端生效（配置存储在 config.toml 中）。

Windows 原生沙箱

在 Windows 上，Codex 可以原生运行在 PowerShell 中，使用 Windows 原生沙箱，无需 WSL 或虚拟机。

十二、实战工作流：从 Issue 到 PR 的完整闭环

以下是一个典型的多智能体并行工作流，展示如何利用 App 的各项功能完成一个真实的开发任务。

场景：同时修复 Bug 和开发新功能

Fix the authentication timeout bug in src/auth/session.ts.
The session expires after 5 minutes instead of 30.
Run the auth tests to verify the fix.

Implement the user profile avatar upload feature.
Add a new endpoint POST /api/users/avatar.
Include file validation (max 5MB, jpg/png only).

十三、App 功能速查