進入點
- 閘道 RPC：
agent和agent.wait。 - 命令列介面：
openclaw agent。
執行順序
agentRPC 會驗證參數、解析工作階段（sessionKey/sessionId）、持久化工作階段中繼資料，並立即傳回{ runId, acceptedAt }。agentCommand會執行該輪次：解析模型及思考／詳細／追蹤預設值、載入 Skills 快照、呼叫runEmbeddedAgent；如果內嵌迴圈尚未發出事件，則發出備援的生命週期結束／錯誤事件。runEmbeddedAgent：透過每工作階段佇列及全域佇列序列化執行、解析模型及驗證設定檔、建立 OpenClaw 工作階段、訂閱執行階段事件、串流助理／工具差異、強制執行逾時限制（到期時中止），並傳回承載資料及用量中繼資料。對於 Codex app-server 輪次，如果已接受的輪次在終止事件前停止產生 app-server 進度，也會將其中止。subscribeEmbeddedAgentSession會將執行階段事件橋接至agent串流：工具事件傳至stream: "tool"、助理差異傳至stream: "assistant"、生命週期事件傳至stream: "lifecycle"（phase: "start" | "end" | "error"）。agent.wait（waitForAgentRun）會在runId上等待生命週期結束／錯誤，並傳回{ status: ok|error|timeout, startedAt, endedAt, error? }。
佇列與並行處理
執行會依每個工作階段金鑰（工作階段通道）序列化，並可選擇性地再經過全域通道，以防止工具／工作階段競爭。訊息通道會選擇佇列模式（steer/followup/collect/interrupt）送入此通道系統；請參閱命令佇列。 逐字記錄寫入還會受到工作階段檔案上的工作階段寫入鎖保護。此鎖可感知處理程序且以檔案為基礎，因此可偵測繞過處理程序內佇列或來自其他處理程序的寫入者。寫入者預設最多等待 60 秒（可由環境變數OPENCLAW_SESSION_WRITE_LOCK_ACQUIRE_TIMEOUT_MS 覆寫），之後便會回報工作階段忙碌中。
工作階段寫入鎖預設不可重入。若輔助程式刻意巢狀取得同一把鎖，同時仍維持單一邏輯寫入者，則必須透過 allowReentrant: true 明確選擇啟用。
工作階段與工作區準備
- 解析並建立工作區；沙箱化執行可能會重新導向至沙箱工作區根目錄。
- 載入 Skills（或從快照重複使用），並注入環境與提示詞。
- 解析啟動／內容檔案，並注入系統提示詞。
- 在開始串流前取得工作階段寫入鎖，並準備工作階段逐字記錄目標。之後任何逐字記錄重寫、壓縮或截斷路徑，都必須先取得同一把鎖，才能修改 SQLite 逐字記錄資料列。
提示詞組裝
系統提示詞由 OpenClaw 的基礎提示詞、Skills 提示詞、啟動內容及每次執行的覆寫項目建構而成。系統會強制執行模型專屬限制與壓縮保留權杖數。關於模型可見的內容，請參閱系統提示詞。鉤子
OpenClaw 有兩套鉤子系統：- 內部鉤子（閘道鉤子）：用於命令與生命週期事件的事件驅動指令碼。
- 外掛鉤子：代理／工具生命週期與閘道流水線內的擴充點。
內部鉤子（閘道鉤子）
agent:bootstrap：在系統提示詞定稿前建立啟動檔案時執行。可用來新增或移除啟動內容檔案。- 命令鉤子：
/new、/reset、/stop及其他命令事件（請參閱鉤子文件）。
外掛鉤子
這些鉤子會在代理迴圈或閘道流水線內執行：
傳出／工具防護鉤子的判定規則：
before_tool_call：{ block: true }是終止性判定，會停止較低優先順序的處理常式。{ block: false }不執行任何動作，且不會清除先前的封鎖。before_install：具有與上述相同的終止／不執行任何動作語意。對於操作員擁有、且必須涵蓋命令列介面安裝及更新路徑的安裝允許／封鎖判定，請使用security.installPolicy，而非before_install。message_sending：{ cancel: true }是終止性判定，會停止較低優先順序的處理常式。{ cancel: false }不執行任何動作，且不會清除先前的取消。
串流
- 助理差異會從代理執行階段以
assistant事件串流傳送。 - 區塊串流可在
text_end或message_end時發出部分回覆。 - 推理串流可以是獨立串流或區塊回覆。
- 關於分塊與區塊回覆行為，請參閱串流。
工具執行
- 工具開始／更新／結束事件會在
tool串流上發出。 - 工具結果會先針對大小與影像承載資料進行清理，再記錄／發出。
- 系統會追蹤訊息工具傳送，以抑制重複的助理確認。
回覆塑形
最終承載資料由助理文字（加上選用的推理）、行內工具摘要（啟用詳細模式且允許時），以及模型發生錯誤時的助理錯誤文字組裝而成。- 輸出承載資料會篩除完全相符的靜默權杖
NO_REPLY。 - 最終承載資料清單會移除訊息工具的重複項目。
- 若沒有剩餘可呈現的承載資料且工具發生錯誤，除非訊息工具已傳送使用者可見的回覆，否則會發出備援的工具錯誤回覆。
壓縮與重試
自動壓縮會發出compaction 串流事件，並可觸發重試。重試時，記憶體內緩衝區與工具摘要會重設，以避免重複輸出。請參閱壓縮。
事件串流
lifecycle：由subscribeEmbeddedAgentSession發出（也可由agentCommand作為備援發出）。assistant：來自代理執行階段的串流差異。tool：來自代理執行階段的串流工具事件。
聊天通道處理
助理差異會緩衝至聊天delta 訊息中。發生生命週期結束／錯誤時，會發出聊天 final。
逾時
卡住的工作階段診斷
啟用診斷後，內建的兩分鐘門檻會對長時間未觀察到回覆、工具、狀態、封鎖或 ACP 進度的processing 工作階段進行分類：
- 進行中的內嵌執行、模型呼叫和工具呼叫會回報為
session.long_running。由擁有者負責且無輸出的模型呼叫會維持session.long_running，直到達到中止門檻，避免過早將較慢或非串流供應商標記為停滯。 - 近期沒有進度的進行中工作會回報為
session.stalled。由擁有者負責的模型呼叫會在達到或超過中止門檻時切換為session.stalled；沒有擁有者的過期模型／工具活動不會被隱藏為長時間執行。 session.stuck保留給可復原的過期工作階段記錄，包括具有過期且無擁有者模型／工具活動的閒置排隊工作階段。
session.stuck 診斷會採用退避機制。
可能提前結束的位置
- 代理程式逾時（中止）
- AbortSignal（取消）
- 閘道中斷連線或 RPC 逾時
agent.wait逾時（僅等待，不會停止代理程式）