orca

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Orca — Agent Orchestrator

Orca — Agent编排器

One-time setup: see references/SETUP.md if orca is not already on your PATH.

You are the orchestrator. Use the

orca

CLI below. You never need tmux knowledge.

一次性设置：如果orca未在你的PATH中，请查看references/SETUP.md。

你是编排器，请使用下方的

orca

CLI，无需掌握tmux相关知识。

Identify yourself

确认你的身份

Before using Orca, determine which agent you are and jump to your section:

You are…	Jump to	`--spawned-by`
OpenClaw	OpenClaw instructions	`openclaw`
Claude Code	Claude Code instructions	`$ORCA_WORKER_NAME` (if set), or `self` (if L0)
Codex	Codex instructions	`$ORCA_WORKER_NAME` (if set), or `self` (if L0)
Cursor	Cursor instructions	`$ORCA_WORKER_NAME` (if set), or `self` (if L0)

使用Orca前，请确定你是哪类Agent并跳至对应章节：

你是…	跳至	`--spawned-by`
OpenClaw	OpenClaw说明	`openclaw`
Claude Code	Claude Code说明	`$ORCA_WORKER_NAME` （若已设置），或 `self` （若为L0）
Codex	Codex说明	`$ORCA_WORKER_NAME` （若已设置），或 `self` （若为L0）
Cursor	Cursor说明	`$ORCA_WORKER_NAME` （若已设置），或 `self` （若为L0）

--spawned-by

rules

--spawned-by

规则

Every

orca spawn

must include

--spawned-by

so the daemon knows parent → child links and where to route notifications.

OpenClaw (L0 orchestrator):

```
--spawned-by openclaw
```
— OpenClaw is the only true L0 orchestrator. It lives outside tmux and receives notifications via
```
openclaw system event
```
.

cc / cx / cu (always in tmux):

Check
```
ORCA_WORKER_NAME
```
in your environment.
- If set: you are a worker —
```
--spawned-by "$ORCA_WORKER_NAME"
```
  (the plain name from
```
orca list
```
  , e.g.
```
fin
```
  ,
```
mud
```
  ), NOT the emoji label, NOT
```
openclaw
```
  .
- If not set: you are the L0 orchestrator —
```
--spawned-by self
```
  . Orca auto-detects or generates your L0 pane name.

Workers spawning sub-workers:

Same rule:

--spawned-by <your-worker-name>

from

ORCA_WORKER_NAME

orca list

每次执行

orca spawn

必须包含

--spawned-by

参数，这样守护进程才能知晓父→子关联，并确定通知路由。

OpenClaw（L0编排器）：

```
--spawned-by openclaw
```
—— OpenClaw是唯一真正的L0编排器，它运行在tmux外部，通过
```
openclaw system event
```
接收通知。

cc / cx / cu（始终运行在tmux中）：

检查环境变量中的
```
ORCA_WORKER_NAME
```
。
- 若已设置：你是工作进程 —— 使用
```
--spawned-by "$ORCA_WORKER_NAME"
```
  （即
```
orca list
```
  显示的纯名称，如
```
fin
```
  、
```
mud
```
  ），不要使用表情标签，不要使用
```
openclaw
```
  。
- 若未设置：你是L0编排器 —— 使用
```
--spawned-by self
```
  。Orca会自动检测或生成你的L0面板名称。

工作进程生成子工作进程：

规则相同：使用

--spawned-by <your-worker-name>

，即来自

ORCA_WORKER_NAME

或

orca list

的名称。

OpenClaw (L0 orchestrator)

OpenClaw（L0编排器）

You are an OpenClaw agent — the only true L0 orchestrator. Notifications go via

openclaw system event

, not tmux. The user only sees results if you route them explicitly via

openclaw message send

bash

orca spawn "fix the login bug" -b cc -d ~/proj --orchestrator openclaw \
  --reply-channel slack --reply-to C0AGZA4178Q --reply-thread 1234567890.123456 \
  --spawned-by openclaw

