relay_tool 0.9.4 新增

借助 relay_tool，智能体可以与其他会话协作：列出并读取它们、给其中一个发送提示词、启动一个新会话、等待回复、回答另一个智能体提出的问题、停止或归档会话，还可以请求在它所监视的会话中发生事情时被唤醒。

它可以访问两种中继：

• 此中继，即智能体自身运行于其上的中继。智能体可以把任务的一部分交给这里的其他会话。在你开启之前是关闭的。0.9.7 新增
• 已配对的中继，即你与此中继配对的其他 OAR 中继，例如你工作站上的中继和服务器上的中继。在每个对话中保持锁定，直到你提及该中继。

该工具在拥有它的每个提供商上都相同；参见按提供商了解谁拥有它以及名称。

名称 0.9.18 新增 #

在 0.9.17 及更早版本中，该工具名为 remote_relay。现在它在每个提供商上都列为 relay_tool（Claude 的智能体看到 mcp__relay__relay_tool），操作和字段相同。以旧名称写入的工具行仍显示为该工具。

• 更新时正在运行的会话。 会话的智能体在其 worker 启动时获得工具列表，而 worker 在中继重启期间会继续运行。这样的会话的智能体在它的 worker 再次启动之前，仍以 remote_relay 拥有该工具，例如在 Kill session（强制结束会话）之后。它的调用继续有效：无论以哪个名称，调用都以相同方式到达中继。当中继以 Linux 服务运行时，worker 可能随中继停止，随后以新名称回来。
• OAR 自己的 MCP 服务器，即 Grok 和 Copilot 扩展引擎使用的那个，仍然会执行对 remote_relay 的调用，但不再列出它。
• 你自己的指令。 如果你的指令、权限规则或 hook 中使用了 remote_relay 或 mcp__relay__remote_relay，请改为 relay_tool 或 mcp__relay__relay_tool：在 OAR 的 MCP 服务器之外，旧名称会被拒绝。

你会看到什么 #

• 审批卡片。 在智能体于对话中启动第一个会话之前、在它第一次监视会话之前，以及在对话处于 ask 或 plan 中继模式时的每个写入操作之前，都会用一张提问卡片征询。
• 回复中的工具调用。 智能体的活动会显示每次调用，带有 🛰️、操作、中继和会话。
• “via agent”（经由智能体）。智能体启动的会话会在对话列表中以及其标题下方带有 via agent · "title"，指明智能体运行所在的对话。0.9.11 新增 它位于该对话下的一个会话分组中，0.9.16 新增 或位于智能体指定的一个已有分组中。
• “↗ from …”（来自 …）。智能体发送的提示词在接收方带有徽标，标明发送的中继、会话和模型。
• 监视。 监视其他会话的对话会在其标题栏中显示 watching N sessions（正在监视 N 个会话）；小标签列出它的订阅，每个带有一个 Unsubscribe（取消订阅）按钮。被监视的会话显示一个 watched（监视）徽标。

启用 #

当以下至少一项成立时，就会向智能体提供 relay_tool：

会话在其智能体进程启动时确定它是否获得该工具，因此已经在运行的对话可能直到其智能体再次启动才拥有它。

命名中继 #

除 list_relays 外的每个操作都作用于一个中继，在 relay 中指定：

• "this"，或此中继自己的名称，即智能体运行于其上的中继。它无需提及。
• 已配对的中继用其中继名称或主机命名，如 list_relays 所示。

对于四个订阅操作、0.9.16 新增 三个定时操作和三个提问操作，relay 可以省略，意为 "this"。定时任务只在此中继上生效。

锁定与解锁 #

已配对的中继在对话中保持 locked（已锁定），直到发生以下情况之一：

• 你在某条消息中提及它：输入 @ 并选择它，或写出它的名称或主机名。名称为 IP 地址或 localhost 的中继只有带前导 @ 才算数。
• 该中继上的智能体向对话写入。该中继随后打开，这样这里的智能体就能回答。

一旦解锁，它在对话的剩余时间里保持打开。锁定的中继会拒绝除 list_relays 外的每个操作；智能体被告知请你在对话中提及该中继。

权限与批准 #

已配对的中继允许什么 #

每个已配对的中继在 Settings → Relays 下都有一个 Agents may（智能体可以）级别。新的配对从 Full（完全访问）开始。

list_relays 不需要级别。此中继本身始终算作 Full。

在另一端，Accept prompts from other relays' agents（接受其他中继上智能体的提示词）（已配对中继上的 Settings → Relays）会关闭另一个中继的智能体在那里可以更改或监视的一切：提示、启动、回答、停止和归档会话，以及订阅它们。列出和读取会话、读取任务输出、等待、relay_info 和 usage 仍然有效。

何时征询你 #

此中继上会话的规则 #

