warp-delegate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Warp Delegate

Warp 任务委托

You are the orchestrator. Delegate a bounded coding task to a separate implementer - the Warp Agent CLI - then review what it produced and land it yourself. You write the brief and own the judgment; the implementer makes changes in its own conversation; you verify and commit.

The loop needs only a shell command and file access, so any comparable orchestrator can drive it.

你是编排者。将一个明确范围的编码任务委托给独立的实现工具——Warp Agent CLI——然后审查其产出并自行完成落地。你撰写任务简报并负责判断；实现工具在其独立会话中进行修改；你负责验证并提交。

该流程仅需shell命令和文件访问权限，因此任何类似的编排工具均可驱动它。

The binary is

oz

, not

warp

二进制工具是

oz

，而非

warp

Warp ships two different programs, and only one of them can be delegated to:

oz
- the Warp Agent CLI. Headless and scriptable;
```
oz agent run
```
executes an agent against a local directory. This is what the relay drives.
warp
- the interactive Warp TUI. It requires a terminal device, has no prompt or print flag (its only options are
```
--resume
```
,
```
--auto-approve
```
,
```
--api-key
```
, and the provider-key commands), and exits with
```
Device not configured
```
when stdin is a pipe. It cannot be relayed.

oz

is missing but

warp

is installed, you have the TUI, not the CLI.

Warp提供两个不同的程序，其中只有一个可用于任务委托：

oz
- Warp Agent CLI。无头且可脚本化；
```
oz agent run
```
会在本地目录中执行agent。这正是本中继工具所驱动的程序。
warp
- 交互式Warp TUI。它需要终端设备，没有提示符或打印标志（仅有的选项为
```
--resume
```
、
```
--auto-approve
```
、
```
--api-key
```
以及提供商密钥命令），当标准输入为管道时会以
```
Device not configured
```
错误退出。它无法通过中继工具调用。

如果

oz

缺失但安装了

warp

，则你拥有的是TUI而非CLI。

When NOT to use this

请勿使用此工具的场景

The task is small enough to do inline; delegation overhead is not worth it.
The
```
oz
```
CLI is not installed or authenticated.
You need a sandboxed or read-only implementer.
```
oz agent run
```
has no sandbox, no permission mode, and no read-only run - see Autonomy and permissions.
The work must stay off Warp's servers.
```
oz agent run
```
uploads an end-of-run workspace snapshot unless
```
--no-snapshot
```
is passed, and conversations live server-side.

任务规模小到可直接完成；委托带来的开销得不偿失。
```
oz
```
CLI未安装或未完成认证。
你需要一个沙箱化或只读的实现工具。
```
oz agent run
```
没有沙箱、权限模式或只读运行模式——详见自主性与权限。
工作内容必须远离Warp服务器。
```
oz agent run
```
会上传运行结束时的工作区快照，除非传递
```
--no-snapshot
```
参数，且会话内容会存储在服务器端。

Prerequisites (check once)

前置条件（只需检查一次）

Install the Warp Agent CLI - see https://docs.warp.dev/cli/.
Authenticate:
```
oz login
```
, or set
```
WARP_API_KEY
```
for CI, a container, or any headless host.
Confirm the account has AI quota. A working login is not enough - unlike the other CLIs in this package.
```
oz whoami
```
can succeed while every dispatch fails with
```
In order to use Warp's AI features, subscribe to a Warp plan, or bring your own inference.
```
Warp records this internally as
```
QuotaLimit
```
/ "lack of AI quota", so it is a credit condition on the account rather than a CLI-specific entitlement:
```
oz
```
runs the same agent harness as the Warp app and draws on the same account, plan, and credits. Check that
```
oz whoami
```
names the account holding the plan - if it does not,
```
oz logout && oz login
```
fixes it. Otherwise confirm the plan's AI credits are not spent, or store your own provider key -
```
warp --set-provider-api-key <openai|anthropic|google|grok>
```
, or
```
/api-keys
```
inside the TUI. Bring-your-own-key needs no paid Warp plan.
Confirm
```
oz --version
```
succeeds and
```
oz whoami
```
prints your user.
Work in, or point
```
--cd
```
at, the target git repository.