Flag	Required?	Notes
`--orchestrator openclaw`	Yes
`--spawned-by openclaw`	Yes	L0 orchestrator marker
`--reply-channel`	Yes	`slack` , `telegram` , `discord` , etc.
`--reply-to`	Yes	Channel ID or user ID for delivery
`--reply-thread`	No	Thread ID for threaded replies (Slack)
`--session-id`	No	OpenClaw session ID for scoped killall/gc
`--pane`	No	Not used — OpenClaw delivers via system events, not tmux panes

Without
--reply-channel
and
--reply-to
,
orca spawn
will fail. Set

ORCA_ALLOW_OPENCLAW_WITHOUT_REPLY=1

only for automation.

When you receive the completion event:

Run
```
orca logs <name>
```
to review the output
Summarize the results (include PR links if any)

Send the summary via

openclaw message send --channel <ch> --target <target> --message <summary>

Do NOT reply in-session — the user won't see that. Use
```
openclaw message send
```
.

你是OpenClaw Agent —— 唯一真正的L0编排器。通知通过

openclaw system event

发送，而非tmux。只有当你通过

openclaw message send

显式路由结果时，用户才能看到。

bash

orca spawn "fix the login bug" -b cc -d ~/proj --orchestrator openclaw \
  --reply-channel slack --reply-to C0AGZA4178Q --reply-thread 1234567890.123456 \
  --spawned-by openclaw

参数	是否必填？	说明
`--orchestrator openclaw`	是
`--spawned-by openclaw`	是	L0编排器标识
`--reply-channel`	是	支持 `slack` 、 `telegram` 、 `discord` 等
`--reply-to`	是	接收通知的频道ID或用户ID
`--reply-thread`	否	用于线程回复的线程ID（Slack）
`--session-id`	否	OpenClaw会话ID，用于限定killall/gc的作用范围
`--pane`	否	未使用 —— OpenClaw通过系统事件传递通知，而非tmux面板

**若未设置

--reply-channel

和

--reply-to

，

orca spawn

会执行失败。**仅在自动化场景下可设置

ORCA_ALLOW_OPENCLAW_WITHOUT_REPLY=1

。

收到完成事件时：

执行
```
orca logs <name>
```
查看输出
总结结果（若有PR链接请包含在内）

通过

openclaw message send --channel <ch> --target <target> --message <summary>

发送总结

不要在会话内回复 —— 用户看不到。请使用
```
openclaw message send
```
。

Claude Code (

cc

claude

)

Claude Code (

cc

claude

)

You must be running inside a tmux pane. Orca auto-detects your tmux pane for notification delivery — this does not work outside tmux. If a human launched you as the orchestrator, they must have started your session inside a tmux window first.

Check

ORCA_WORKER_NAME

in your environment:

If set: you are a worker —
```
--spawned-by "$ORCA_WORKER_NAME"
```
If not set: you are the L0 orchestrator —
```
--spawned-by self
```

bash

undefined

**你必须运行在tmux面板中。**Orca会自动检测你的tmux面板来传递通知 —— 在tmux外无法生效。如果人类将你作为编排器启动，他们必须先在tmux窗口中启动你的会话。

检查环境变量中的

ORCA_WORKER_NAME

：

若已设置：你是工作进程 —— 使用
```
--spawned-by "$ORCA_WORKER_NAME"
```
若未设置：你是L0编排器 —— 使用
```
--spawned-by self
```

bash

undefined

As a worker (ORCA_WORKER_NAME is set):

作为工作进程（ORCA_WORKER_NAME已设置）：

orca spawn "fix the login bug" -b cc -d ~/proj
--orchestrator cc --spawned-by "$ORCA_WORKER_NAME"

As L0 orchestrator (ORCA_WORKER_NAME is not set):

作为L0编排器（ORCA_WORKER_NAME未设置）：

orca spawn "fix the login bug" -b cc -d ~/proj
--orchestrator cc --spawned-by self


| Flag | Required? | Notes |
|------|-----------|-------|
| `--orchestrator cc` | **Yes** | Tells the daemon to send completions to your tmux pane |
| `--spawned-by <name>` | **Yes** | `$ORCA_WORKER_NAME` if set, or `self` if L0 |
| `--pane` | No | Auto-detected from your current tmux pane — omit unless overriding |
| `--depth` | No | Auto-resolved from your parent's depth |

