warp-delegate

Warp Delegate

你是 编排者。将一项范围明确的编码任务委派给单独的 实现者——Warp Agent CLI，然后审查其产出并由你亲自落地。你撰写任务说明并负责判断；实现者在自己的对话中进行修改；你负责验证并提交。

这个循环只需要一条 shell 命令和文件访问权限，因此任何类似的编排者都能驱动它。

可执行文件是 oz，不是 warp

Warp 提供了两个不同的程序，只有其中一个可以用于委派：

• oz - Warp Agent CLI。无头且可编写脚本；oz agent run 会针对本地目录运行 Agent。中继驱动的就是它。
• warp - 交互式 Warp TUI。它需要终端设备，没有提示词或打印标志（仅提供 --resume、--auto-approve、--api-key 和提供商密钥命令），且当 stdin 是管道时会因 Device not configured 而退出。无法通过中继驱动。

如果没有安装 oz，但安装了 warp，那么你拥有的是 TUI，而不是 CLI。

何时不应使用

• 任务足够小，可以直接完成；委派带来的额外开销不值得。
• 未安装或未完成身份验证的 oz CLI。
• 需要沙盒化或只读的实现者。oz agent run 没有沙盒、没有权限模式，也没有只读运行方式 - 请参阅自主性与权限。
• 工作必须避免上传到 Warp 的服务器。除非传入 --no-snapshot，否则 oz agent run 会在运行结束时上传工作区快照，对话也存储在服务器端。

前提条件（检查一次即可）

1. 安装 Warp Agent CLI - 请参阅 https://docs.warp.dev/cli/。
2. 完成身份验证：运行 oz login，或为 CI、容器或任何无头主机设置 WARP_API_KEY。
3. 确认账户有 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 使用与 Warp 应用相同的 Agent 框架，并使用相同账户、计划和额度。检查 oz whoami 显示的是否为持有计划的账户 - 如果不是，运行 oz logout && oz login 即可修正。否则，请确认计划的 AI 额度尚未用完，或存储自己的提供商密钥 - warp --set-provider-api-key <openai|anthropic|google|grok>，或在 TUI 中使用 /api-keys。自带密钥无需付费 Warp 计划。
4. 确认 oz --version 能成功运行，且 oz whoami 会显示你的用户。
5. 在目标 git 仓库中工作，或通过 --cd 指向该仓库。

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

选择模型（可选）

省略 --model 即使用 Warp 配置的默认模型。要选择其他模型，请从 oz model list 中选取一个 ID 并原样传入。中继只接受字母、数字以及 . _ : / -，因此值不会被误认为另一个 oz 标志。

工作循环

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

1. 撰写任务说明

Warp 只能看到你发送的文本，以及它能在工作区中检查的内容 - 没有聊天历史记录或共享上下文。请写明目标、当前状态、要修改的内容、要保持不变的内容、项目实际的检查关卡，以及报告约定。告诉它不要提交。每份任务说明只包含一项任务。任务说明会作为 --prompt 的值通过 argv 传递，因此会显示在宿主进程列表中 - 请勿在其中放入机密，并改为引用工作区文件。请参阅 references/writing-the-brief.md。

2. 调度

对于 Codex 对后台工作的编排，请先安装并配置独立的 codex-background 支持工具。如果缺少其 MCP 工具或注册表，请停止并说明所需的设置；不要悄悄回退到由模型驱动的轮询。然后调用其已注册的 delegate_run MCP 工具一次，代替下面的 shell 示例。 遵循该技能，使用结构化的通用参数、保持提供方标志不变，并通过 runId 重新连接。请求需保持待处理状态，直至任务完成，然后继续执行本技能中的审查和提交步骤。其他编排器继续使用下面的 shell 工作流。

使用随附的中继程序。它会运行 oz agent run --output-format ndjson，捕获事件流，并写入 result.json。（<skill-dir> 是安装了此 SKILL.md 的文件夹。）

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
# choose a model:                          add --model <id from oz model list>
# use an agent profile:                    add --profile <id>
# label the run:                           add --name <label>
# continue an existing conversation:       add --conversation <id> (delta brief only)
# base the run on a Warp skill:            add --skill <name|repo:name|org/repo:name>
# start MCP servers:                       add --mcp <path-or-inline-json>  (repeatable)
# suppress the workspace snapshot upload:  add --no-snapshot
# hard time limit (watchdog):              add --timeout 2h  (the 30m default suits short runs; implementation briefs routinely need 1-2h)
# see all options:                         node .../relay.mjs --help