• 最多 4 个在工作。 一个对话的智能体启动的会话中，同一时间最多 4 个可以有排队或运行中的轮次。第五个会被拒绝，直到其中一个结束。
• 只有一层。 智能体创建的会话本身无法再创建会话，0.9.16 新增 除非你为它开启 Agents in this conversation may start sessions（允许此对话中的智能体启动会话）。list_sessions 和 read_session 随后会显示 "mayCreateSessions": true。任何智能体都无法设置该开关。
• 不能作用于自身。 智能体不能对它所运行的对话进行 send、wait、stop 或 archive，也不能回答自己的问题，0.9.16 新增 也不能更改其设置。
• 你的账户。 智能体启动的会话使用此中继的提供商账户，并计入它们的用量。
• 中继从不会自行归档这些会话。它们会留在你的列表中，直到你归档或删除它们，或智能体归档其中一个。

跨中继 #

• 已经跨越两个中继的提示词不会被传递给第三个，除非你自己解锁了那个中继。读取和等待绝不受此限制。
• 另一个智能体收到的提示词以一行开头，说明另一个智能体正在与它对话：[Remote prompt from an agent on relay "…" · session "…" · model · acting for the user]。
• 以此方式启动的轮次不会在另一个中继上发送“reply ready”通知。提问卡片仍会通知。
• 远程地址必须使用 https://。纯 http:// 仅对环回和私有网络范围接受。

操作 #

每次调用都指定一个 action。下表显示每个操作需要什么；级别是在已配对的中继上允许它的最低 Agents may 设置。

结果是 JSON。成功的调用具有 "ok": true、它所作用的 relay 以及一行 summary；失败的调用具有 "ok": false、一个 code 和一条 error 文本（错误）。下面的示例展示主要字段，名称和 id 均为虚构。

0.9.16 新增 一个操作不接受的参数绝不会被无声丢弃。create_session 和 update_session 会用 REMOTE_RELAY_INVALID_INPUT 拒绝调用，列出它们自己的参数，并且不做任何更改：create_session does not take: session. Its arguments: relay, text, provider, model, cwd, repo, branch, mode, effort, title, group, wait_seconds. Nothing was created. 其他每个操作仍会运行，并在其结果的 ignored 中列出它不接受的参数，最多 20 个。空值（null、""、false 或空列表）算作没有参数，因为有些提供商会发送每个字段。

查找中继和会话 #

list_relays #

列出已配对的中继，包含 name、url、online、version、permission 和 unlocked。当智能体会话开启时，此中继排在最前，标记为 "self": true。还会返回此中继的等待上限。它是唯一一个无需提及、也无需 relay 就能工作的操作。

{ "action": "list_relays" }

{
  "ok": true,
  "summary": "list_relays: 2 relays, 1 unlocked",
  "self": { "name": "desk" },
  "relays": [
    { "name": "desk", "self": true, "online": true, "version": "0.9.19", "permission": "full", "unlocked": true },
    { "name": "build-box", "url": "https://build-box.example.com", "online": true, "version": "0.9.19", "permission": "full", "unlocked": false }
  ],
  "limits": { "maxWaitSeconds": 600, "maxActiveSessions": 4 }
}

relay_info #

中继提供什么，以便智能体为新会话选择提供商、模型和文件夹：它的名称、版本和平台，是否接受智能体提示词，每个提供商及其默认模型、模型和推理强度，默认和最近的工作目录，以及中继模式。

{ "action": "relay_info", "relay": "build-box" }

0.9.16 新增 它还会在 groups 中列出中继的会话分组，即那里的 create_session 可以指定的分组：每个都有 id、name（侧边栏显示的内容；对于无人命名的分组，则是头会话的标题）和 memberCount，最近有活动的分组排在前面。只有至少包含一个未删除会话的分组才会列出，最多 50 个；当有更多时，groupsTotal 会说明有多少。成员 id 和标题不在其中。当中继的分组无法读取时，例如因为它运行较旧的 OAR，groups 为 null，groupsNote 会说明原因，并说明那里的 create_session 不能接收 group。

"groups": [
  { "id": "grp_…", "name": "Release 2.4", "memberCount": 3 },
  { "id": "grp_…", "name": "Review: server/", "memberCount": 2 }
]

usage 0.9.10 新增 #

每个提供商的套餐在中继上还剩多少，这样智能体可以在开始会产生费用的工作之前检查：每个提供商一个状态及其仪表（已用、额度、剩余、利用率、重置时间），以及那里的 Claude 用量上限是否已暂停轮次。参见 Check Usage（查看用量）。未设置或未跟踪的提供商会说明这一点。账户名、地址和令牌绝不会包含在内。

{ "action": "usage", "relay": "this" }

list_sessions #

列出会话，包含 id、title、provider、model、state、cwd、最后活动时间和消息计数。state 为 running_turn、background_only（智能体已回答，后台工作仍在运行）或 idle；tasks 列出后台智能体和 shell 任务。

0.9.11 新增 位于会话分组中的会话还有 group：它的 id、name 以及会话在其中的 role（head 或 member）。0.9.16 新增 create_session 可以把它创建的会话放入已有分组，update_session 可以把会话移入分组（包括新分组）或移出分组。重命名、解散和重排分组都由你来做。

{ "action": "list_sessions", "relay": "build-box", "scope": "active" }

read_session #

