Orca Parallel Agent Workflow Tutorial: Use Git Worktree to run Codex and Claude Code simultaneously

多个 Agent 同时改一个仓库，最怕的不是速度不够，而是它们相互覆盖文件、污染未提交改动，最后很难判断哪一份结果可合并。Orca 的做法是为每个 Agent 分配独立的 Git worktree：同一个仓库可以并行运行 Codex、Claude Code 或其他终端 Agent，完成后再比较 diff、选择并合并结果。Orca 官方仓库

它不是另一个模型，也不会替代 Codex 或 Claude Code；更准确地说，它是给多个 CLI Agent 加上一层工作区、任务和结果管理界面。适合需要并行探索方案、但又希望保留 Git 隔离边界的开发者。

Orca 适合什么任务

Orca 最适合“目标相同、实现路径可比较”的任务，例如：

让两个 Agent 分别实现同一个接口，再比较测试、可读性和改动范围。
一边排查 bug，另一边补测试或阅读相关模块。
同时尝试保守修复与重构方案，最后只合并其中一个。
把前端、后端、文档拆成互不重叠的子任务并行推进。

不适合直接拆开的情况也很常见：多个 Agent 同时改同一个核心文件、需要共享未提交状态的调试过程，或需求本身还没有明确。这时先用一个 Agent 梳理计划，通常比并行启动五个窗口更省时间。

工作原理：每个 Agent 一棵独立工作树

Git worktree 允许一个仓库同时检出多个分支到不同目录。Orca 在此基础上为 Agent 创建和管理这些独立目录：每个 Agent 都有自己的文件改动、终端会话和分支上下文，不会直接覆盖主工作目录。

官方 README 描述的典型流程是：把同一个提示分发给多个 Agent，每个 Agent 在隔离 worktree 中完成任务，然后比较结果并合并胜出的实现。Parallel Worktrees 说明

可以把关系理解为：

层级	负责什么
Codex / Claude Code	理解任务、修改代码、执行测试
Git worktree	隔离每个方案的文件和分支改动
Orca	创建工作树、启动 Agent、集中查看会话与 diff
你	拆分任务、审查结果、决定合并哪个方案

开始前的仓库准备

并行之前先把主目录收拾干净。worktree 能隔离新分支的文件改动，却不能替你判断主目录里哪些未提交变更应该保留。

1
2
3
4


git status
git fetch --all --prune
git switch main
git pull --ff-only

如果 git status 不是干净状态，先提交、暂存或明确保留当前改动。随后为不同方案建立清晰的分支命名，例如：

1
2
3


agent/fix-login-codex
agent/fix-login-claude
agent/add-login-tests

Orca 支持 Windows、macOS 和 Linux 桌面端；安装包和当前版本以官方发布页为准。它可以运行任何能在终端执行的 Agent，因此还要确认本机已经完成 Codex、Claude Code 或你计划使用的 CLI 的登录和基础配置。

一个可复用的并行拆分方式

以“登录偶发失败”为例，不要给三个 Agent 都发送“修复登录 bug”。更好的拆分是把交付物写清楚：

1
2
3


Agent A：定位请求重试与 token 刷新路径；只提交最小修复，并补充复现步骤。
Agent B：不改业务逻辑；为登录失败、过期 token、网络超时补自动化测试。
Agent C：审查最近登录相关改动，给出根因假设、风险文件和建议，不直接修改代码。

这样三条工作树的输出可以直接比较：A 提供候选修复，B 提供回归保护，C 提供独立审查。即使最终只采用 A 的修改，B 和 C 的结果仍能帮助验证方向。

对于同一个功能的多方案竞赛，也应限制范围：要求每个 Agent 只改指定模块、运行相同测试命令、在最终说明中列出修改文件和未解决问题。没有共同的验收标准，多个 Agent 的“完成”很难横向比较。

在 Orca 中启动并行 worktree

具体界面会随版本变化，但操作顺序通常如下：

打开一个已初始化 Git 的仓库，确认基线分支和主目录没有意外改动。
为每个子任务创建独立 worktree 或让 Orca 从任务创建工作树。
分别选择 Codex、Claude Code 等本机可用 Agent，给出不重叠的任务说明和验收命令。
让 Agent 在自己的 worktree 中执行；不要在主目录同时手动修改同一批文件。
完成后查看每棵工作树的 diff、测试输出和提交记录，再决定保留、修改或丢弃。

Orca 还提供终端分屏、diff 行内评论、文件拖放给 Agent，以及通过 CLI 管理工作树的能力；例如其文档列出了 orca worktree create、snapshot 等工作流命令。功能入口以当前版本文档为准。Orca CLI 介绍

如何合并结果，避免把三个方案混在一起

最安全的顺序是先审查、后合并：

1
2
3
4
5
6
7


# 在主工作树中查看某个候选分支
git diff main...agent/fix-login-codex
git log --oneline main..agent/fix-login-codex

# 确认测试和改动范围后再合并
git switch main
git merge --no-ff agent/fix-login-codex

如果测试工作树和修复工作树都值得保留，先合并测试，再合并修复，或用 git cherry-pick 挑选单独提交。不要因为它们都由 Agent 生成，就直接把全部 worktree 一次性 merge；重复的依赖升级、格式化改动和同文件重构最容易在这里引入冲突。

合并前至少检查四项：

改动是否只覆盖了任务范围内的文件。
测试命令是否实际运行且结果可复现。
是否包含密钥、生成文件、大型锁文件或无关格式化。
两个候选方案是否改了同一段业务逻辑；若是，保留一个作为主方案，另一个只作为参考。

常见问题

Orca 会替我购买或共享 Codex、Claude Code 的额度吗？

不会。Orca 的定位是编排终端 Agent；你仍使用自己已有的 Agent 订阅、账号和本机登录状态。多开 Agent 也可能更快消耗对应产品的用量额度。

多个 Agent 可以修改同一个文件吗？

可以，因为它们位于不同 worktree；但后续合并会产生竞争。若同一个文件不可避免地要改，最好指定一个主实现 Agent，其他 Agent 只做审查、测试或提出补丁建议。

没有 Git 仓库能用吗？

Orca 能运行终端 Agent，但并行 worktree 的隔离和可控合并依赖 Git。对重要项目，先初始化仓库并建立可回滚的基线，再开始并行任务。

Orca 与直接开多个终端有什么区别？

手动开多个终端也能并行，但你需要自己创建工作树、记住分支、追踪会话和对比结果。Orca 把这些步骤放到同一界面，重点是降低并行 Agent 的管理成本，而不是改变 Agent 本身的能力。

小结

Orca 的实用之处在于把“并行试错”变成可审查的 Git 工作流：每个 Agent 在独立 worktree 中工作，结果用 diff、测试和分支提交来比较。先把任务拆到互不干扰，再只合并经过审查的候选分支，才能让 Codex、Claude Code 的并行能力真正服务于交付，而不是制造更多冲突。