On macOS the CLI is distributed as a signed Developer ID binary; a first run may be held by Gatekeeper until it is approved.

安装Warp Agent CLI - 查看https://docs.warp.dev/cli/。
完成认证：执行
```
oz login
```
，或为CI、容器或任何无头主机设置
```
WARP_API_KEY
```
。
确认账户拥有AI配额。仅成功登录是不够的——与本包中的其他CLI不同。
```
oz whoami
```
可能执行成功，但每次调度都会失败并提示
```
In order to use Warp's AI features, subscribe to a Warp plan, or bring your own inference.
```
Warp内部将此记录为
```
QuotaLimit
```
/ "缺少AI配额"，因此这是账户的信用条件，而非CLI特有权限：
```
oz
```
运行的agent harness与Warp应用相同，且使用相同的账户、套餐和信用额度。确认
```
oz whoami
```
显示的账户持有对应套餐——若未显示，执行
```
oz logout && oz login
```
即可修复。否则请确认套餐的AI信用额度未耗尽，或存储你自己的提供商密钥——执行
```
warp --set-provider-api-key <openai|anthropic|google|grok>
```
，或在TUI内使用
```
/api-keys
```
命令。使用自有密钥无需付费Warp套餐。
确认
```
oz --version
```
执行成功且
```
oz whoami
```
显示你的用户信息。
在目标git仓库中工作，或通过
```
--cd
```
参数指定目标git仓库路径。

在macOS上，CLI以签名的Developer ID二进制文件分发；首次运行可能会被Gatekeeper拦截，直到你批准它。

Choose the model (optional)

选择模型（可选）

Omit

--model

to use Warp's configured default. To pick another, choose an id from

oz model list

and pass it verbatim. The relay accepts letters, digits, and

. _ : / -

only, so a value cannot be mistaken for another

oz

flag.

省略

--model

参数将使用Warp配置的默认模型。如需选择其他模型，从

oz model list

中选择一个ID并直接传递。中继工具仅接受字母、数字以及

. _ : / -

，因此该值不会被误认为其他

oz

标志。

The loop

流程循环

Run these five steps per task. Steps 1, 4, and 5 require judgment; 2 and 3 are mechanical.

每个任务执行以下五个步骤。步骤1、4和5需要判断；步骤2和3为机械操作。

1. Write the brief

1. 撰写任务简报

Warp sees only the text you send plus what it can inspect in the workspace - no chat history or shared context. Include the goal, current state, what to change, what to leave untouched, the project's actual gates, and a report contract. Tell it not to commit. Keep one task per brief. The brief is delivered as the

--prompt

value on argv, so it is visible in the host process list - keep secrets out of it and reference workspace files instead. See references/writing-the-brief.md.

Warp只能看到你发送的文本以及它在工作区中可检查的内容——没有聊天历史或共享上下文。请包含目标、当前状态、需要修改的内容、需要保留的内容、项目的实际准入条件以及报告约定。告知它不要提交。每个简报对应一个任务。简报作为argv上的

--prompt

值传递，因此会在主机进程列表中可见——请勿在其中包含机密信息，而是引用工作区文件。详见references/writing-the-brief.md。

2. Dispatch

2. 调度任务

Use the bundled relay. It runs

oz agent run --output-format ndjson

, captures the event stream, and writes

result.json