---

orca spawn "fix the login bug" -b cc -d ~/proj
--orchestrator cc --spawned-by self


| 参数 | 是否必填？ | 说明 |
|------|-----------|-------|
| `--orchestrator cc` | **是** | 告知守护进程将完成通知发送至你的tmux面板 |
| `--spawned-by <name>` | **是** | 若已设置则为`$ORCA_WORKER_NAME`，若为L0则为`self` |
| `--pane` | 否 | 从当前tmux面板自动检测 —— 除非需要覆盖，否则无需填写 |
| `--depth` | 否 | 从父进程的深度自动解析 |

---

Codex (

cx

codex

)

Codex (

cx

codex

)

You must be running inside a tmux pane. If a human launched you as the orchestrator, they must have started your session inside a tmux window first.

Check

ORCA_WORKER_NAME

in your environment:

If set: you are a worker —
```
--spawned-by "$ORCA_WORKER_NAME"
```
If not set: you are the L0 orchestrator —
```
--spawned-by self
```

bash

undefined

**你必须运行在tmux面板中。**如果人类将你作为编排器启动，他们必须先在tmux窗口中启动你的会话。

检查环境变量中的

ORCA_WORKER_NAME

：

若已设置：你是工作进程 —— 使用
```
--spawned-by "$ORCA_WORKER_NAME"
```
若未设置：你是L0编排器 —— 使用
```
--spawned-by self
```

bash

undefined

As a worker (ORCA_WORKER_NAME is set):

作为工作进程（ORCA_WORKER_NAME已设置）：

orca spawn "add unit tests" -b cx -d ~/proj
--orchestrator cx --spawned-by "$ORCA_WORKER_NAME"

As L0 orchestrator (ORCA_WORKER_NAME is not set):

作为L0编排器（ORCA_WORKER_NAME未设置）：

orca spawn "add unit tests" -b cx -d ~/proj
--orchestrator cx --spawned-by self


| Flag | Required? | Notes |
|------|-----------|-------|
| `--orchestrator cx` | **Yes** | |
| `--spawned-by <name>` | **Yes** | `$ORCA_WORKER_NAME` if set, or `self` if L0 |
| `--pane` | No | Auto-detected |

---

orca spawn "add unit tests" -b cx -d ~/proj
--orchestrator cx --spawned-by self


| 参数 | 是否必填？ | 说明 |
|------|-----------|-------|
| `--orchestrator cx` | **是** | |
| `--spawned-by <name>` | **是** | 若已设置则为`$ORCA_WORKER_NAME`，若为L0则为`self` |
| `--pane` | 否 | 自动检测 |

---

Cursor (

cu

cursor

)

Cursor (

cu

cursor

)

You must be running inside a tmux pane. If a human launched you as the orchestrator, they must have started your session inside a tmux window first.

Check

ORCA_WORKER_NAME

in your environment:

If set: you are a worker —
```
--spawned-by "$ORCA_WORKER_NAME"
```
If not set: you are the L0 orchestrator —
```
--spawned-by self
```

bash

undefined

**你必须运行在tmux面板中。**如果人类将你作为编排器启动，他们必须先在tmux窗口中启动你的会话。

检查环境变量中的

ORCA_WORKER_NAME

：

若已设置：你是工作进程 —— 使用
```
--spawned-by "$ORCA_WORKER_NAME"
```
若未设置：你是L0编排器 —— 使用
```
--spawned-by self
```

bash

undefined

As a worker (ORCA_WORKER_NAME is set):

作为工作进程（ORCA_WORKER_NAME已设置）：

orca spawn "refactor auth" -b cu -d ~/proj
--orchestrator cu --spawned-by "$ORCA_WORKER_NAME"

As L0 orchestrator (ORCA_WORKER_NAME is not set):

作为L0编排器（ORCA_WORKER_NAME未设置）：

orca spawn "refactor auth" -b cu -d ~/proj
--orchestrator cu --spawned-by self


