relay_tool 0.9.4 新增

有了 relay_tool，agent 就能操作其他 session：列出並讀取它們、對其中一個下提示、啟動新的 session、等待回覆、回答另一個 agent 提出的問題、停止或封存 session，還可以要求在它監看的 session 發生事情時被喚醒。

它能連到兩種中繼：

• 此中繼，也就是 agent 本身執行所在的中繼。agent 可以把部分任務交給這裡的其他 session。在你啟用之前都是關閉的。0.9.7 新增
• 配對的中繼，也就是你已和此中繼配對的其他 OAR 中繼，例如你工作站上的中繼和伺服器上的中繼。在每個對話中都是鎖定的，直到你提到該中繼。

每個提供此工具的供應商，工具都相同；哪些供應商提供、用什麼名稱，請見依供應商。

名稱 0.9.18 新增 #

在 0.9.17 及更早版本中，這個工具叫做 remote_relay。現在它在每個供應商上都列為 relay_tool（Claude 的 agent 看到的是 mcp__relay__relay_tool），動作和欄位都相同。以舊名稱寫下的工具記錄行，仍會顯示為這個工具。

• 你更新時正在執行的 session。 session 的 agent 在它的 worker 啟動時取得工具清單，而 worker 在中繼重新啟動期間會持續執行。這類 session 的 agent 仍以 remote_relay 的名稱持有這個工具，直到它的 worker 再次啟動，例如在 Kill session（強制結束 session）之後。它的呼叫照樣有效：不論用哪個名稱，都以相同方式到達中繼。中繼以 Linux 服務執行時，worker 可能會隨中繼一起停止，回來時就會使用新名稱。
• OAR 自己的 MCP 伺服器（Grok 和 Copilot 的擴充功能引擎使用它）仍會執行對 remote_relay 的呼叫，但不再列出它。
• 你自己的指示。 如果你的指示、權限規則或 hook 提到 remote_relay 或 mcp__relay__remote_relay，請改成 relay_tool 或 mcp__relay__relay_tool：在 OAR 的 MCP 伺服器之外，舊名稱會被拒絕。

你會看到什麼 #

• 核准卡片。 在 agent 於對話中啟動第一個 session 之前、第一次監看 session 之前，以及對話處於 ask 或 plan 中繼模式時的每個寫入動作之前，提問卡片都會先詢問。
• 回覆中的工具呼叫。 agent 的活動會以 🛰️ 顯示每次呼叫，以及動作、中繼和 session。
• 「via agent」（經由 agent）。agent 啟動的 session 會在對話清單中和它的標題下方帶有 via agent · "title"（經由 agent · 「title」），寫出 agent 所在的對話。0.9.11 新增 它位於該對話下的 session 群組中，0.9.16 新增 或位於 agent 指定的現有群組中。
• 「↗ from …」（來自 …）。agent 傳送的提示，在接收端會帶有一個徽章，寫出傳送端的中繼、session 和模型。
• 監看。 監看其他 session 的對話，標題列會顯示 watching N sessions（正在監看 N 個 session）；小標籤會列出它的訂閱，每個訂閱都有一個 Unsubscribe（取消訂閱）按鈕。被監看的 session 會顯示 watched（監看）徽章。

啟用 #

只要下列至少一項成立，agent 就會取得 relay_tool：

session 在它的 agent 處理程序啟動時，才會知道自己是否取得這個工具，所以已經在執行的對話，可能要等它的 agent 再次啟動後才會有這個工具。

指定中繼 #

除了 list_relays 以外，每個動作都作用於一個中繼，以 relay 指定：

• "this"，或此中繼自己的名稱，就是 agent 執行所在的中繼。不需要提到它。
• 配對的中繼以它的中繼名稱或主機指定，和 list_relays 顯示的一樣。

四個訂閱動作，以及 0.9.16 新增 三個排程動作和三個提問動作，可以省略 relay，此時代表 "this"。排程只能在此中繼上運作。

鎖定與解鎖 #

配對的中繼在對話中會保持 locked（已鎖定），直到發生下列其中一件事：

• 你在自己的某則訊息中提到它：輸入 @ 並選取它，或寫出它的名稱或主機名稱。名稱是 IP 位址或 localhost 的中繼，只有前面加上 @ 才算數。
• 該中繼上的 agent 在對話中寫入訊息。之後該中繼就會開放，讓這裡的 agent 可以回答。