. (

<skill-dir>

is the installed folder containing this

SKILL.md

bash

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo

使用捆绑的中继工具。它会运行

oz agent run --output-format ndjson

，捕获事件流并写入

result.json

。（

<skill-dir>

是包含此

SKILL.md

的安装文件夹。）

bash

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo

choose a model: add --model <id from oz model list>

选择模型: 添加 --model <id from oz model list>

use an agent profile: add --profile <id>

使用agent配置文件: 添加 --profile <id>

label the run: add --name <label>

为运行添加标签: 添加 --name <label>

continue an existing conversation: add --conversation <id> (delta brief only)

继续现有会话: 添加 --conversation <id> (仅传递增量简报)

base the run on a Warp skill: add --skill <name|repo:name|org/repo:name>

基于Warp skill运行: 添加 --skill <name|repo:name|org/repo:name>

start MCP servers: add --mcp <path-or-inline-json> (repeatable)

启动MCP服务器: 添加 --mcp <path-or-inline-json> (可重复添加)

suppress the workspace snapshot upload: add --no-snapshot

禁止上传工作区快照: 添加 --no-snapshot

hard time limit (watchdog): add --timeout 2h (the 30m default suits short runs; implementation briefs routinely need 1-2h)

硬时间限制（看门狗）: 添加 --timeout 2h (默认30分钟适合短运行；实现类简报通常需要1-2小时)

see all options: node .../relay.mjs --help

查看所有选项: node .../relay.mjs --help


The relay pins the workspace with both the child process's cwd and Warp's own `--cwd`. It writes
artifacts under the system temp dir by default and never commits. See
[references/dispatch-and-poll.md](references/dispatch-and-poll.md).


中继工具通过子进程的当前工作目录和Warp自身的`--cwd`固定工作区。它默认在系统临时目录下写入工件，且从不提交。详见[references/dispatch-and-poll.md](references/dispatch-and-poll.md)。

3. Wait for completion

3. 等待完成

The relay blocks until

oz

finishes. Run it with the orchestrator's background-command facility, or background it in the shell and poll for

result.json

. A pre-run usage error exits 2 and writes no result; a missing

oz

exits 127 and writes

status: "warp_unavailable"

Trust process state and the working tree over a progress display. Completion means the process exited and

result.json

exists. Warp's report is the

finalMessage

field in

result.json

(also printed on stdout between the report markers); the raw event stream is always in

events.jsonl

中继工具会阻塞直到

oz

完成。使用编排工具的后台命令功能运行它，或在shell中将其放入后台并轮询

result.json

。预运行使用错误会以状态码2退出且不写入结果；若

oz

缺失则以状态码127退出并写入

status: "warp_unavailable"

。

优先信任进程状态和工作树而非进度显示。完成意味着进程已退出且

result.json

存在。Warp的报告位于

result.json

的

finalMessage

字段中（也会在报告标记之间打印到标准输出）；原始事件流始终存储在

events.jsonl

中。

4. Review - do not trust the self-report

4. 审查——不要信任自我报告

Treat Warp's final message and gate claims as claims:

Re-run the project's gates yourself.
Read the diff against the brief, starting with
```
touchedFiles
```
.
Run relevant guard skills if installed.
Round-trip migrations and grep for dangling references after removals or renames.

Because there is no read-only mode to fall back on, the diff is the only record you get - and it records what git can see in the workspace afterward, not everything the run did. Dispatch from a clean tree so the two are as close as they can be. See references/review-and-land.md.

将Warp的最终消息和准入条件声明仅视为声明：

自行重新运行项目的准入检查。
根据简报审查diff，从
```
touchedFiles
```
开始。
若已安装相关防护skill则运行它们。
在删除或重命名后往返迁移并搜索悬空引用。

由于没有只读模式可以 fallback，diff是你能获取的唯一记录——它记录的是运行后git在工作区中能看到的内容，而非运行期间的所有操作。请从干净的工作树开始调度，以便两者尽可能一致。详见references/review-and-land.md。

5. Land it

5. 完成落地

The implementer edits the working tree; the orchestrator commits. Commit only after the gates pass and the diff holds. If rework is needed, send a delta brief with

--conversation <id>

using the

conversationId

from

result.json

, then review again.

实现工具会编辑工作树；编排者负责提交。仅在准入检查通过且diff符合要求后再提交。若需要返工，请使用

result.json

中的

conversationId

，通过

--conversation <id>

传递增量简报，然后再次审查。

Autonomy and permissions

自主性与权限

oz agent run

has no sandbox, no permission mode, and no read-only mode. A headless run reads, writes, edits, and executes commands with your own user permissions and never prompts. There is nothing in the CLI to restrict that surface, so this relay ships no

--read-only

flag - offering one would imply an enforcement that does not exist. The controls you actually have are:

Scope by directory.
```
--cd
```
pins the workspace, and the relay passes it to Warp's own
```
--cwd
```
. Treat this as aim, not a fence: on oz 0.2026.05.27 shell commands did run in the pinned workspace, but the agent's file tool resolved bare relative paths against
```
$HOME
```
. Name absolute paths in the brief - see references/writing-the-brief.md.
Review the diff.
```
touchedFiles
```
is
```
git status --porcelain
```
taken after the run - post-run, git-visible worktree state, not a log of what the agent did. It cannot show an ignored file, an edit the run made and then reverted, or a write outside the repository (see item 1), and it carries anything that was already dirty before dispatch. Dispatch from a clean tree so those are the same set, and treat the diff as the best available record, not a complete one.
Snapshot egress.
```
--no-snapshot
```
forwards Warp's flag so the end-of-run workspace snapshot is not uploaded. Without it, the upload is Warp's default.

--auto-approve

belongs to the interactive

warp

TUI and has no bearing on

oz agent run

oz agent run

没有沙箱、权限模式或只读模式。无头运行会以你的用户权限读取、写入、编辑和执行命令，且从不提示。CLI中没有任何功能可以限制这些操作范围，因此本中继工具未提供

--read-only

标志——提供该标志会暗示存在实际并不存在的强制限制。你实际拥有的控制手段为：

按目录限定范围。
```
--cd
```
固定工作区，且中继工具会将其传递给Warp自身的
```
--cwd
```
。将此视为目标定位，而非围栏：在oz 0.2026.05.27版本中，shell命令确实会在固定的工作区中运行，但agent的文件工具会相对于
```
$HOME
```
解析裸相对路径。请在简报中使用绝对路径——详见references/writing-the-brief.md。
审查diff。
```
touchedFiles
```
是运行后执行
```
git status --porcelain
```
的结果——即运行后git可见的工作树状态，而非agent操作的日志。它无法显示被忽略的文件、运行后又被还原的编辑，或仓库外的写入（见第1点），且会包含调度前已存在的脏内容。请从干净的工作树开始调度，以便两者一致，并将diff视为最佳可用记录，而非完整记录。
快照导出。
```
--no-snapshot
```
会传递Warp的标志，从而禁止上传运行结束时的工作区快照。若无此参数，上传是Warp的默认行为。

--auto-approve

属于交互式

warp

TUI，与

oz agent run

无关。

Authorization model

授权模型

Delegation is something the human opts into. Once they have ("run this queue", "proceed"), committing verified, gate-passing work is the agreed contract. Two limits remain: surface, don't absorb (report Warp's design decisions, defensible-but-unasked turns, and non-blocking nitpicks) and stop for scope changes (if correct completion needs going beyond the brief, ask instead of expanding the mandate). See references/review-and-land.md.

任务委托是用户主动选择的操作。一旦用户同意（“运行此队列”、“继续”），提交经过验证且通过准入检查的工作内容就是约定的契约。仍有两个限制：透明展示，而非隐瞒（报告Warp的设计决策、合理但未被要求的变更以及非阻塞性细节问题），以及遇到范围变更时停止（若正确完成任务需要超出简报范围，请先询问用户而非自行扩大权限）。详见references/review-and-land.md。

References

参考资料

references/writing-the-brief.md - structure, report contract, real gates, argv delivery, and delta briefs.
references/dispatch-and-poll.md - flags, artifacts,
```
result.json
```
, polling, and failure recovery.
references/review-and-land.md - review checklist, commit boundary, and rework through Warp conversations.
references/multi-task-queues.md - sequential queues, constraint carry-forward, progress tracking, and the final coherence pass.

references/writing-the-brief.md - 结构、报告约定、实际准入条件、argv传递以及增量简报。
references/dispatch-and-poll.md - 标志、工件、
```
result.json
```
、轮询以及故障恢复。
references/review-and-land.md - 审查清单、提交边界以及通过Warp会话进行返工。
references/multi-task-queues.md - 顺序队列、约束传递、进度跟踪以及最终一致性检查。