读取会话最近的消息，以及那里正在发生的事：它的 state、仍在撰写中的回复（inFlight），以及等待回答的任何 pendingQuestions（0.9.16 新增 每个都有 kind：ask 表示一个 ask，ask_user 表示会话正在等待的卡片）。0.9.11 新增 对于分组中的会话，group 会加上其他成员，最多 50 个，每个都有 id、title、role、state，归档时还有 archived。

{ "action": "read_session", "relay": "build-box", "session": "3f9c…", "last": 5 }

0.9.12 新增 会话的每个 tasks 还有它的 taskId、output（是否有输出可供 read_task_output 读取），对于输出在文件中的命令，还有 health：运行时的 minutesSinceOutput、quiet 和 quietAfterMinutes（中继的静默设置），以及有测试运行结果时的 counts。

read_task_output 0.9.12 新增 #

读取后台 shell 命令或监视器输出的末尾，与任务控制台显示的输出相同：在任务运行期间，以及结束后一小时内。智能体可以检查另一个中继上的构建是否仍在忙、已静默或测试失败，而无需询问启动它的智能体。

结果包含 task（描述、类型、启动、status 和 exitCode）、tail（这些行，作为无颜色的纯文本，重复行标记为 [×N]）、truncated（当它们之前还有更多内容时）、stall（距上次输出的分钟数，以及对照中继设置的 quiet，在任务运行期间），当输出是测试运行时，还有 counts 及其 runner 和通过、失败、跳过的测试数。凭据会像控制台中一样被遮蔽。note 会说明何时只有输出的末尾存在、何时输出已不存在，或何时向智能体的进程请求过输出且调用应在几秒后重试。

{ "action": "read_task_output", "relay": "build-box", "session": "3f9c…", "task_id": "b7k2…", "lines": 50 }

{
  "ok": true,
  "summary": "read_task_output → build-box session 3f9c2a1e task b7k2m9q4: 50 lines, running, last output 14 min ago, 412 passed, 2 failed",
  "task": { "id": "b7k2…", "description": "npm test", "type": "local_bash", "status": "running", "exitCode": null },
  "stall": { "minutes": 14, "since": "2026-10-18T09:12:00.000Z", "quiet": true, "quietAfterMinutes": 10 },
  "counts": { "runner": "vitest", "passed": 412, "failed": 2, "skipped": 0, "final": false },
  "tail": ["…"],
  "truncated": true
}

一个未运行且未在过去一小时内结束的任务会返回 REMOTE_RELAY_NOT_FOUND；早于 0.9.12 的中继会返回 REMOTE_RELAY_UNSUPPORTED。

提示 #

send #

在已有会话中把提示词加入队列，并等待回复。

{ "action": "send", "relay": "build-box", "session": "3f9c…", "text": "Did last night's deploy go through? Answer in two lines." }

{
  "ok": true,
  "relay": "build-box",
  "status": "done",
  "session": "3f9c…",
  "message_id": "b41e…",
  "reply": { "text": "Yes. The deploy finished at 02:14 and the health check is green.", "model": "…" }
}

切换 Claude 会话的计费 0.9.18 新增 #

带 provider 的 send 会在一次调用中把 Claude 会话在订阅和 Claude API 密钥之间切换并发送消息：被拒绝的切换不会发送任何内容，被拒绝的消息不会切换任何内容。另一种计费必须在目标中继上设置好。需要征询时的审批卡片会显示 Switches billing to API key 或 Switches billing to subscription。

• 目标中继拒绝的切换会返回 REMOTE_RELAY_PROVIDER_UNAVAILABLE（当那里未设置 Claude API 或 Claude，或已达到每月上限时），以及 REMOTE_RELAY_UNKNOWN_MODEL（当会话的模型不在另一侧的列表中时）。remoteCode 携带中继自己的代码，例如 CLAUDE_API_CAP_REACHED。
• 早于 0.9.18 的中继无法切换：调用会以 REMOTE_RELAY_UNSUPPORTED 被拒绝，并且不会发送任何内容。
• 没有 provider 时，会话保持其计费。在达到上限时对使用密钥的会话进行 send 会被拒绝，且不会加入队列：用 provider: "claude" 发送以把它切换到订阅，或请用户提高上限。

create_session #

启动一个新会话并给它第一条提示词。新会话对启动它的对话一无所知，因此提示词必须自足。

像 send 一样接收 text、wait_seconds、mode、model 和 effort，此外还有：

智能体省略的内容会跟随它所工作的会话，只要目标中继提供。无法以这种方式启动 OpenAI Image 对话。

{
  "action": "create_session",
  "relay": "this",
  "title": "Review: server/",
  "cwd": "/home/dev/projects/shop",
  "text": "Review the code under server/ for missing input checks. List findings with file and line. Change nothing."
}

Claude Cloud 会话接收仓库而不是文件夹：

{
  "action": "create_session",
  "relay": "this",
  "provider": "claude-cloud",
  "repo": "example-org/sample-repo",
  "branch": "feature/banner",
  "text": "On branch feature/banner, change the sample banner text to \"Hello\" and push. Report what changed.",
  "wait_seconds": 60
}

