Agent Loop（OpenClaw）¶

エージェントループとは、エージェントの完全で「実際の」実行全体を指します。すなわち、入力の受け取り → コンテキストの組み立て → モデル推論 → ツール実行 → 応答のストリーミング → 永続化、という流れです。これは、セッション状態の一貫性を保ちながら、メッセージをアクションと最終的な応答へと変換する、権威ある経路です。 セッション状態を一定に保ちながら、メッセージ をアクションと最終返信に変える権威ある経路です。

OpenClaw では、ループはセッションごとに 1 回の直列化された実行であり、モデルが思考し、ツールを呼び出し、出力をストリーミングする過程で、ライフサイクルイベントおよびストリームイベントを発行します。本ドキュメントでは、この正規のループがエンドツーエンドでどのように配線されているかを説明します。 このドキュメントでは、その本物のループが 有線エンドツーエンドであるかについて説明します。

エントリーポイント¶

• Gateway RPC: agent および agent.wait。
• CLI: agent コマンド。

仕組み（ハイレベル）¶

1. agent RPC がパラメータを検証し、セッション（sessionKey/sessionId）を解決し、セッションメタデータを永続化し、即座に { runId, acceptedAt } を返します。
2. agentCommand がエージェントを実行します。 - モデルおよび thinking/verbose のデフォルトを解決 - Skills のスナップショットをロード - runEmbeddedPiAgent（pi-agent-core ランタイム）を呼び出し - 埋め込まれたループが 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 を使用します。 - runId に対して lifecycle end/error を待機 - { status: ok|error|timeout, startedAt, endedAt, error? } を返却

キューイング＋並行性¶

• 実行はセッションキー（セッションレーン）ごとに直列化され、必要に応じてグローバルレーンも通過します。
• これにより、ツールやセッションの競合を防ぎ、セッション履歴の一貫性を保ちます。
• メッセージングチャンネルは、レーンシステムに供給されるキューモード（collect/steer/followup）を選択できます。 詳細は Command Queue を参照してください。 Command Queue を参照してください。

セッションとワークスペースの準備¶

• ワークスペースが解決・作成され、サンドボックス化された実行ではサンドボックスのワークスペースルートへリダイレクトされる場合があります。
• Skills がロード（またはスナップショットから再利用）され、環境およびプロンプトに注入されます。
• ブートストラップ／コンテキストファイルが解決され、システムプロンプトレポートに注入されます。
• セッション書き込みロックが取得され、ストリーミング前に SessionManager がオープンおよび準備されます。

プロンプト組み立てとシステムプロンプト¶

• システムプロンプトは、OpenClaw のベースプロンプト、Skills プロンプト、ブートストラップコンテキスト、および実行ごとのオーバーライドから構築されます。
• モデル固有の制限と圧縮リザーブトークンが強制されます。
• モデルが実際に見る内容については、System prompt を参照してください。

フックポイント（介入できる場所）¶

OpenClaw には 2 種類のフックシステムがあります。

• 内部フック（Gateway フック）: コマンドおよびライフサイクルイベント向けのイベント駆動スクリプト。
• プラグインフック: エージェント／ツールのライフサイクルおよびゲートウェイパイプライン内の拡張ポイント。

内部フック（Gateway フック）¶

• agent:bootstrap: システムプロンプトが確定する前に、ブートストラップファイルを構築している間に実行されます。 ブートストラップコンテキストファイルの追加／削除に使用します。 ブートストラップのコンテキストファイルの追加/削除に使用します。
• コマンドフック: /new、/reset、/stop、およびその他のコマンドイベント（詳細は Hooks ドキュメント参照）。

セットアップおよび例については、Hooks を参照してください。

プラグインフック（エージェント＋ゲートウェイのライフサイクル）¶

これらはエージェントループ内、またはゲートウェイパイプライン内で実行されます。

• 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 および登録の詳細については、Plugins を参照してください。

ストリーミングと部分応答¶

• assistant の差分は pi-agent-core からストリーミングされ、assistant イベントとして発行されます。
• ブロックストリーミングでは、text_end または message_end 上で部分応答を発行できます。
• 推論のストリーミングは、別ストリームとして、またはブロック応答として発行できます。
• チャンク化およびブロック応答の挙動については、Streaming を参照してください。

ツール実行とメッセージングツール¶

• ツールの開始／更新／終了イベントは、tool ストリーム上で発行されます。
• ツール結果は、ログ記録および発行前に、サイズや画像ペイロードに関してサニタイズされます。
• メッセージングツールによる送信は追跡され、assistant による重複確認応答を抑制します。

応答の整形と抑制¶

• 最終的なペイロードは、以下から組み立てられます。
• assistant テキスト（および任意の推論）
• インラインのツール要約（verbose かつ許可されている場合）
• モデルエラー時の assistant エラーテキスト
• NO_REPLY はサイレントトークンとして扱われ、送信ペイロードから除外されます。
• メッセージングツールの重複は、最終ペイロードリストから削除されます。
• 表示可能なペイロードが残らず、かつツールがエラーになった場合は、フォールバックのツールエラー応答が発行されます （ただし、メッセージングツールがすでにユーザー可視の応答を送信している場合を除きます）。

コンパクション + リトライ¶

• 自動圧縮は compaction ストリームイベントを発行し、リトライをトリガーする場合があります。
• リトライ時には、重複出力を避けるため、インメモリバッファおよびツール要約がリセットされます。
• 圧縮パイプラインについては、Compaction を参照してください。

イベントストリーム（現状）¶

• lifecycle: subscribeEmbeddedPiSession によって発行（およびフォールバックとして agentCommand によって発行）
• assistant: pi-agent-core からのストリーミング差分
• tool: pi-agent-core からのストリーミングツールイベント

チャットチャンネルの処理¶

• assistant の差分は、チャットの delta メッセージにバッファされます。
• チャットの final は lifecycle end/error 時に発行されます。

タイムアウト¶

• agent.wait のデフォルト: 30 秒（待機のみ）。timeoutMs パラメータで上書きできます。 timeoutMs param overrides.
• エージェントランタイム: agents.defaults.timeoutSeconds のデフォルトは 600 秒で、runEmbeddedPiAgent の中断タイマーで強制されます。

早期終了が発生する箇所¶

• エージェントのタイムアウト（中断）
• AbortSignal（キャンセル）
• Gateway の切断または RPC タイムアウト
• agent.wait タイムアウト（待機のみで、エージェントは停止しません）