Agent 迴圈（OpenClaw）

所謂 agentic loop，就是 agent 完整跑一輪的過程：接收訊息 → 組裝上下文 → 模型推論 → 執行工具 → 串流回覆 → 持久化儲存。這條路徑是把一則訊息轉換成實際操作與最終回覆的核心流程，同時確保 session 狀態保持一致。

在 OpenClaw 中，每個 session 一次只會有一個序列化的迴圈在跑，過程中會發出生命週期與串流事件——模型思考、呼叫工具、串流輸出，全都在這裡發生。本文說明這個迴圈從頭到尾是怎麼串起來的。

進入點

agent RPC 驗證參數、解析 session（sessionKey/sessionId）、持久化 session 中繼資料，然後立即回傳 { runId, acceptedAt }。
agentCommand 負責執行 agent：
- 解析模型 + thinking/verbose 預設值
- 載入 skills 快照
- 呼叫 runEmbeddedPiAgent（pi-agent-core 執行環境）
- 如果內嵌迴圈沒有發出生命週期結束/錯誤事件，則由這裡補發
runEmbeddedPiAgent：
- 透過 per-session + 全域佇列序列化執行
- 解析模型 + 驗證設定檔，建立 pi session
- 訂閱 pi 事件，串流 assistant/tool 的差量更新
- 強制逾時 → 超時則中止執行
- 回傳 payload + 用量中繼資料
subscribeEmbeddedPiSession 負責將 pi-agent-core 事件橋接到 OpenClaw agent 串流：
- 工具事件 => stream: "tool"
- 助理差量 => stream: "assistant"
- 生命週期事件 => stream: "lifecycle"（phase: "start" | "end" | "error"）
agent.wait 使用 waitForAgentJob：
- 等待 runId 的生命週期結束/錯誤事件
- 回傳 { status: ok|error|timeout, startedAt, endedAt, error? }

OpenClaw 有兩套 hook 系統：

請參閱 Hooks 取得設定與範例。

這些在 agent 迴圈或 gateway 管線內部執行：

before_model_resolve：在 session 之前執行（沒有 messages），可在模型解析前確定性地覆寫 provider/model。
before_prompt_build：在 session 載入後執行（有 messages），可注入 prependContext、systemPrompt、prependSystemContext 或 appendSystemContext。用 prependContext 注入每回合的動態文字，用 system-context 欄位注入應放在系統提示詞空間的穩定指引。
before_agent_start：相容性 hook，可能在上述任一階段執行；建議改用上面明確的 hook。
agent_end：在完成後檢視最終訊息列表和執行中繼資料。
before_compaction / after_compaction：觀察或標註壓縮週期。
before_tool_call / after_tool_call：攔截工具參數/結果。
tool_result_persist：在工具結果寫入 session 對話記錄之前，同步轉換其內容。
message_received / message_sending / message_sent：入站 + 出站訊息 hook。
session_start / session_end：session 生命週期邊界。
gateway_start / gateway_stop：gateway 生命週期事件。

請參閱 Plugins 瞭解 hook API 與註冊細節。

最終 payload 由以下內容組裝：
- 助理文字（以及可選的推理內容）
- 行內工具摘要（在 verbose + 允許的條件下）
- 模型出錯時的助理錯誤文字
NO_REPLY 被視為靜默 token，會從出站 payload 中過濾掉。
訊息工具的重複內容會從最終 payload 列表中移除。
如果沒有可渲染的 payload 且某個工具出錯，會發出備用的工具錯誤回覆（除非訊息工具已經發送了使用者可見的回覆）。

agent.wait 預設：30 秒（僅等待）。可用 timeoutMs 參數覆寫。
Agent 執行環境：agents.defaults.timeoutSeconds 預設 600 秒；在 runEmbeddedPiAgent 的中止計時器中強制執行。