代理程式迴圈

代理迴圈是每個工作階段序列化的執行流程，會將訊息轉換為 動作與回覆：接收、脈絡組裝、模型推論、工具 執行、串流、持久化。

​

進入點

• 閘道 RPC：agent 和 agent.wait。
• 命令列介面：openclaw agent。

​

執行順序

1. agent RPC 會驗證參數、解析工作階段（sessionKey/sessionId）、持久化工作階段中繼資料，並立即回傳 { runId, acceptedAt }。
2. agentCommand 會執行該輪對話：解析模型 + thinking/verbose/trace 預設值、載入 Skills 快照、呼叫 runEmbeddedAgent，如果嵌入式迴圈尚未發出 生命週期結束/錯誤，則發出後援的 生命週期結束/錯誤。
3. runEmbeddedAgent：透過每工作階段和全域佇列序列化執行、解析模型 + 驗證設定檔、建構 OpenClaw 工作階段、訂閱執行階段事件、串流助理/工具增量、強制執行執行逾時（到期時中止），並回傳承載資料與用量中繼資料。對於 Codex app-server 輪次，它也會中止已接受但在終端事件前停止產生 app-server 進度的輪次。
4. subscribeEmbeddedAgentSession 會將執行階段事件橋接到 agent 串流：工具事件到 stream: "tool"、助理增量到 stream: "assistant"、生命週期事件到 stream: "lifecycle"（phase: "start" | "end" | "error"）。
5. agent.wait（waitForAgentRun）會等待某個 runId 上的 生命週期結束/錯誤，並回傳 { status: ok|error|timeout, startedAt, endedAt, error? }。

​

佇列與並行

執行會依工作階段鍵（工作階段通道）序列化，並可選擇通過全域通道，防止工具/工作階段競態。訊息通道會選擇佇列模式（steer/followup/collect/interrupt），並饋入此通道系統；請參閱命令佇列。 轉錄寫入也會受到工作階段檔案上的工作階段寫入鎖保護。該鎖具備程序感知能力並以檔案為基礎，因此能捕捉繞過程序內佇列或來自其他程序的寫入者。寫入者最多會等待 session.writeLock.acquireTimeoutMs（預設 60000 毫秒；環境變數覆寫 OPENCLAW_SESSION_WRITE_LOCK_ACQUIRE_TIMEOUT_MS），之後才會回報工作階段忙碌。 工作階段寫入鎖預設不可重入。若某個輔助工具刻意巢狀取得同一把鎖，同時保留一個邏輯寫入者，必須使用 allowReentrant: true 選擇加入。

​

工作階段與工作區準備

• 工作區會被解析並建立；沙盒化執行可能會重新導向到沙盒工作區根目錄。
• Skills 會被載入（或從快照重用），並注入到環境與提示中。
• Bootstrap/脈絡檔案會被解析並注入到系統提示中。
• 在串流開始之前，會取得工作階段寫入鎖，並開啟與準備 SessionManager。任何後續的轉錄重寫、壓縮或截斷路徑，都必須在開啟或變更轉錄檔案之前取得同一把鎖。

​

提示組裝

系統提示會由 OpenClaw 的基礎提示、Skills 提示、bootstrap 脈絡與每次執行覆寫建構而成。會強制套用模型特定限制與壓縮保留 token。請參閱系統提示，了解模型會看到的內容。

​

Hook

OpenClaw 有兩套 hook 系統：

• 內部 hook（閘道 hook）：用於命令與生命週期事件的事件驅動指令碼。
• 外掛 hook：代理/工具生命週期與閘道管線內的擴充點。

​

內部 hook（閘道 hook）

• agent:bootstrap：在系統提示最終確定前建構 bootstrap 檔案時執行。可用它新增或移除 bootstrap 脈絡檔案。
• 命令 hook：/new、/reset、/stop 和其他命令事件（請參閱 Hook 文件）。

設定與範例請參閱 Hook。

​

外掛 hook

這些會在代理迴圈或閘道管線內執行： 傳出/工具防護的 hook 決策規則：

• before_tool_call：{ block: true } 是終端狀態，會停止較低優先級的處理常式。{ block: false } 是無操作，不會清除先前的封鎖。
• before_install：語意與上述相同，包含終端/無操作行為。若操作者擁有的安裝允許/封鎖決策必須涵蓋命令列介面安裝與更新路徑，請使用 security.installPolicy，而不是 before_install。
• message_sending：{ cancel: true } 是終端狀態，會停止較低優先級的處理常式。{ cancel: false } 是無操作，不會清除先前的取消。