结果与 send 相同，另加会话启动所用的内容：provider、model、mode、effort、title，以及云端会话的 repo / branch。0.9.16 新增 它还有 group，即新会话进入的会话分组，如 list_sessions 所示（id、name、role），或为 null。

放入分组 0.9.16 新增 #

没有 group 时，在此中继上启动的会话会加入启动它的会话所在的分组，或以该会话为头启动一个分组。在已配对的中继上启动的会话不进入任何分组。

带有 group 时，新会话改为进入那个已有分组，在此中继或已配对的中继上。智能体通过其 id，或 relay_info 所列的名称来指定分组，不区分大小写。空的 group 算作没有。

{
  "action": "create_session",
  "relay": "build-box",
  "group": "Release 2.4",
  "text": "Run the release checklist in docs/RELEASE.md up to the tag. Report each step."
}

中继在显示任何审批卡片之前会在目标上查找该分组，就像它对模型所做的那样，卡片会指明它（Group: Release 2.4 (grp_…)）。以下情况不会创建任何内容：

• 目标没有该 id 或名称的分组。调用会以 REMOTE_RELAY_UNKNOWN_GROUP 被拒绝，error 和 groups 会列出那里的分组（最多 20 个，更多时用 groupsTotal）：Relay "build-box" has no session group "Relase". Groups there: Release 2.4 (grp_…), … No session was created.
• 该名称匹配多个分组。相同的代码，连同该名称的分组：… Pass the id.
• 分组在查找和启动之间被解散。相同的代码。
• 目标的分组无法读取。对 group 来说过旧的中继会返回 REMOTE_RELAY_UNSUPPORTED（The target relay doesn't support groups on create_session yet: …）；不响应或拒绝令牌的中继会以其通常的代码返回。

当会话已创建但未进入所要求的分组时，结果会有 groupWarning，其 summary 以 (no group: …) 结尾，note 会请智能体告诉你。你可以随后手动移动该会话。

create_session 只接受已有分组。要把会话放入新分组，智能体随后用该名称调用 update_session。重命名、解散和重排分组都由你来做。

update_session 0.9.16 新增 #

为另一个会话的后续轮次更改其设置，而不提示它，并返回它现在的设置以及更改了什么。它在此中继和已配对的中继上都有效。

至少需要一个设置。任何其他参数都会被拒绝，且不会更改任何内容。mayCreateSessions 不在设置之列：Whether a session may start sessions is the owner's setting alone.

{ "action": "update_session", "relay": "this", "session": "3f9c…", "model": "claude-sonnet-5-5", "effort": "low", "group": "Release 2.4" }

{
  "ok": true,
  "summary": "update_session → desk session 3f9c2a1e: model, effort, group",
  "session": "3f9c…",
  "settings": {
    "model": "claude-sonnet-5-5", "effort": "low", "mode": "agent", "auto_compact_window": "auto",
    "title": "Review: server/", "group": { "id": "grp_…", "name": "Release 2.4", "role": "member" },
    "thinking_enabled": true, "thinking_display": "summarized", "cwd": "/home/dev/projects/shop"
  },
  "changed": ["model", "effort", "group"]
}

更改为新文件夹还会说明 CLI 是否已重启（relaunched），新分组会以 groupCreated 返回。不会更改任何内容的调用会返回 changed: []，并且不征询任何人。note 携带智能体应了解的内容，例如窗口取了最接近的值，或窗口和思考仅适用于 Claude 会话（0.9.18 新增 包括 Claude API 会话）且对其他提供商不做任何更改。0.9.17 新增 DeepSeek 会话也会得到该说明，但那里的窗口确实生效，且 0 表示 400,000 个 token；thinking_enabled 不生效，因为 DeepSeek 会话始终思考。

谁能改什么。 智能体只能自由更改它自己的对话启动的会话：在此中继上，或当已配对的中继把此对话记录为启动者时在该中继上。任何其他会话——你的、另一个智能体的，或启动该智能体的那一个——都需要你先 Allow。提问卡片每个对话和每个中继征询一次，指明会话并列出更改（Model: … · Effort: … · Group: …）；Allow 涵盖该对话之后对那里此类会话的更改。Deny 以 REMOTE_RELAY_PERMISSION 拒绝调用；没有运行中轮次可供征询的对话会得到 REMOTE_RELAY_NO_ACTIVE_TURN。另一个中继自身也遵循相同规则。智能体绝不改动它所运行的对话。在 ask 和 plan 模式下，写入操作的常规卡片同样适用。

在更改任何内容之前，中继会在目标上检查整个调用：模型和推理强度、分组、文件夹，以及是否必须征询你。未知模型、未知分组 id、匹配两个分组的分组名、中继不可用的文件夹，或给繁忙会话的新文件夹，会在任何卡片之前拒绝调用，并且不会更改任何内容。

分组。

