Skip to main content
エージェントループは、メッセージをアクションと返信へ変換する、セッション単位で直列化された実行です。受信、コンテキストの組み立て、モデル推論、ツール実行、ストリーミング、永続化を行います。

​
エントリーポイント

  • Gateway RPC: agent と agent.wait。
  • CLI: 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）を選択します。コマンドキューを参照してください。 トランスクリプトへの書き込みは、セッションファイルに対するセッション書き込みロックによっても保護されます。このロックはプロセスを認識するファイルベースの仕組みであるため、プロセス内キューを迂回するライターや別プロセスのライターも検出します。ライターは、セッションがビジーであると報告する前に、デフォルトで最大 60 秒待機します（環境変数 OPENCLAW_SESSION_WRITE_LOCK_ACQUIRE_TIMEOUT_MS で上書き可能）。 セッション書き込みロックは、デフォルトでは再入可能ではありません。単一の論理ライターを維持しながら同じロックを意図的にネストして取得するヘルパーは、allowReentrant: true で明示的にオプトインする必要があります。

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

  • ワークスペースを解決して作成します。サンドボックス化された実行では、サンドボックスのワークスペースルートへリダイレクトされる場合があります。
  • Skills を読み込み（またはスナップショットから再利用し）、環境とプロンプトへ注入します。
  • ブートストラップ/コンテキストファイルを解決し、システムプロンプトへ注入します。
  • ストリーミングの開始前にセッション書き込みロックを取得し、セッショントランスクリプトの書き込み先を準備します。その後に行われるトランスクリプトの再書き込み、Compaction、または切り詰めの各パスでは、SQLite のトランスクリプト行を変更する前に同じロックを取得する必要があります。

​
プロンプトの組み立て

システムプロンプトは、OpenClaw の基本プロンプト、Skills プロンプト、ブートストラップコンテキスト、実行単位の上書きから構築されます。モデル固有の制限と Compaction 用の予約トークンが適用されます。モデルに表示される内容については、システムプロンプトを参照してください。

​
フック

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

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

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

​
Plugin フック

これらはエージェントループまたは Gateway パイプライン内で実行されます。 送信/ツールガードに関するフックの判定規則:
  • before_tool_call: { block: true } は終端であり、優先度の低いハンドラーを停止します。{ block: false } は何も行わず、先行するブロックを解除しません。
  • before_install: 上記と同じ終端/無操作のセマンティクスです。CLI のインストールおよび更新パスを対象に含める必要がある、オペレーター所有のインストール許可/ブロック判定には、before_install ではなく security.installPolicy を使用します。
  • message_sending: { cancel: true } は終端であり、優先度の低いハンドラーを停止します。{ cancel: false } は何も行わず、先行するキャンセルを解除しません。
フック API と登録の詳細については、Plugin フックを参照してください。 ハーネスはこれらのフックに適応できます。Codex app-server ハーネスでは、文書化されたミラー対象の互換性契約として OpenClaw Plugin フックを維持します。Codex ネイティブフックは、これとは別の、より低レベルな Codex の仕組みです。

​
ストリーミング

  • アシスタント差分は、エージェントランタイムから assistant イベントとしてストリーミングされます。
  • ブロックストリーミングでは、text_end または message_end で部分的な返信を発行できます。
  • 推論ストリーミングは、独立したストリームまたはブロック返信にできます。
  • チャンク化とブロック返信の動作については、ストリーミングを参照してください。

​
ツール実行

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

​
返信の整形

最終ペイロードは、アシスタントのテキスト（オプションの推論を含む）、インラインのツール概要（verbose が有効かつ許可されている場合）、およびモデルでエラーが発生した場合のアシスタントエラーテキストから組み立てられます。
  • 完全一致するサイレントトークン NO_REPLY は、送信ペイロードから除外されます。
  • メッセージングツールによる重複は、最終ペイロードリストから削除されます。
  • レンダリング可能なペイロードが残らず、ツールでエラーが発生した場合、メッセージングツールがすでにユーザーに表示される返信を送信していない限り、フォールバックのツールエラー返信が発行されます。

​
Compaction と再試行

自動 Compaction は compaction ストリームイベントを発行し、再試行をトリガーする場合があります。再試行時には、出力の重複を避けるため、メモリ内バッファとツール概要がリセットされます。Compactionを参照してください。

​
イベントストリーム

  • lifecycle: subscribeEmbeddedAgentSession によって発行されます（また、agentCommand によってフォールバックとして発行されます）。
  • assistant: エージェントランタイムからストリーミングされる差分。
  • tool: エージェントランタイムからストリーミングされるツールイベント。
Gateway は、ライフサイクルイベントとツールの開始/終端イベントを、上限付きでメタデータのみの監査台帳へ投影します。この投影は、プロンプト、メッセージ、ツール引数、ツール結果、または生のエラーをトランスクリプト/ランタイムのパス外へコピーせずに、来歴と結果コードを記録します。

​
チャットチャネルの処理

アシスタント差分は、チャットの delta メッセージへバッファリングされます。チャットの final は、ライフサイクル終了/エラー 時に発行されます。

​
タイムアウト

​
停止したセッションの診断

診断を有効にすると、組み込みの 2 分間のしきい値により、応答、ツール、ステータス、ブロック、または ACP の進行が観測されない長時間の processing セッションが分類されます。
  • アクティブな埋め込み実行、モデル呼び出し、およびツール呼び出しは session.long_running として報告されます。所有されている無応答のモデル呼び出しは中止しきい値まで session.long_running のままとなるため、低速または非ストリーミングのプロバイダーが早すぎる段階で停止と判定されることはありません。
  • 最近の進行がないアクティブな処理は session.stalled として報告されます。所有されているモデル呼び出しは、中止しきい値以降に session.stalled へ切り替わります。所有者のいない古いモデルまたはツールのアクティビティが、長時間実行として隠されることはありません。
  • session.stuck は、所有者のいない古いモデルまたはツールのアクティビティがあるアイドル状態のキュー済みセッションなど、復旧可能な古いセッション管理情報のために予約されています。
中止しきい値は 5 分以上かつ警告しきい値の 3 倍です。復旧ゲートを通過すると、古いセッション管理情報によって影響を受けたセッションレーンは直ちに解放されます。停止した埋め込み実行は中止しきい値の経過後にのみ中止およびドレインされるため、単に低速な実行を途中で終了させることなく、キュー内の処理が再開されます。復旧時には、要求および完了の結果が構造化された形式で出力されます。診断状態がアイドルとして記録されるのは、同じ処理世代が引き続き最新である場合に限られます。また、セッションに変化がない間は、繰り返される session.stuck 診断の間隔が段階的に延長されます。

​
処理が早期終了する場合

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

​
関連項目

  • ツール - 利用可能なエージェントツール
  • フック - エージェントのライフサイクルイベントによって起動されるイベント駆動型スクリプト
  • Compaction - 長い会話が要約される仕組み
  • 実行の承認 - シェルコマンドの承認ゲート
  • 思考 - 思考および推論レベルの設定