| Flag | Required? | Notes |
|------|-----------|-------|
| `--orchestrator cu` | **Yes** | |
| `--spawned-by <name>` | **Yes** | `$ORCA_WORKER_NAME` if set, or `self` if L0 |
| `--pane` | No | Auto-detected |

---

orca spawn "refactor auth" -b cu -d ~/proj
--orchestrator cu --spawned-by self


| 参数 | 是否必填？ | 说明 |
|------|-----------|-------|
| `--orchestrator cu` | **是** | |
| `--spawned-by <name>` | **是** | 若已设置则为`$ORCA_WORKER_NAME`，若为L0则为`self` |
| `--pane` | 否 | 自动检测 |

---

Sub-workers (worker spawning further workers)

子工作进程（工作进程生成更多子进程）

If you are a worker spawning sub-workers:

Always pass

--spawned-by <your-worker-name>

— the plain name from

ORCA_WORKER_NAME

orca list

(e.g.

fin

mud

), NOT the emoji label.

Only OpenClaw uses
```
--spawned-by openclaw
```
. If you are a worker, you must use your own worker name.
Orca fails closed if you omit
```
--spawned-by
```
or pass the wrong name.

bash

undefined

如果你是生成子工作进程的工作进程：

务必传递
```
--spawned-by <your-worker-name>
```
—— 即来自
```
ORCA_WORKER_NAME
```
或
```
orca list
```
的纯名称（如
```
fin
```
、
```
mud
```
），不要使用表情标签。
只有OpenClaw使用
```
--spawned-by openclaw
```
。如果你是工作进程，必须使用自己的工作进程名称。
若省略
```
--spawned-by
```
或传递错误名称，Orca会执行失败。

bash

undefined

Example: you are worker "fin" spawning sub-workers

示例：你是工作进程"fin"，正在生成子工作进程

orca spawn "sub-task A" -b cx -d ~/proj --orchestrator cc --spawned-by fin orca spawn "sub-task B" -b cc -d ~/proj --orchestrator cc --spawned-by fin


Max depth is 3 (`ORCA_MAX_DEPTH`). Max 10 running workers per orchestrator (`ORCA_MAX_WORKERS`). At max depth, do the work yourself.

---

orca spawn "sub-task A" -b cx -d ~/proj --orchestrator cc --spawned-by fin orca spawn "sub-task B" -b cc -d ~/proj --orchestrator cc --spawned-by fin


最大深度为3（`ORCA_MAX_DEPTH`）。每个编排器最多可运行10个工作进程（`ORCA_MAX_WORKERS`）。达到最大深度时，请自行完成任务。

---

Headless / scripts (not interactive agents)

无头模式 / 脚本（非交互式Agent）

To use

--orchestrator none

, set

ORCA_ALLOW_SPAWN_WITHOUT_ORCHESTRATOR=1

要使用

--orchestrator none

，请设置

ORCA_ALLOW_SPAWN_WITHOUT_ORCHESTRATOR=1

。

CLI reference

CLI参考

bash

orca spawn "fix the login bug" -b cc -d ~/proj --orchestrator openclaw --spawned-by openclaw
orca spawn "add unit tests" -b cx -d ~/proj --base-branch develop --orchestrator cx --spawned-by fin
orca spawn "refactor auth" -b cu -d ~/proj --orchestrator cu --spawned-by ace

orca list                                   # List all workers
orca status <name>                          # Detailed status (last output lines)
orca logs <name>                            # Full terminal output
orca steer <name> "also add tests"          # Send follow-up to a running worker
orca kill <name>                            # Kill a single worker (warns if not yours)
orca killall --mine                         # Kill YOUR workers only (safe, auto-detects pane)
orca killall --force                        # Kill ALL workers globally (requires human approval!)
orca gc --mine                              # Clean up YOUR done/dead workers
orca gc --force                             # Clean up ALL done/dead workers (requires human approval!)
orca daemon start|stop|status               # Daemon management (auto-starts on first spawn)
orca hooks install|uninstall                # Install/remove lifecycle hooks for Claude Code & Codex
orca report -w <name> -e done              # Report worker lifecycle event (used by hooks)

bash