• 中继没有的名称会以该名称创建新分组。分组 id 必须存在（REMOTE_RELAY_UNKNOWN_GROUP）。
• 你创建的分组绝不会以这种方式被移除。当智能体移出其最后一个会话时，分组会保留，并在你的侧边栏中显示为 group · empty（分组 · 空）：从其菜单重命名或解散它，或让智能体再次命名它。没有任何东西会自行移除它。
• 智能体通过名称或启动会话创建的分组，一旦为空就会消失。

文件夹。 新的 cwd 会在该文件夹中重启会话的 CLI。当那里有排队或运行中的轮次，或有后台任务运行时，会以 REMOTE_RELAY_BUSY 拒绝：The session cannot move to another folder now: …。文件夹必须是中继可以使用的。尚未启动的会话会为它的首次启动保留该文件夹。如果 CLI 未重启，该文件夹仍会为它的下次启动保存，答复会说明这一点。不适用于 Claude Cloud，它在仓库的克隆上工作。

以此方式设置的模式会一直保持，直到下一个指定了另一模式或来自另一模式调用者的 send：不带 mode 的 send 会传递调用者自己的模式。

如果在其他步骤已写入后某一步失败，答复仍会在 changed 中列出已写入的内容。打开的页面会一次显示每个更改。运行较旧 OAR 的中继会返回 REMOTE_RELAY_UNSUPPORTED。

接受哪些模型 0.9.13 新增 #

send 或 create_session 中的 model 会在任何审批卡片之前，对照 New Chat（新建对话）为目标中继上的提供商提供的列表（即 relay_info 显示的同一列表）进行检查。不在其上的模型会以 REMOTE_RELAY_UNKNOWN_MODEL 被拒绝，且不会创建或发送任何内容：

Unknown model 'gpt-5-4' for Copilot on relay "build-box"; did you mean 'gpt-5.4'? Valid ids: … Nothing was sent.

结果还带有 suggestions（相近匹配）和 models（有效 id）。在 0.9.13 之前，这样的 id 会在另一个模型上创建会话，之后使用该 id 的 send 调用无法到达该会话。

0.9.19 新增 Copilot 的模型 id 使用点号：claude-opus-5.5，而不是 Claude 的 claude-opus-5-5。Copilot 会在创建任何内容之前拒绝其他提供商的 id：返回 COPILOT_MODEL_UNAVAILABLE 和最相近的匹配；在 create_session 中，如果只有另一个提供商列出该 id，则返回该提供商的代码，例如 CLAUDE_PROVIDER_REQUIRED。Copilot 会话也绝不会因为模型名称而转到别的提供商。

当实际运行的模型与所请求的不同时，结果的 modelNote 会说明。当目标中继还没有该提供商的列表时（其模型发现未运行或失败），模型会不检查地通过，modelNote 也会说明这一点。当另一个中继的智能体在其上启动会话时，中继也会拒绝未知的 Copilot 模型。

wait #

继续等待 send 或 create_session 未及时得到的回复。

{ "action": "wait", "relay": "build-box", "session": "3f9c…", "message_id": "b41e…", "wait_seconds": 300 }

等待与返回内容 #

send、create_session 和 wait 会按智能体在 wait_seconds 中所要求的时长等待回复，最长到智能体所在中继上的 Longest wait per tool call（每次工具调用的最长等待）设置（位于 Settings → Relays → Agent sessions）：默认 10 分钟，可在 2 到 60 分钟之间调整。当调用请求的时长超过中继允许的范围时，结果会在 note 中说明。时间到时，智能体会得到迄今已有的内容，并可以再次调用 wait。

等待中的轮次仍计入 Settings → General（设置 → 常规）下的 Max turn duration（单轮最长时长）。

结果的 status 说明另一个会话处于什么状态：

每个此类结果都带有 session 和 message_id，以及 openUrl（打开该会话的链接，当中继有链接时）。

引导另一个会话 #

answer_question #

回答另一个会话中正在等待的提问卡片。除非你让它们自己决定，否则智能体被告知要先征得你的同意。

choices 和 answer 二者必填其一。智能体不能回答自己的问题，也不能回答中继的审批卡片：那些是你的。0.9.16 新增 它也不能回答 ask：answer_question 会在调用任何人之前以 REMOTE_RELAY_FORBIDDEN 拒绝它。

{ "action": "answer_question", "relay": "build-box", "question_id": "q_7d2…", "choices": ["Merge"] }

stop #

停止会话中正在运行的轮次，就像界面中的 Stop（停止） 那样。结果说明是否请求了停止，或当时没有运行中的内容。

{ "action": "stop", "relay": "this", "session": "3f9c…" }

archive #

归档一个会话。

{ "action": "archive", "relay": "this", "session": "3f9c…" }

监视会话 #

0.9.10 新增 与其反复询问，智能体可以订阅会话并在那里发生事情时被唤醒。它在此中继（开启智能体会话时）和已配对的中继上都有效。

订阅只会通知。它不批准任何内容，也不回答任何内容；事件所要求的事仍像以前一样决定：由你决定，或由智能体在它本来就能做的范围内决定。

subscribe #

一个对话同一时间可以持有 20 个订阅。智能体自己的对话绝不会被监视。