一旦解鎖，它在對話的其餘部分都保持開放。鎖定的中繼會拒絕 list_relays 以外的每個動作；agent 會被告知要請你提到該中繼。

權限與核准 #

配對的中繼允許什麼 #

每個配對的中繼在 Settings → Relays 下都有一個 Agents may（agent 可以）等級。新的配對一開始是 Full（完整存取）。

list_relays 不需要任何等級。此中繼本身一律算作 Full。

在另一端，Accept prompts from other relays' agents（接受其他中繼 agent 的提示）（配對中繼上的 Settings → Relays）會關閉其他中繼的 agent 在那裡可能變更或監看的一切：對 session 下提示、啟動、回答、停止和封存 session，以及訂閱它們。列出和讀取 session、讀取任務輸出、等待、relay_info 和 usage 仍然可用。

什麼時候會詢問你 #

此中繼上 session 的規則 #

• 最多 4 個同時工作。 在一個對話的 agent 啟動的 session 中，最多 4 個可以同時有排入佇列或執行中的回合。第五個會被拒絕，直到其中一個完成。
• 只有一層。 由 agent 建立的 session 本身不能建立 session，0.9.16 新增 除非你為它開啟了 Agents in this conversation may start sessions（允許此對話中的 agent 啟動 session）。此時 list_sessions 和 read_session 會顯示 "mayCreateSessions": true。沒有任何 agent 能設定這個開關。
• 不能對自己。 agent 不能對它所在的對話 send、wait、stop 或 archive，也不能回答自己的問題，0.9.16 新增 或變更它的設定。
• 你的帳戶。 agent 啟動的 session 使用此中繼的供應商帳戶，並計入它們的用量。
• 中繼永遠不會自行封存這些 session。它們會留在你的清單中，直到你封存或刪除它們，或由 agent 封存其中一個。

跨中繼 #