Hook API 與註冊細節請參閱外掛 hook。 測試框架可以調整這些 hook。Codex app-server 測試框架會將 OpenClaw 外掛 hook 保留為已記錄鏡像表面的相容性合約；Codex 原生 hook 是另一個較低階的 Codex 機制。

​

串流

• 助理增量會從代理執行階段以 assistant 事件串流。
• 區塊串流可在 text_end 或 message_end 發出部分回覆。
• 推理串流可以是獨立串流或區塊回覆。
• 分塊與區塊回覆行為請參閱串流。

​

工具執行

• 工具開始/更新/結束事件會發出到 tool 串流。
• 工具結果在記錄/發出前，會針對大小與圖片承載資料進行清理。
• 訊息工具傳送會被追蹤，以抑制重複的助理確認。

​

回覆塑形

最終承載資料會由助理文字（加上選用推理）、行內工具摘要（在 verbose 且允許時）以及模型錯誤時的助理錯誤文字組裝而成。

• 精確的靜默 token NO_REPLY 會從傳出承載資料中過濾。
• 訊息工具重複項會從最終承載資料清單中移除。
• 如果沒有可呈現的承載資料留下，且工具發生錯誤，除非訊息工具已傳送使用者可見的回覆，否則會發出後援工具錯誤回覆。

​

壓縮與重試

自動壓縮會發出 compaction 串流事件，並可觸發重試。重試時，記憶體內緩衝區與工具摘要會重設，以避免重複輸出。請參閱壓縮。

​

事件串流

• lifecycle：由 subscribeEmbeddedAgentSession 發出（也會由 agentCommand 作為後援發出）。
• assistant：來自代理執行階段的串流增量。
• tool：來自代理執行階段的串流工具事件。

閘道會將生命週期與工具開始/終端事件投影到有界、 僅含中繼資料的稽核分類帳。此投影會記錄來源與 結果代碼，而不會將提示、訊息、工具引數、工具結果 或原始錯誤從轉錄/執行階段路徑複製出去。

​

聊天通道處理

助理增量會緩衝成聊天 delta 訊息。聊天 final 會在 生命週期結束/錯誤 時發出。

​

逾時

​

卡住工作階段診斷

啟用診斷後，diagnostics.stuckSessionWarnMs（預設 120000 ms）會將長時間處於 processing、且沒有觀察到回覆、工具、狀態、區塊或 ACP 進度的工作階段分類：

• 作用中的嵌入式執行、模型呼叫和工具呼叫會回報為 session.long_running。有擁有者的靜默模型呼叫會維持 session.long_running，直到 diagnostics.stuckSessionAbortMs，避免過早將較慢或非串流的提供者標記為停滯。
• 作用中但最近沒有進度的工作會回報為 session.stalled。有擁有者的模型呼叫會在達到或超過中止閾值時切換為 session.stalled；無擁有者的過期模型/工具活動不會被隱藏為長時間執行。
• session.stuck 保留給可復原的過期工作階段簿記，包括具有過期無擁有者模型/工具活動的閒置佇列工作階段。

diagnostics.stuckSessionAbortMs 預設至少為 5 分鐘且為警告閾值的 3 倍。過期工作階段簿記會在復原閘門通過後立即釋放受影響的工作階段通道；停滯的嵌入式執行只會在中止閾值後進行中止排空，因此佇列工作可恢復，而不會切斷只是較慢的執行。復原會發出結構化的 requested/completed 結果；只有在同一個 processing 世代仍為目前狀態時，診斷狀態才會標記為閒置；當工作階段維持不變時，重複的 session.stuck 診斷會退避。

​

哪些情況會提前結束

• 代理逾時（中止）
• AbortSignal（取消）
• 閘道中斷連線或 RPC 逾時
• agent.wait 逾時（僅等待，不會停止代理）

​

相關

• 工具 - 可用的代理工具
• Hooks - 由代理生命週期事件觸發的事件驅動指令碼
• 壓縮 - 長對話如何被摘要
• 執行核准 - shell 命令的核准閘門
• 思考 - 思考/推理等級設定