{ "action": "subscribe", "sessions": ["3f9c…", "a12b…"], "events": ["question_asked", "error", "all_idle"] }

{
  "ok": true,
  "summary": "subscribe → desk: 2 sessions (sub_ab12cd34ef)",
  "subscription": {
    "id": "sub_ab12cd34ef",
    "sessions": [ { "id": "3f9c…", "title": "Review: server/" }, { "id": "a12b…", "title": "Review: web/" } ],
    "events": ["question_asked", "error", "all_idle"],
    "once": false,
    "stalledMinutes": 15
  }
}

更少的唤醒 0.9.16 新增 #

每次唤醒都是监视者的完整一轮。subscribe 的三个选项用于请求更少。question_asked、question_answered 和 error 绝不会被其中任何一个扣留；其他每个事件，包括 task_failed、stalled 和 all_idle，都会被扣留。

{
  "action": "subscribe",
  "sessions": ["all"],
  "exclude": ["77aa…"],
  "digest_minutes": 30,
  "quiet_hours": { "from": "23:00", "to": "06:00", "tz": "Europe/Berlin" }
}

• digest_minutes。 订阅的事件被汇总，每 N 分钟作为一条消息送达：第一条最早在订阅建立 N 分钟后，之后每条在上一条之后 N 分钟。消息会说 Digest of 4 events (subscription sub_… every 30 min; questions and errors come at once):。单个事件的摘要读起来就是那个事件。
• quiet_hours。 一个 IANA 时区中的每日本地时间窗口。from 和 to 是一天中的时间（HH:MM，00:00 到 23:59）且必须不同；窗口可以跨过午夜。其中发生的事会等待，并在窗口结束时作为一条消息送达，带有一行 Held during quiet hours (23:00–06:00 Europe/Berlin): 3 events, delivered now that the window has ended; questions and errors came at once. 其中不会产生心跳。摘要本应在窗口内投递的事件会移到窗口结束。
• exclude。 对 all 会话的订阅会忽略这些会话，对 all_idle、stalled 和心跳也是如此。带会话列表时会被拒绝：exclude goes with sessions ["all"] only; a list of sessions names what it watches。

时钟变化。 窗口跟随该时区的时钟。在时钟回拨、to 出现两次的夜晚，窗口在第一次结束，且不会在重复的那个小时再次进入。在时钟前拨并跳过 to 的夜晚，它在跳跃的那一刻结束。一个已知的限制：重复小时内的 from 会在第一遍时启动窗口，而在第二遍时，from 之前的分钟算作窗口之外。

错误的值会被拒绝并说明哪里错了，例如 quiet_hours from and to must be times of day as "HH:MM" (00:00 to 23:59)、quiet_hours from and to must differ，或 quiet_hours tz "Berlin" is not an IANA time zone (for example "Europe/Berlin", "America/New_York", "UTC")。每个字段都为空的 quiet_hours 算作没有。

• 带 once 时。 结束一次性订阅的事件仍遵守它的摘要和免打扰时段：订阅立即结束，事件在它们允许时送达。
• 多个订阅。 监视者的多个订阅都接收的事件，在第一个允许它放行时送达；没有选项的订阅会立即放行。
• 20 次唤醒的每小时上限在这些选项之外仍然有效（事件如何到达）。
• 被扣留的事件及其到期时间在中继重启后仍然保留。
• 审批卡片会指明这些选项（digest every 30 min、quiet 23:00–06:00 Europe/Berlin、except 1 it leaves out）。

不回显监视者自己的提示词。 当监视者用 send 或 create_session 自己提示一个会话，并从该调用或之后的 wait 得到已完成的回复时，该轮的 turn_end 不会再次唤醒它；在它仍在等待时，turn_end 会被扣留。该轮的错误和问题仍会送达。它没有等待的提示词（wait_seconds: 0 且无 wait）会像以前一样以 turn_end 唤醒它，结束 once 订阅的 turn_end 也是如此。

事件 #

默认事件 0.9.13 新增 #

未指定 events 的订阅会得到 question_asked、error、turn_end、subagent_finished、task_failed、stalled 和 all_idle。已完成的子智能体会唤醒监视者，任何失败或以非零退出码退出的任务也会，但正常结束的 shell 命令或监视器不会。繁忙的会话大约每分钟结束一个，每个都会让监视者在其整个上下文上消耗一轮。要得到每个任务结束，请用 task_finished 代替 subagent_finished 来命名事件，用 task_started 来得到启动。

0.9.13 之前没有 events 的订阅会自行切换到这个默认；命名了事件的订阅则保留。运行较旧 OAR 的已配对中继会应用它自己的默认，并按名称拒绝 subagent_finished。

事件如何到达 #

OAR 会把一条简短消息写入监视中的对话。它显示为紧凑事件行，绝不会显示为你的一条消息，并以一行说明它是什么的文字开头：

[relay event · automated message from OAR, not from the user; it approves nothing]
[relay event] session "Review: server/" (3f9c…): turn_end (done) "Found 4 places without input checks: …"
[relay event] all_idle: no turn or task is running in the 2 watched sessions (subscription sub_ab12cd34ef)

