エージェントループ
エージェントループのライフサイクル、フロー、待機セマンティクス。
エージェントループはエージェントの完全な「真の」実行です：取り込み→コンテキストの組み立て→モデル推論→
ツール実行→ストリーミング返信→永続化。これはメッセージを配信するための権威あるパスです
アクションと最終回答に変換しながら、セッション状態の一貫性を維持します。
OpenClawでは、ループはセッションごとの単一のシリアル化された実行であり、ライフサイクルとストリームイベントを発行します
モデルが思考し、ツールを呼び出し、出力をストリーミングするように。このドキュメントは、実際のループがどのように進むかを説明します
エンドツーエンドのワイヤ接続。
エントリーポイント
- ゲートウェイ RPC：''agent'' と ''agent.wait''。
- CLI：''agent'' コマンド。
仕組み（高レベル）
1. ''agent'' RPC は引数を検証し、セッション（sessionKey/sessionId）を解決し、セッションメタデータを保存し、すぐに ''{ runId, acceptedAt }'' を返します。
2. ''agentCommand'' はエージェントを実行します：
- モデル+思考/詳細のデフォルトを解決
- スキルスナップショットをロード
- ''runEmbeddedPiAgent'' を呼び出す（pi-agent-core ランタイム）
- 組み込みループがライフサイクル終了/エラーを発行しない場合、ライフサイクル終了/エラーを発行
3.''runEmbeddedPiAgent''：
- セッションごと+グローバルキューで実行をシリアル化
- モデル+認証プロファイルを解決し、piセッションを構築
- piイベントをサブスクライブし、アシスタント/ツールデルタをストリーミング
- タイムアウトを強制 → 超過した場合に実行を中止
- ペイロード+使用量メタデータを返す
4. ''subscribeEmbeddedPiSession'' は pi-agent-core イベントを OpenClaw ''agent'' ストリームにブリッジします：
- ツールイベント => ''stream: "tool"''
- アシスタントデルタ => ''stream: "assistant"''
- ライフサイクルイベント => ''stream: "lifecycle"'' (''phase: "start" | "end" | "error"'')
5. ''agent.wait'' は ''waitForAgentJob'' を使用します：
- ''runId'' の''ライフサイクル終了/エラー''を待機
- ''{ status: ok|error|timeout, startedAt, endedAt, error? }'' を返す
キュー+同時実行
- 実行はセッションキー（セッションチャネル）ごとにシリアル化され、オプションでグローバルチャネルを介してシリアル化されます。
- これにより、ツール/セッションの競合を防ぎ、セッション履歴の一貫性を保ちます。
- メッセージングチャネルは、そのチャネルシステムのキューモード（収集/リード/フォロー）をオプションで提供できます。
''コマンドキュー''を参照してください。
セッション + ワークスペースの準備
- ワークスペースが解決され作成されます。サンドボックス実行はサンドボックスワークスペースルートにリダイレクトされる場合があります。
- スキルがロード（またはスナップショットから再利用）され、環境とプロンプトに注入されます。
- ブートストラップ/コンテキストファイルが解決され、システムプロンプトレポートに注入されます。
- セッション書き込みロックが取得されます。ストリーミング前に ''SessionManager'' が開かれ準備完了状態になります。
プロンプトの組み立て+システムプロンプト
- システムプロンプトは、OpenClawの基本プロンプト、スキルプロンプト、ブートストラップコンテキスト、実行ごとのオーバーライドから構築されます。
- モデル固有の制限と圧縮予約トークンが強制されます。
- モデルが見るものについては、''システムプロンプト''を参照してください。
フックポイント（インターセプトできる場所）
OpenClawには2つのフックシステムがあります：
- 内部フック（ゲートウェイフック）：コマンドとライフサイクルイベントのイベント駆動型スクリプト。
- プラグインフック：エージェント/ツールライフサイクルとゲートウェイパイプライン内の拡張ポイント。
#
内部フック（ゲートウェイフック）
- ''''agent:bootstrap''''：システムプロンプトの最終化前にブートストラップファイルを構築するときに実行されます。
ブートストラップコンテキストファイルを追加/削除するために使用します。
- ''コマンドフック''：''/new''、''/reset''、''/stop'' およびその他のコマンドイベント（フックのドキュメントを参照）。
設定と例については、''フック''を参照してください。
#
プラグインフック（エージェント+ゲートウェイライフサイクル）
それらはエージェントループまたはゲートウェイパイプライン内で実行されます：
- ''''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''''：ゲートウェイライフサイクルイベント。
フックAPIと登録の詳細については、''プラグイン''を参照してください。
ストリーミング + 部分返信
- アシスタントデルタは pi-agent-core からストリーミングされ、''assistant'' イベントとして発行されます。
- チャンクストリームは、''text_end'' または ''message_end'' で部分返信を発行できます。
- 推論ストリームは、個別のストリームまたはチャンク返信として発行できます。
- チャンキングとチャンク返信の動作については、''ストリーミング''を参照してください。
ツール実行+メッセージングツール
- ツール開始/更新/終了イベントは ''tool'' ストリームで発行されます。
- ツール結果は、ログ記録/送信前にサイズと画像ペイロードに基づいてサニタイズされます。
- メッセージングツールの送信は追跡され、重複するアシスタント確認を抑制します。
返信の整形+抑制
- 最終ペイロードは以下から組み立てられます：
- アシスタントテキスト（およびオプションの推論）
- インラインツールの概要（詳細+許可されている場合）
- モデルエラー時のアシスタントエラーテキスト
- ''NO_REPLY'' はサイレントトークンとして扱われ、発信ペイロードからフィルタリングされます。
- メッセージングツールの重複は最終ペイロードリストから削除されます。
- レンダリング可能なペイロードが残っておらず、ツールがエラーになった場合、フォールバックツールエラー返信が発行されます
（メッセージングツールがすでにユーザーに表示される返信を送信していない限り）。
Compaction+Retry
- 自動圧縮は ''compaction'' ストリームイベントを発行し、再試行をトリガーできます。
- 再試行時、メモリバッファとツールの概要がリセットされ、重複出力を回避します。
- 圧縮パイプラインについては、''圧縮''を参照してください。
イベントストリーム（現在）
- ''lifecycle''：''subscribeEmbeddedPiSession'' によって発行されます（''agentCommand'' のフォールバックとして）
- ''assistant''：pi-agent-core からのストリーミングデルタ
- ''tool''：pi-agent-core からのストリーミングツールイベント
チャットチャネルの処理
- アシスタントデルタはチャット ''delta'' メッセージにバッファリングされます。
- チャット ''final'' は''ライフサイクル終了/エラー''時に発行されます。
タイムアウト
- ''agent.wait'' デフォルト：30秒（待機のみ）。''timeoutMs'' パラメータで上書き。
- エージェント実行時間：''agents.defaults.timeoutSeconds'' デフォルト600秒。''runEmbeddedPiAgent'' 中止タイマーで強制実行。
早期終了できる場所
- エージェントタイムアウト（中止）
- AbortSignal（キャンセル）
- ゲートウェイの切断またはRPCタイムアウト
- ''agent.wait'' タイムアウト（待機のみ、エージェントは停止しない）