• 已經跨過兩個中繼的提示，不會再傳給第三個中繼，除非該中繼是你自己解鎖的。讀取和等待永遠不受此限制。
• 另一個 agent 收到的提示，開頭會有一行說明是另一個 agent 在和它對話： [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 或空清單）算作沒有引數，因為有些供應商會傳送每個欄位。

尋找中繼與 session #

list_relays #

列出配對的中繼，包含 name、url、online、version、permission 和 unlocked。agent session 開啟時，此中繼會排在最前面，並標示 "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 #

中繼提供什麼，讓 agent 可以為新 session 選擇供應商、模型和資料夾：它的名稱、版本和平台、是否接受 agent 提示、每個供應商及其預設模型、模型和 reasoning effort、預設和最近使用的工作資料夾，以及中繼模式。

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

0.9.16 新增 它也會在 groups 中列出中繼的 session 群組，也就是在那裡呼叫 create_session 時可以指定的群組：每個都有 id、name（側邊欄顯示的名稱；沒人命名的群組則是主 session 的標題）和 memberCount，最近有活動的群組排在最前面。只會列出至少有一個未刪除 session 的群組，最多 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 新增 #

中繼上每個供應商的方案還剩多少；請見 Check Usage（檢查用量）。它讓 agent 在開始會花錢的工作之前先檢查：每個供應商的狀態及其計量（已用、額度、剩餘、使用率、重設時間），以及那裡是否有 Claude 用量上限暫停了回合。未設定或未追蹤的供應商會說明這點。絕不包含帳戶名稱、位址和 token。

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

list_sessions #

列出 session，包含 id、title、provider、model、state、cwd、最後活動時間和訊息數。state 為 running_turn、background_only（agent 已回答，背景工作仍在執行）或 idle；tasks 列出背景 agent 和 shell 任務。

0.9.11 新增 session 群組中的 session 也有 group：它的 id、name，以及 session 在其中的 role，head 或 member。0.9.16 新增 create_session 可以把它建立的 session 放進現有的群組，而 update_session 可以把 session 移進某個群組（包括新群組），或移出群組。重新命名、解散和重新排列群組仍由你負責。

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

read_session #

讀取 session 最近的訊息，以及那裡正在發生的事：它的 state、仍在撰寫中的回覆（inFlight），以及任何等待回答的 pendingQuestions（0.9.16 新增 每個都有 kind：ask 提問為 ask，session 正在等待的卡片為 ask_user）。0.9.11 新增 對群組中的 session，group 會加上其他成員，最多 50 個，每個都有 id、title、role、state，已封存的還有 archived。

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

0.9.12 新增 session 的每個 tasks 也有它的 taskId、output（是否有可用 read_task_output 讀取的輸出），而輸出寫在檔案中的指令還有 health：執行期間的 minutesSinceOutput、quiet 和 quietAfterMinutes（中繼的靜默設定），以及有測試執行時的 counts。

read_task_output 0.9.12 新增 #

讀取背景 shell 指令或 monitor 輸出的結尾，也就是任務主控台顯示的同一份輸出：任務執行期間，以及結束後一小時內都可以讀取。agent 不必詢問啟動它的 agent，就能查看另一個中繼上的建置是否仍在忙、已經靜默，或有測試失敗。

結果包含 task（描述、類型、開始時間、status 和 exitCode）、tail（這些行，為不含顏色的純文字，重複的行標示為 [×N]）、前面還有更多內容時的 truncated、任務執行期間的 stall（距離上次輸出的分鐘數，以及依中繼設定判斷的 quiet），以及輸出為測試執行時的 counts，內含執行器及其通過、失敗和略過的測試數。憑證會像在主控台中一樣被遮蔽。note 會說明何時只有輸出的結尾存在、何時輸出已不在，或何時已向 agent 的處理程序索取輸出、應在幾秒後重試呼叫。

{ "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 #

把提示排入現有 session 的佇列，並等待回覆。

{ "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 session 的計費方式 0.9.18 新增 #

帶有 provider 的 send 會在一次呼叫中，把 Claude session 在訂閱和 Claude API 金鑰之間移動，並傳送訊息：被拒絕的切換不會傳送任何東西，被拒絕的訊息也不會切換任何東西。另一種計費方式必須已在目標中繼上設定好。需要詢問時，核准卡片會寫著 Switches billing to API key 或 Switches billing to subscription。

• 目標中繼拒絕切換時，若是那裡未設定 Claude API 或 Claude，或已達到每月上限，會回傳 REMOTE_RELAY_PROVIDER_UNAVAILABLE；若是 session 的模型不在另一方的清單上，會回傳 REMOTE_RELAY_UNKNOWN_MODEL。remoteCode 帶有該中繼自己的代碼，例如 CLAUDE_API_CAP_REACHED。
• 0.9.18 之前的中繼無法切換：呼叫會以 REMOTE_RELAY_UNSUPPORTED 被拒絕，也不會傳送任何東西。
• 沒有 provider 時，session 保留它的計費方式。對使用金鑰、且已達上限的 session 呼叫 send 會被拒絕，也不會排入任何東西：請以 provider: "claude" 傳送，把它移到訂閱，或請使用者調高上限。

create_session #

啟動新的 session 並給它第一個提示。新的 session 對啟動它的對話一無所知，所以提示必須能獨立成立。

和 send 一樣接受 text、wait_seconds、mode、model 和 effort，另外還有：

agent 沒有指定的部分，只要目標中繼提供，就沿用它所在的 session。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 session 接受的是儲存庫，而不是資料夾：

{
  "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 相同，再加上 session 啟動時使用的設定：provider、model、mode、effort、title，雲端 session 還有 repo / branch。0.9.16 新增 它也有 group，也就是新 session 加入的 session 群組，格式和 list_sessions 顯示的一樣（id、name、role），或為 null。

放進群組 0.9.16 新增 #

沒有 group 時，在此中繼上啟動的 session 會加入啟動它的 session 所在的群組，或以那個 session 為主 session 建立一個群組。在配對中繼上啟動的 session 不會加入任何群組。

有 group 時，新 session 會改為加入那個現有的群組，不論在此中繼還是配對的中繼上。agent 以群組的 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: …）；沒有回應或拒絕 token 的中繼，則以它平常的代碼回應。

session 已建立、但沒有進入要求的群組時，結果會有 groupWarning，它的 summary 以 (no group: …) 結尾，而 note 會要求 agent 告訴你。之後你可以手動移動這個 session。

create_session 只接受現有的群組。要把 session 放進新群組，agent 之後要以那個名稱呼叫 update_session。重新命名、解散和重新排列群組仍由你負責。

update_session 0.9.16 新增 #

變更另一個 session 之後回合的設定，而不對它下提示，並回應它現在的設定以及變更了什麼。它可用於此中繼和配對的中繼。

至少需要一項設定。其他任何引數都會被拒絕，且不會變更任何東西。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 帶有 agent 應該知道的事，例如視窗被取為最接近的值，或視窗和思考設定只適用於 Claude session（0.9.18 新增 包括 Claude API session），在其他供應商上不會改變任何東西。0.9.17 新增 DeepSeek session 也會收到這則註記，但在那裡視窗確實會生效，而 0 代表 400,000 token；thinking_enabled 則不會生效，因為 DeepSeek session 一律會思考。

誰可以變更什麼。 agent 只能自由變更由它自己的對話啟動的 session：在此中繼上，或在配對的中繼上且該中繼記錄這個對話為啟動者。其他任何 session，不論是你的、另一個 agent 的，或啟動這個 agent 的那個，都需要先取得你的 Allow。提問卡片會針對每個對話和中繼詢問一次，寫出 session 並列出變更（Model: … · Effort: … · Group: …）；Allow 涵蓋該對話之後在那裡對這類 session 的變更。Deny 會以 REMOTE_RELAY_PERMISSION 拒絕呼叫；沒有執行中的回合可以詢問的對話，會收到 REMOTE_RELAY_NO_ACTIVE_TURN。另一個中繼本身也遵守同樣的規則。agent 永遠不會變更它所在的對話。在 ask 和 plan 模式下，寫入動作平常的卡片也同樣適用。

在任何變更之前，中繼會在目標上檢查整個呼叫：模型和 effort、群組、資料夾，以及是否必須詢問你。未知的模型、未知的群組 id、符合兩個群組的群組名稱、中繼不得使用的資料夾，或為忙碌中的 session 指定新資料夾，都會在任何卡片出現之前拒絕呼叫，且不會變更任何東西。

群組。

• 中繼沒有的名稱，會建立以該名稱命名的新群組。群組 id 必須存在（REMOTE_RELAY_UNKNOWN_GROUP）。
• 你建立的群組絕不會以這種方式被移除。當 agent 移出它的最後一個 session 時，群組會保留，並在你的側邊欄中顯示為 group · empty（群組 · 空）：你可以從它的選單重新命名或解散它，或讓 agent 再次指定它。沒有任何東西會自行移除它。
• agent 建立的群組（不論是以名稱建立，還是透過啟動 session 建立），一旦變空就會消失。

資料夾。 新的 cwd 會讓 session 的 CLI 在那個資料夾重新啟動。當那裡有回合排入佇列或正在執行，或有背景任務在執行時，會以 REMOTE_RELAY_BUSY 拒絕：The session cannot move to another folder now: …。資料夾必須是中繼可以使用的。尚未啟動的 session 會保留這個資料夾，供第一次啟動時使用。如果 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 會在另一個模型上建立 session，之後用該 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 session 也絕不會因為模型名稱而轉到別的供應商。

實際執行的模型與要求的不同時，結果的 modelNote 會說明。目標中繼還沒有該供應商的清單時（它的模型探索尚未執行或失敗），模型會不經檢查直接傳遞，modelNote 也會說明。另一個中繼的 agent 在某個中繼上啟動 session 時，該中繼也會拒絕未知的 Copilot 模型。

wait #

繼續等待 send 或 create_session 沒有及時取得的回覆。

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

等待與回傳內容 #

send、create_session 和 wait 會依 agent 在 wait_seconds 中要求的時間等待回覆，最長為 agent 所在中繼上的 Longest wait per tool call（每次工具呼叫的最長等待）（Settings → Relays → Agent sessions）：預設 10 分鐘，可在 2 到 60 分鐘之間調整。呼叫要求的時間超過中繼允許時，結果會在 note 中說明。時間到時，agent 會取得目前已有的內容，並可以再次呼叫 wait。

等待中的回合仍會計入 Settings → General（設定 → 一般）下的 Max turn duration（回合最長時間）。

結果的 status 說明另一個 session 目前的狀態：

每個這樣的結果都帶有 session 和 message_id，中繼有連結時還有 openUrl，也就是開啟該 session 的連結。

操控另一個 session #

answer_question #

回答另一個 session 中正在等待的提問卡片。agent 會被告知先問你，除非你告訴過它們可以自己決定。

choices 和 answer 必須擇一。agent 不能回答自己的問題，也不能回答中繼的核准卡片：那些由你回答。 0.9.16 新增 它也不能回答 ask 提問：answer_question 會在呼叫任何人之前，以 REMOTE_RELAY_FORBIDDEN 拒絕。

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

stop #

停止 session 中正在執行的回合，就像 UI 中的 Stop（停止）。結果會說明是已要求停止，還是沒有任何東西在執行。

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

archive #

封存 session。

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

監看 session #

0.9.10 新增 agent 不必一再詢問，而可以訂閱 session，在那裡發生事情時被喚醒。這可用於此中繼（需開啟 agent session）和配對的中繼。

訂閱只負責通知。它不核准任何事，也不回答任何事；事件所要求的事，仍和以前一樣由你決定，或由 agent 在它原本就被允許的範圍內決定。

subscribe #

一個對話同時最多可有 20 個訂閱。agent 自己的對話永遠不會被監看。

{ "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 session 的訂閱會忽略這些 session，all_idle、stalled 和心跳也一樣。搭配 session 清單時會被拒絕：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 對 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。已結束的背景 subagent 會喚醒監看者，任何失敗或以非零值結束的任務也會，但順利結束的 shell 指令或 monitor 不會。忙碌的 session 大約每分鐘就會結束一個，而每一個都會讓監看者在它的完整上下文上花掉一個回合。要取得每個任務的結束，請指定事件，以 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 會把它的其他事件暫緩更久。

在配對的中繼上 #

該中繼必須在對話中已解鎖並至少允許讀取，而另一個中繼必須接受其他中繼的 agent。單向配對就足夠。此中繼每隔幾秒取得一次事件，而這些事件的行以另一個中繼的名稱開頭：

[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：此中繼仍會丟棄那些 session 的事件，但那個中繼會在 all_idle、停滯判斷和心跳的清單中計入它們。

unsubscribe #

結束一個訂閱，或以 "all" 結束對話在指定中繼上持有的每個訂閱。

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

list_subscriptions #

顯示對話的訂閱：使用中的訂閱，以及最近一小時內結束的訂閱和結束原因。搭配 watcher 時，會顯示另一個對話的訂閱，agent 就是這樣在接手之前先查看。

{ "action": "list_subscriptions" }

每個訂閱都會顯示它的 session、事件、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 #

把另一個對話的每個訂閱移到這個對話，例如新的 session 取代舊的監看者時。一律會以核准卡片詢問你。

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

訂閱的存續期間 #

訂閱在中繼重新啟動後仍會保留。訂閱會在下列情況結束：

• agent 呼叫 unsubscribe，或你在監看者的清單中按下 Unsubscribe；
• 監看者或被監看的 session 被封存；
• 它已觸發，且建立時帶有 once；
• 對配對的中繼而言，配對被移除。

排程 0.9.16 新增 #

agent 可以讓此中繼稍後把提示排入佇列，排進它自己的對話或這裡的另一個 session。不同於 agent 自己 CLI 的計時器，排程在中繼重新啟動和更新後仍會保留。排程提示從你的角度說明這項功能。

排程需要 Agents may start and use sessions on this relay，即使是為 agent 自己的對話排程也一樣。排程由 agent 所在的中繼保存：指定配對中繼的呼叫會以 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] 開頭的訊息。回合會以目標 session 自己的中繼模式執行。回合執行期間到達的訊息會排入佇列，或在支援導正的供應商上導正進回合，但絕不會帶有以使用者口吻說話的導正註記。

• 錯過的時間。 中繼停機期間經過的時間，會在中繼恢復時觸發一次，而不是每個錯過的間隔各觸發一次；重複的排程之後會繼續依循它的時間格（第一次的時間加上整數個間隔）。
• 不會堆積。 前一次觸發的訊息仍在佇列中等待時，會略過這次重複（清單中的 skippedCount）。
• 跳數。 訊息帶有設定排程那個回合的來源資訊，包括它的跳數，所以排程傳遞的提示，記錄的跳數不會比那個回合直接下的提示少（跨中繼）。

另一個 session。 有 session 時，排程會對那個 session 下提示。它和 send 受到同樣的管制：在 ask 和 plan 模式下，你要在卡片上核准它，而且它會計入詢問你之前對其他 agent 的 30 個提示，設定時計一次，每次觸發時再各計一次。這個額度用完後，觸發會被暫緩：list_schedules 會顯示 heldForApproval 和 heldSince。當你在設定它的對話中寫入訊息，或在它的 agent 為下一個對其他 agent 的提示所提出的卡片上選擇 Allow 時，它就會送出；中繼每分鐘會再檢查一次。為 agent 自己的對話設定的排程既不計數，也不會被暫緩。

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（取消）時，以及它觸發的 session 或設定它的對話被封存或刪除時。壓縮則會把這兩種排程移到新的對話。一個對話最多可有 20 個觸發到它之中的使用中排程，並最多可為其他 session 設定 20 個；超過時會回傳 REMOTE_RELAY_SCHEDULE_LIMIT。

不會卡住的提問 0.9.16 新增 #

agent 可以向你提問，然後繼續工作：問題會以卡片形式顯示在它的 session 和你的 Inbox（收件匣）中，agent 稍後才會得知答案。提問與 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"。agent 應繼續處理不依賴答案的工作，並且在問題待處理期間，不要再問同樣的問題。

答案。 當你回答或關閉問題時，agent 會收到中繼事件 question_answered，包含 question_id、你的 answer、你選的 choice、你關閉它時的 dismissed，以及 via，也就是你回答時所在的中繼：保存這個 ask 提問的中繼，或你使用其 Inbox 的配對中繼。它不需要訂閱。這個事件是緊急的：任何摘要或勿擾時段都不會暫緩它。它是自動產生的，不會核准其他任何事，而且在迴圈保護中不算作你傳送的訊息：回答 ask 提問並不會重設 agent 彼此可傳送之提示的計數。

誰來回答。 只有你，在 session 中或在 Inbox 中（此中繼的，或與它配對之中繼的）。answer_question 會拒絕 ask 提問。

管制。

• 關於 agent 自己對話的 ask 提問，以及 list_questions 和 withdraw，不需要任何設定，也不需要提到中繼。
• 有 session 時，agent 是代另一個 session 提問：在此中繼上需要 Agents may start and use sessions on this relay，在配對的中繼上需要 Agents may 至少為 Read and prompt，且該中繼已解鎖。這樣的 ask 提問屬於寫入：在 ask 和 plan 模式下，你要在卡片上核准它，而且它遵守跳數限制（跨中繼）。迴圈保護不會計入它。卡片顯示在那個 session 中，而那個 session 和提問的對話都會收到答案。
• 關於配對中繼上某個 session 的 ask 提問，會保存在該中繼上；在它未結束期間，此中繼每 5 秒檢查一次是否已有答案（該中繼沒有回應時則每 30 秒）。執行較舊 OAR 的中繼會回應 REMOTE_RELAY_UNSUPPORTED。

每個提問的對話最多可有 20 個待處理的 ask 提問，每個被詢及的 session 也最多 20 個；超過時會回傳 REMOTE_RELAY_QUESTION_LIMIT。ask 提問不會過期。

list_questions #

列出對話的 ask 提問：待處理的，以及最近一天內已回答、已關閉或已收回的，連同它們的狀態和答案。搭配 session 時，列出關於另一個 session 的 ask 提問。在配對的中繼上，它會列出這個對話在那裡提出的 ask 提問；那裡的 read_session 則會列出 session 每個待處理的問題。

withdraw #

收回仍在待處理的 ask 提問。只有提問的對話可以收回它。

ask 提問也會在它的 session 被封存或刪除時結束（不會通知任何人），以及在與保存它的中繼之間的配對被移除時結束。壓縮會把它的 ask 提問移到新的對話。

限制 #

錯誤 #

被拒絕的呼叫會回傳一個 agent 可以據以處理的 code。