Agent Loop（OpenClaw）¶

Agentic loop 是代理程式一次完整且「真實」的執行流程：輸入接收 → 情境組裝 → 模型推論 → 工具執行 → 串流回覆 → 持久化。這是一條權威路徑，將一則訊息轉化為行動與最終回覆，同時維持工作階段狀態的一致性。 It’s the authoritative path that turns a message into actions and a final reply, while keeping session state consistent.

在 OpenClaw 中，一個 loop 是每個工作階段一次、序列化的執行，會在模型思考、呼叫工具與串流輸出時發出生命週期與串流事件。本文件說明這個真實 loop 如何端到端地連接運作。 This doc explains how that authentic loop is wired end-to-end.

進入點¶

• Gateway RPC：agent 與 agent.wait。
• CLI：agent 指令。

運作方式（高層）¶

1. agent RPC 會驗證參數、解析工作階段（sessionKey/sessionId）、持久化工作階段中繼資料，並立即回傳 { runId, acceptedAt }。
2. agentCommand 會執行 agent： - 解析模型與 thinking/verbose 的預設值 - 載入 Skills 快照 - 呼叫 runEmbeddedPiAgent（pi-agent-core runtime） - 若內嵌 loop 未發出事件，則送出 lifecycle end/error
3. runEmbeddedPiAgent： - 透過每個工作階段與全域佇列將執行序列化 - 解析模型與驗證設定檔，並建立 Pi 工作階段 - 訂閱 pi 事件並串流 assistant/tool 的增量 - 強制執行逾時機制 → 若超過時限則中止執行 - 回傳負載資料與使用量中繼資料
4. subscribeEmbeddedPiSession 將 pi-agent-core 事件橋接到 OpenClaw 的 agent 串流： - 工具事件 ⇒ stream: "tool" - assistant 增量 ⇒ stream: "assistant" - 生命週期事件 ⇒ stream: "lifecycle"（phase: "start" | "end" | "error"）
5. agent.wait 使用 waitForAgentJob： - 等待 lifecycle end/error 以取得 runId - 回傳 { status: ok|error|timeout, startedAt, endedAt, error? }

佇列與並行處理¶

• 每個工作階段鍵（session lane）的執行會被序列化，並可選擇性地透過全域 lane 進行序列化。
• 這可防止工具或工作階段發生競爭狀況，並維持工作階段歷史的一致性。
• 訊息頻道可選擇佇列模式（collect/steer/followup）以餵入此 lane 系統。 請參見 Command Queue。 See Command Queue.

工作階段與工作空間準備¶

• 解析並建立工作空間；沙箱隔離的執行可能會重新導向至沙箱工作空間根目錄。
• 技能會被載入（或從快照中重用），並注入至 env 與提示中。
• Bootstrap/context files are resolved and injected into the system prompt report.
• 取得工作階段寫入鎖；在開始串流前會開啟並準備 SessionManager。

Prompt assembly + system prompt¶

• 系統提示詞由 OpenClaw 的基礎提示詞、Skills 提示詞、啟動情境與每次執行的覆寫所組成。
• Model-specific limits and compaction reserve tokens are enforced.
• 模型實際看到的內容請參見 System prompt。

掛鉤點（可攔截的位置）¶

OpenClaw 有兩套掛鉤系統：

• Internal hooks (Gateway hooks): event-driven scripts for commands and lifecycle events.
• Plugin hooks: extension points inside the agent/tool lifecycle and gateway pipeline.

內部掛鉤（Gateway 掛鉤）¶

• agent:bootstrap：在系統提示詞最終確定前、建立啟動檔案期間執行。 可用於新增／移除啟動情境檔案。 Use this to add/remove bootstrap context files.
• Command 掛鉤：/new、/reset、/stop，以及其他指令事件（見 Hooks 文件）。

設定與範例請參見 Hooks。

外掛掛鉤（agent + Gateway 生命週期）¶

這些會在 agent loop 或 Gateway 管線內執行：

• before_agent_start：在執行開始前注入情境或覆寫系統提示詞。
• agent_end：完成後檢視最終訊息清單與執行中繼資料。
• before_compaction / after_compaction：觀察或標註壓縮循環。
• before_tool_call / after_tool_call：攔截工具參數／結果。
• tool_result_persist：在寫入工作階段逐字稿前，同步轉換工具結果。
• message_received / message_sending / message_sent：入站＋出站訊息掛鉤。
• session_start / session_end：工作階段生命週期邊界。
• gateway_start / gateway_stop：Gateway 生命週期事件。

掛鉤 API 與註冊細節請參見 Plugins。

串流與部分回覆¶

• assistant 增量由 pi-agent-core 串流並以 assistant 事件發出。
• 區塊串流可在 text_end 或 message_end 上發出部分回覆。
• Reasoning streaming can be emitted as a separate stream or as block replies.
• See Streaming for chunking and block reply behavior.

工具執行與訊息工具¶

• 工具的開始／更新／結束事件會在 tool 串流上發出。
• Tool results are sanitized for size and image payloads before logging/emitting.
• 會追蹤訊息工具的送出，以抑制重複的 assistant 確認訊息。

Reply shaping + suppression¶

• 最終負載由以下組成：
• assistant 文字（與可選的推理）
• 內嵌工具摘要（在 verbose 且允許時）
• 模型出錯時的 assistant 錯誤文字
• NO_REPLY is treated as a silent token and filtered from outgoing payloads.
• 訊息工具的重複項會從最終負載清單中移除。
• If no renderable payloads remain and a tool errored, a fallback tool error reply is emitted (unless a messaging tool already sent a user-visible reply).

Compaction + retries¶

• Auto-compaction emits compaction stream events and can trigger a retry.
• 重試時，會重設記憶體中的緩衝區與工具摘要，以避免重複輸出。
• See Compaction for the compaction pipeline.

事件串流（目前）¶

• lifecycle：由 subscribeEmbeddedPiSession 發出（並由 agentCommand 作為後備）
• assistant：來自 pi-agent-core 的串流增量
• tool：來自 pi-agent-core 的串流工具事件

聊天頻道處理¶

• assistant 增量會緩衝為聊天 delta 訊息。
• 在 lifecycle end/error 時會送出聊天 final。

逾時¶

• agent.wait default: 30s (just the wait). timeoutMs param overrides.
• Agent runtime：agents.defaults.timeoutSeconds 預設 600 秒；由 runEmbeddedPiAgent 的中止計時器強制執行。

Where things can end early¶

• Agent 逾時（中止）
• AbortSignal（取消）
• Gateway 斷線或 RPC 逾時
• agent.wait 逾時（僅等待，不會停止 agent）