orca spawn "fix the login bug" -b cc -d ~/proj --orchestrator openclaw --spawned-by openclaw
orca spawn "add unit tests" -b cx -d ~/proj --base-branch develop --orchestrator cx --spawned-by fin
orca spawn "refactor auth" -b cu -d ~/proj --orchestrator cu --spawned-by ace

orca list                                   # 列出所有工作进程
orca status <name>                          # 查看详细状态（最后几行输出）
orca logs <name>                            # 查看完整终端输出
orca steer <name> "also add tests"          # 向运行中的工作进程发送后续指令
orca kill <name>                            # 终止单个工作进程（若不属于你会发出警告）
orca killall --mine                         # 仅终止你的工作进程（安全，自动检测面板）
orca killall --force                        # 全局终止所有工作进程（需要人工确认！）
orca gc --mine                              # 清理你已完成/已终止的工作进程
orca gc --force                             # 清理所有已完成/已终止的工作进程（需要人工确认！）
orca daemon start|stop|status               # 守护进程管理（首次执行spawn时自动启动）
orca hooks install|uninstall                # 为Claude Code和Codex安装/移除生命周期钩子
orca report -w <name> -e done              # 上报工作进程生命周期事件（钩子使用）

Backends

后端

Flag	Agent
`-b cc`	Claude Code
`-b cx`	Codex
`-b cu`	Cursor Agent

参数	Agent
`-b cc`	Claude Code
`-b cx`	Codex
`-b cu`	Cursor Agent

Cleanup responsibility

清理职责

Do NOT kill or gc workers automatically. The human decides when to kill/gc — they may want to inspect logs, review branches, or cherry-pick work first.
If the human explicitly asks you to clean up, use
```
orca gc --mine
```
(safe, scoped to your workers only).

**不要自动终止或清理工作进程。**何时终止/清理由人类决定 —— 他们可能需要检查日志、查看分支或挑选工作成果。
如果人类明确要求你清理，请使用
```
orca gc --mine
```
（安全，仅作用于你的工作进程）。

Recovering work after

orca kill

gc

orca kill

gc

后恢复工作

When a worker is killed or garbage-collected, Orca auto-stashes uncommitted changes before removing the worktree. Stashes attach to the main repo, not the deleted worktree path.

From the project root (

-d

directory):

bash

git stash list                           # look for "orca-preserving <worker> …"
git stash show -p stash@{n}              # inspect the diff
git stash pop                            # or: git stash apply stash@{n}

Committed work on a branch is unaffected by stash; detached commits still need branches per normal Git rules.
Pass
```
--no-stash
```
to
```
kill
```
,
```
killall
```
, or
```
gc
```
to skip stashing (automation escape hatch).
Debugging:
```
$ORCA_HOME/audit.log
```
has
```
KILL
```
,
```
GC
```
, and
```
STASH_PRESERVE
```
entries;
```
events/<worker>.jsonl
```
has lifecycle events;
```
logs/<worker>.log
```
has terminal output;
```
daemon.log
```
has daemon diagnostics.

当工作进程被终止或垃圾回收时，Orca会在移除工作目录前自动暂存未提交的更改。暂存内容关联到主仓库，而非已删除的工作目录路径。

从项目根目录（

-d

指定的目录）执行：

bash

git stash list                           # 查找包含"orca-preserving <worker> …"的记录
git stash show -p stash@{n}              # 查看差异
git stash pop                            # 或：git stash apply stash@{n}

分支上的已提交工作不受暂存影响；分离的提交仍需遵循常规Git规则创建分支。
执行
```
kill
```
、
```
killall
```
或
```
gc
```
时传递
```
--no-stash
```
可跳过暂存（自动化场景的逃生舱）。
调试：
```
$ORCA_HOME/audit.log
```
包含
```
KILL
```
、
```
GC
```
和
```
STASH_PRESERVE
```
条目；
```
events/<worker>.jsonl
```
包含生命周期事件；
```
logs/<worker>.log
```
包含终端输出；
```
daemon.log
```
包含守护进程诊断信息。

DO

建议做法