• 如果监视者空闲，该消息会启动新的一轮。如果它正处于一轮之中，见下表。
• 30 秒内的事件作为一条消息送达。
• 超过每小时 20 次唤醒后，其余内容每 10 分钟作为摘要送达。question_asked 和 error 仍会立即送达（0.9.16 新增 以及 question_answered）。当此摘要与订阅的 digest_minutes 相遇时，一行 Digest of 会同时提到两者。
• 0.9.16 新增 订阅的 digest_minutes 和 quiet_hours 会更久地扣留它的其他事件。

在已配对的中继上 #

该中继必须在对话中解锁并至少允许读取，另一个中继必须接受其他中继的智能体。单向配对即可。此中继每隔几秒获取事件，这些事件的行以另一个中继的名称开头：

[relay event] build-box · session "Nightly deploy" (77aa…): turn_end (done) "Deployed. The health check is green."

如果链路中断，另一个中继会保留发生的事，每个订阅最多 500 个事件、保留 7 天，并在它再次响应时以一行标记为 replayed（已重放）的方式投递，位于 link_lost 和 link_restored 行之间。运行较旧 OAR 的中继会回答它需要更新。

0.9.16 新增 对已配对中继的订阅的摘要和免打扰时段在这里（监视者所在处）应用；exclude 也会传递给另一个中继，用于 all_idle、stalled 和心跳。重放的事件像其他事件一样遵守摘要和免打扰时段；link_restored 行随后会说明其中有多少被扣留并稍后送达。运行较旧 OAR 的已配对中继不认识 exclude：此中继仍会丢弃那些会话的事件，但那个中继会在 all_idle、停滞和心跳列表中计算它们。

unsubscribe #

结束一个订阅，或用 "all" 结束该对话在指定中继上持有的每个订阅。

{ "action": "unsubscribe", "subscription_id": "sub_ab12cd34ef" }

list_subscriptions #

显示对话的订阅：活跃的以及过去一小时内结束的，附带原因。带 watcher 时，显示另一个对话的订阅，智能体在接管之前就是这样查看的。

{ "action": "list_subscriptions" }

每个订阅会显示它的会话、事件、once、match、stalledMinutes 和 heartbeatMinutes，0.9.16 新增 以及 digestMinutes、quietHours 和 exclude（当它有这些时）。活跃的订阅还会说明它的摘要或免打扰时段此刻扣留了多少事件（heldCount）以及其中第一个的到期时间（nextDeliveryAt，未扣留时为 null）。已结束的订阅仅在其最后一个事件仍被扣留时才说明这一点，例如在免打扰时段内触发的 once 之后。

{
  "id": "sub_ab12cd34ef",
  "scope": "all",
  "sessions": "all",
  "digestMinutes": 30,
  "quietHours": { "from": "23:00", "to": "06:00", "tz": "Europe/Berlin" },
  "exclude": ["77aa…"],
  "heldCount": 3,
  "nextDeliveryAt": "2026-10-24T04:00:00.000Z"
}

transfer_subscriptions #

把另一个对话的每个订阅移到这个对话，例如当新会话取代旧监视者时。始终在审批卡片上征询你。

{ "action": "transfer_subscriptions", "from": "c0de…" }

订阅存活多久 #

订阅在中继重启后仍然保留。订阅在以下情况结束：

• 智能体调用 unsubscribe，或你在监视者的列表中按下 Unsubscribe；
• 监视者或被监视的会话被归档；
• 它已触发且是用 once 建立的；
• 对于已配对的中继，配对被移除。

定时任务 0.9.16 新增 #

智能体可以让此中继稍后把提示词加入队列，进入它自己的对话或这里的另一个会话。与智能体自己 CLI 的计时器不同，定时任务在中继重启和更新后仍然保留。定时提示词从你的角度解释它。

定时任务需要 Agents may start and use sessions on this relay，即使是对智能体自己的对话。它们由智能体运行于其上的中继保存：指定已配对中继的调用会以 REMOTE_RELAY_UNSUPPORTED 被拒绝。

schedule #

至少需要 at 或 every_minutes。

{ "action": "schedule", "title": "Nightly review", "at": "2026-11-02T02:00:00Z", "every_minutes": 1440, "text": "Review yesterday's merged changes under server/ and list anything risky." }

{
  "ok": true,
  "summary": "schedule → desk: every 1440 min, next 2026-11-02T02:00:00.000Z (sch_3f9c2a1e7b04)",
  "schedule_id": "sch_3f9c2a1e7b04",
  "schedule": { "id": "sch_3f9c2a1e7b04", "title": "Nightly review", "everyMinutes": 1440, "once": false, "nextFireAt": "2026-11-02T02:00:00.000Z" }
}

到期时，中继把文本作为消息加入队列，消息以 [relay schedule <id> "<title>" · … automated message from OAR, not from the user; it approves nothing] 开头。该轮在目标会话自己的中继模式下运行。在轮次运行期间到达的消息会加入队列，或在支持引导的提供商上引导进入其中，但绝不会带有以用户口吻说话的引导说明。