中继程序会同时通过子进程的 cwd 和 Warp 自身的 --cwd 固定工作区。默认情况下，它会将产物写入系统临时目录，且绝不会提交。请参阅 references/dispatch-and-poll.md。

3. 等待完成

使用 codex-background 的 Codex 会让原始 MCP 请求保持待处理状态：不进行由模型驱动的休眠、状态轮询或日志轮询。只有在请求中断后重新连接时，才使用 delegate_wait。

中继程序会阻塞，直到 oz 运行完毕。使用编排器的后台命令功能运行它，或在 shell 中将其置于后台并轮询 result.json。运行前发生用法错误时会以状态码 2 退出且不写入结果；找不到 oz 时会以状态码 127 退出，并写入 status: "warp_unavailable"。

请以进程状态和工作树为准，而非进度显示。进程已退出且 result.json 存在，即表示完成。Warp 的报告位于 result.json 的 finalMessage 字段中（也会在标准输出的报告标记之间打印）；原始事件流始终保存在 events.jsonl 中。

4. 审查——不要轻信自述

将 Warp 的最终消息和门禁声明视为主张：

• 自行重新运行项目的门禁。
• 对照任务说明阅读差异，从 touchedFiles 开始。
• 如果已安装相关的防护技能，请运行它们。
• 执行迁移的往返测试，并在移除或重命名后 grep 检查是否存在悬空引用。

由于没有只读模式可供回退，差异是你能获得的唯一记录；它记录的是运行结束后 git 在工作区中可见的内容，而非运行期间所做的一切。请从干净的工作树开始调度，以尽可能缩小两者之间的差异。请参阅 references/review-and-land.md。

5. 提交

实现者修改工作树；由编排器提交。 只有在门禁通过且差异符合要求后才能提交。如需返工，请使用 result.json 中的 conversationId，通过 --conversation <id> 发送增量任务说明，然后再次审查。

自主性与权限

oz agent run 没有沙盒、权限模式或只读模式。无头运行会以你自己的用户权限读取、 写入、编辑和执行命令，而且绝不会提示确认。CLI 中没有任何机制可以限制这一范围，因此 这个中继工具不会提供 --read-only 标志——提供它会让人误以为存在实际上并不存在的强制 限制。你实际可用的控制方式如下：

1. 限定目录范围。 --cd 会固定工作区，中继工具会将其传递给 Warp 自带的 --cwd。 请将其视为目标范围，而非防护边界：在 oz 0.2026.05.27 中，Shell 命令确实在固定的 工作区内运行，但 Agent 的文件工具会将未指定路径的相对路径解析为 $HOME 下的路径。 请在任务说明中使用绝对路径——参见 references/writing-the-brief.md。
2. 检查差异。 touchedFiles 是运行结束后获取的 git status --porcelain 结果——它反映 运行后的 Git 可见工作树状态，而不是 Agent 操作的日志。它无法显示被忽略的文件、运行 中进行后又撤销的编辑，或仓库之外的写入（见第 1 项），且会包含派发前就已存在的所有 未提交更改。请从干净的工作树派发任务，这样两者才会一致；并将差异视为目前最好的记录， 而非完整记录。
3. 控制快照上传。 --no-snapshot 会转发 Warp 的标志，这样运行结束时便不会上传工作区 快照。不使用该标志时，上传行为遵循 Warp 的默认设置。

--auto-approve 属于交互式 warp TUI，与 oz agent run 无关。

授权模型

是否委派由人类自行决定。一旦人类授权（“运行此队列”“继续”），提交经过验证且通过门禁的 工作就是双方约定的契约。但仍有两条限制：如实呈现，不要代为决定（报告 Warp 的设计 决策、有充分理由但未经请求的改动，以及不阻塞任务的小问题），以及范围变更时暂停（若 正确完成任务需要超出任务说明的范围，应先询问，而不是自行扩大授权范围）。参见 references/review-and-land.md。

参考资料

• references/writing-the-brief.md - 结构、报告约定、实际门禁、 argv 传递方式和增量任务说明。
• references/dispatch-and-poll.md - 标志、产物、 result.json、轮询和故障恢复。
• references/review-and-land.md - 审查清单、提交边界，以及通过 Warp 对话返工。
• references/multi-task-queues.md - 顺序队列、约束传递、进度跟踪 和最终一致性检查。