Skip to main content
エージェントループは、エージェントの完全な「実際の」実行プロセスです。インテーク（入力受付） → コンテキストのアセンブリ → モデル推論 → ツールの実行 → ストリーミング応答 → 永続化という一連の流れを指します。これは、セッション状態の一貫性を保ちながら、メッセージをアクションと最終的な応答に変換するための正式なパスです。 OpenClaw では、ループはセッションごとに単一のシリアル化された実行として行われ、モデルが思考し、ツールを呼び出し、出力をストリーミングする過程で、ライフサイクルイベントとストリームイベントを発行します。このドキュメントでは、このループがエンドツーエンドでどのように構成されているかを説明します。

​
エントリポイント

  • ゲートウェイ RPC: agent および agent.wait
  • CLI: agent コマンド

​
仕組み (概要)

  1. agent RPC はパラメータを検証し、セッション (sessionKey/sessionId) を解決し、セッションメタデータを永続化し、すぐに { runId, acceptedAt } を返します。
  2. agentCommand はエージェントを実行します。
    • モデルおよび思考プロセス/詳細出力（verbose）のデフォルト設定を解決します。
    • スキルのスナップショットをロードします。
    • 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? } を返します。

​
キュー + 同時実行

  • 実行はセッションキー (セッションレーン) ごとにシリアル化され、オプションでグローバルレーンを通じてもシリアル化されます。
  • これにより、ツールやセッションの競合が防止され、セッション履歴の一貫性が維持されます。
  • メッセージングチャネルは、このレーンシステムに供給されるキューモード (collect/steer/followup) を選択できます。詳細は コマンドキュー を参照してください。

​
セッション + ワークスペースの準備

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

​
プロンプトアセンブリ + システムプロンプト

  • システムプロンプトは、OpenClaw のベースプロンプト、スキルプロンプト、ブートストラップコンテキスト、および実行ごとのオーバーライドから構築されます。
  • モデル固有の制限と、コンパクション（圧縮）予約トークンが適用されます。
  • モデルが認識する内容の詳細については、システムプロンプト を参照してください。

​
フックポイント (インターセプト可能な場所)

OpenClaw には 2 つのフックシステムがあります。
  • 内部フック (ゲートウェイフック): コマンドおよびライフサイクルイベント用のイベント駆動型スクリプト。
  • プラグインフック: エージェント/ツールのライフサイクルおよびゲートウェイパイプライン内の拡張ポイント。

​
内部フック (ゲートウェイフック)

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

​
プラグインフック (エージェント + ゲートウェイのライフサイクル)

これらはエージェントループまたはゲートウェイパイプライン内で実行されます。
  • before_model_resolve: セッション開始前（messages なし）に実行され、モデル解決前にプロバイダー/モデルを決定的にオーバーライドします。
  • before_prompt_build: セッションロード後（messages あり）に実行され、プロンプトの送信前に prependContext、systemPrompt、prependSystemContext、または appendSystemContext を挿入します。ターンごとの動的なテキストには prependContext を使用し、システムプロンプト領域に配置すべき安定したガイダンスにはシステムコンテキストフィールドを使用します。
  • 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 のいずれかのタイミングで部分的な応答を送信できます。
  • 推論（Reasoning）ストリーミングは、別個のストリームまたはブロック応答として送信できます。
  • チャンク化とブロック応答の動作については、ストリーミング を参照してください。

​
ツール実行 + メッセージングツール

  • ツールの開始/更新/終了イベントは、tool ストリームで発行されます。
  • ツールの結果は、記録や出力の前に、サイズ制限や画像ペイロードに関してサニタイズされます。
  • メッセージングツールの送信は追跡され、重複したアシスタントの確認メッセージが抑制されます。

​
応答整形 + 抑制

  • 最終的なペイロードは以下から組み立てられます。
    • アシスタントのテキスト (およびオプションの推論)
    • インラインツールの概要 (詳細出力が許可されている場合)
    • モデルエラー時のアシスタントエラーテキスト
  • NO_REPLY はサイレントトークンとして扱われ、送信ペイロードから除外されます。
  • メッセージングツールの重複は、最終的なペイロードリストから削除されます。
  • 表示可能なペイロードが残っておらず、ツールでエラーが発生した場合、フォールバックとしてツールのエラー応答が発行されます（メッセージングツールがすでにユーザーに見える応答を送信している場合を除く）。

​
圧縮 + 再試行

  • 自動圧縮（コンパクション）は 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 タイムアウト (待機のみ、エージェント自体は停止しません)