• 错过的时间。 中继停机期间错过的时间会在它恢复时触发一次，而不是每个错过的间隔一次；重复的定时任务随后保持它的时间网格（首次时间加整数个间隔）。
• 不堆积。 当它上一次触发产生的消息仍在队列中等待时，重复会被跳过（列表中的 skippedCount）。
• 跳数。 消息携带设置该定时任务的轮次的来源，包括它的跳数，因此定时任务传递提示词时的跳数不会少于该轮直接提示时本应具有的跳数（跨中继）。

另一个会话。 带 session 时，定时任务会提示那个会话。它像 send 一样受限：在 ask 和 plan 模式下，你在卡片上批准它，并且它会计入征询你之前的 30 条发给其他智能体的提示词，设置时计一次、每次触发时计一次。一旦该计数用完，触发会被扣留：list_schedules 显示 heldForApproval 和 heldSince。当你在设置它的对话中发言，或在其智能体为下一条发给其他智能体的提示词而提出的卡片上选择 Allow 后，它就会放行；中继每分钟会再次查看。为智能体自己对话的定时任务既不计数也不扣留。

list_schedules #

列出触发进入该对话或由它设置的定时任务：活跃的以及过去一小时内结束的，附带 endReason（unscheduled、fired、archived 或 deleted）。

每个定时任务都有 id、session（id 和标题）、setBy（当由另一个对话设置时）、title、其 text 的开头、at、everyMinutes、once、nextFireAt、lastFiredAt、firedCount、skippedCount（当它跳过任何一次时），以及被扣留时的 heldForApproval 和 heldSince。

unschedule #

结束对话的一个定时任务：触发进入它的或由它设置的一个。

定时任务何时结束 #

定时任务在 once 时触发后、在 unschedule 或标题栏 ⏰ 列表中的 Cancel（取消）时结束，以及当它触发进入的会话或设置它的对话被归档或删除时结束。压缩会把两种都移到新对话。一个对话最多持有 20 个触发进入它的活跃定时任务，并最多为其他会话设置 20 个；超过后为 REMOTE_RELAY_SCHEDULE_LIMIT。

不阻塞的提问 0.9.16 新增 #

智能体可以向你提问并继续工作：问题会在它的会话和你的 Inbox（收件箱）中显示为卡片，智能体稍后得知答案。提问与 Inbox从你的角度解释它。

ask #

{ "action": "ask", "question": "Ship the migration tonight or wait for the review?", "options": ["Tonight", "Wait"], "recommendation": "Wait", "detail": "The review covers the index change; the rest is tested." }

{ "ok": true, "question_id": "ask_7d2…", "status": "pending", "summary": "ask → desk: question ask_7d2… pending" }

ask 立即返回 question_id 和 status: "pending"。智能体应继续做不依赖答案的事，并且在它待处理期间不要再次问同样的事。

答案。 当你回答或关闭问题时，智能体会得到中继事件 question_answered，附带 question_id、你的 answer、你选择的 choice、关闭时的 dismissed，以及 via（你回答所在的中继：保存该提问的那个，或你使用其 Inbox 的已配对中继）。它不需要订阅。该事件是紧急的：摘要或免打扰时段都不会扣留它。它是自动的，不批准其他任何内容，并且对于循环保护来说不算作你的消息：回答一个提问不会重置智能体可以互相发送的提示词计数。

谁回答。 只有你，在会话中或在 Inbox 中（此中继的，或与它配对的中继的）。answer_question 会拒绝一个提问。

准入条件。

• 关于智能体自己对话的提问、list_questions 和 withdraw 无需设置也无需提及。
• 带 session 时，智能体代另一个会话提问：在此中继上需要 Agents may start and use sessions on this relay，在已配对的中继上需要 Agents may 至少为 Read and prompt 且中继已解锁。这样的提问是写入：在 ask 和 plan 模式下你在卡片上批准它，并且它遵守跳数限制（跨中继）。循环保护不计入它。卡片显示在那个会话中，它和提问的对话都会得到答案。
• 关于已配对中继上会话的提问保存在那个中继上；此中继在它打开期间每 5 秒检查一次答案（当那个中继不响应时每 30 秒）。运行较旧 OAR 的中继会返回 REMOTE_RELAY_UNSUPPORTED。

每个提问的对话最多可有 20 个待处理提问，它们所关于的每个会话最多 20 个；超过后为 REMOTE_RELAY_QUESTION_LIMIT。提问不会过期。

list_questions #

列出对话的提问：待处理的，以及过去一天内已回答、已关闭或已撤回的，附带它们的状态和答案。带 session 时，列出关于另一个会话的提问。在已配对的中继上，它列出此对话在那里提出的提问；那里的 read_session 会列出会话的每个待处理问题。

withdraw #

撤回一个仍待处理的提问。只有提问的对话可以撤回它。

当它的会话被归档或删除时（不会通知任何人），以及当与保存它的中继的配对被移除时，提问也会结束。压缩会把它的提问移到新对话。

限制 #

错误 #

被拒绝的调用会返回智能体可以据此采取行动的 code。