Spawn workers for independent tasks that can run in parallel
After spawning, stop and wait silently -- the daemon notifies you when workers finish
Use
```
orca list
```
/
```
orca status
```
only when the user asks what's happening
Do NOT kill or gc workers yourself — the human decides when to clean up
Always pass
```
--orchestrator
```
with the correct value for your agent type

为可并行运行的独立任务生成工作进程
生成后请停止操作并静默等待 —— 工作进程完成后守护进程会通知你
仅在用户询问进展时使用
```
orca list
```
/
```
orca status
```
不要自行终止或清理工作进程 —— 由人类决定清理时机
务必传递
```
--orchestrator
```
参数，并设置与你的Agent类型匹配的正确值

DON'T

禁止做法

NEVER run
orca kill
,
orca killall
, or
orca gc
unless the human explicitly asks -- killing workers can destroy in-progress work and kill orchestrator panes
Don't sleep or poll -- no
```
sleep
```
, no
```
orca list
```
loops, no periodic checks. Just stop and wait for the daemon notification.
Don't use tmux commands directly -- always go through
```
orca
```
Don't spawn more than 4-5 workers at once unless explicitly asked
Don't steer workers with huge messages -- spawn a fresh worker instead
Don't spawn sub-workers if you're at max depth -- do the work yourself
Don't stop the daemon (
```
orca daemon stop
```
) -- other orchestrators share it

除非人类明确要求，否则绝不要执行
orca kill
、
orca killall
或
orca gc
—— 终止工作进程可能会销毁正在进行的工作，并终止编排器面板
不要休眠或轮询 —— 不要使用
```
sleep
```
，不要循环执行
```
orca list
```
，不要定期检查。只需停止操作并等待守护进程通知。
不要直接使用tmux命令 —— 始终通过
```
orca
```
执行
除非明确要求，否则不要同时生成超过4-5个工作进程
不要用大消息指令工作进程 —— 请生成新的工作进程
若已达到最大深度，不要生成子工作进程 —— 请自行完成任务
不要停止守护进程（
```
orca daemon stop
```
） —— 其他编排器会共享该进程

orca

Original

Translation

Orca — Agent Orchestrator

Orca — Agent编排器

Identify yourself

确认你的身份

--spawned-by rules

--spawned-by规则

OpenClaw (L0 orchestrator)

OpenClaw（L0编排器）

Claude Code (cc / claude)

Claude Code (cc / claude)

As a worker (ORCA_WORKER_NAME is set):

作为工作进程（ORCA_WORKER_NAME已设置）：

As L0 orchestrator (ORCA_WORKER_NAME is not set):

作为L0编排器（ORCA_WORKER_NAME未设置）：

Codex (cx / codex)

Codex (cx / codex)

As a worker (ORCA_WORKER_NAME is set):

作为工作进程（ORCA_WORKER_NAME已设置）：

As L0 orchestrator (ORCA_WORKER_NAME is not set):

作为L0编排器（ORCA_WORKER_NAME未设置）：

Cursor (cu / cursor)

Cursor (cu / cursor)

As a worker (ORCA_WORKER_NAME is set):

作为工作进程（ORCA_WORKER_NAME已设置）：

As L0 orchestrator (ORCA_WORKER_NAME is not set):

作为L0编排器（ORCA_WORKER_NAME未设置）：

Sub-workers (worker spawning further workers)

子工作进程（工作进程生成更多子进程）

Example: you are worker "fin" spawning sub-workers

示例：你是工作进程"fin"，正在生成子工作进程

Headless / scripts (not interactive agents)

无头模式 / 脚本（非交互式Agent）

CLI reference

CLI参考

Backends

后端

Cleanup responsibility

清理职责

Recovering work after orca kill / gc

orca kill / gc后恢复工作

DO

建议做法

DON'T

禁止做法

`--spawned-by`
rules

`--spawned-by`
规则

Claude Code (
`cc`
/
`claude`
)

Claude Code (
`cc`
/
`claude`
)

Codex (
`cx`
/
`codex`
)

Codex (
`cx`
/
`codex`
)

Cursor (
`cu`
/
`cursor`
)

Cursor (
`cu`
/
`cursor`
)

Recovering work after
`orca kill`
/
`gc`

`orca kill`
/
`gc`
后恢复工作