エージェントループ

エージェントループは、メッセージをアクションと返信に変換する、セッションごとに直列化された実行です。取り込み、コンテキスト組み立て、モデル推論、ツール実行、ストリーミング、永続化を行います。

​

エントリーポイント

• Gateway RPC: agent と agent.wait。
• CLI: openclaw agent。

​

実行シーケンス

1. agent RPC はパラメーターを検証し、セッション（sessionKey/sessionId）を解決し、セッションメタデータを永続化して、{ runId, acceptedAt } を即座に返します。
2. agentCommand はターンを実行します。モデル + thinking/verbose/trace のデフォルトを解決し、Skills スナップショットを読み込み、runEmbeddedAgent を呼び出し、埋め込みループがまだ送出していない場合はフォールバックの ライフサイクル end/error を送出します。
3. runEmbeddedAgent: セッションごとおよびグローバルキューで実行を直列化し、モデル + 認証プロファイルを解決し、OpenClaw セッションを構築し、ランタイムイベントを購読し、assistant/tool デルタをストリーミングし、実行タイムアウトを適用し（期限切れで中止）、ペイロードと使用量メタデータを返します。Codex アプリサーバーのターンでは、終端イベントの前にアプリサーバー進捗を生成しなくなった受理済みターンも中止します。
4. subscribeEmbeddedAgentSession はランタイムイベントを agent ストリームへ橋渡しします。ツールイベントは stream: "tool"、assistant デルタは stream: "assistant"、ライフサイクルイベントは stream: "lifecycle"（phase: "start" | "end" | "error"）にします。
5. agent.wait（waitForAgentRun）は runId の ライフサイクル end/error を待機し、{ status: ok|error|timeout, startedAt, endedAt, error? } を返します。

​

キューイングと並行処理

実行はセッションキーごと（セッションレーン）に直列化され、任意でグローバルレーンも通すことで、ツール/セッションの競合を防ぎます。メッセージングチャネルは、このレーンシステムへ投入するキューモード（steer/followup/collect/interrupt）を選択します。コマンドキューを参照してください。 トランスクリプト書き込みは、セッションファイル上のセッション書き込みロックでも保護されます。このロックはプロセスを認識するファイルベースのロックであるため、プロセス内キューを迂回する書き込みや別プロセスからの書き込みを検出します。書き込み側は、セッションをビジーとして報告する前に最大 session.writeLock.acquireTimeoutMs（デフォルト 60000 ms、環境変数オーバーライド OPENCLAW_SESSION_WRITE_LOCK_ACQUIRE_TIMEOUT_MS）まで待機します。 セッション書き込みロックはデフォルトで非再入です。1 つの論理的な書き込み側を維持しながら同じロックの取得を意図的にネストするヘルパーは、allowReentrant: true でオプトインする必要があります。

​

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

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

​

プロンプト組み立て

システムプロンプトは、OpenClaw のベースプロンプト、Skills プロンプト、ブートストラップコンテキスト、実行ごとのオーバーライドから構築されます。モデル固有の制限と Compaction 予約トークンが適用されます。モデルが見る内容については、システムプロンプトを参照してください。

​

フック

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

• 内部フック（Gateway フック）: コマンドとライフサイクルイベント向けのイベント駆動スクリプト。
• Plugin フック: エージェント/ツールのライフサイクルと Gateway パイプライン内の拡張ポイント。

​

内部フック（Gateway フック）

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

設定と例については、フックを参照してください。

​

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 アプリサーバーハーネスは、文書化されたミラー対象サーフェスの互換性契約として OpenClaw Plugin フックを維持します。Codex ネイティブフックは、別個の低レベル Codex メカニズムです。

​

ストリーミング

• Assistant デルタは、エージェントランタイムから assistant イベントとしてストリーミングされます。
• ブロックストリーミングは、text_end または message_end で部分返信を送出できます。
• 推論ストリーミングは、別ストリームにすることも、ブロック返信にすることもできます。
• チャンク化とブロック返信の挙動については、ストリーミングを参照してください。

​

ツール実行

• ツールの start/update/end イベントは tool ストリーム上に送出されます。
• ツール結果は、ログ記録/送出前にサイズと画像ペイロードについてサニタイズされます。
• メッセージングツールの送信は、重複する assistant 確認を抑制するために追跡されます。

​

返信の整形

最終ペイロードは、assistant テキスト（任意の推論を含む）、インラインツール要約（verbose かつ許可されている場合）、モデルエラー時の assistant エラーテキストから組み立てられます。

• 正確な無音トークン NO_REPLY は送信ペイロードからフィルターされます。
• メッセージングツールの重複は、最終ペイロードリストから削除されます。
• レンダリング可能なペイロードが残っておらず、ツールでエラーが発生していた場合、メッセージングツールがすでにユーザーに見える返信を送信していない限り、フォールバックのツールエラー返信が送出されます。

​

Compaction とリトライ

自動 Compaction は compaction ストリームイベントを送出し、リトライをトリガーできます。リトライ時には、重複出力を避けるためにインメモリバッファとツール要約がリセットされます。Compactionを参照してください。

​

イベントストリーム

• lifecycle: subscribeEmbeddedAgentSession により送出されます（また、agentCommand によりフォールバックとして送出されます）。
• assistant: エージェントランタイムからストリーミングされるデルタ。
• tool: エージェントランタイムからストリーミングされるツールイベント。

Gateway は、ライフサイクルおよびツールの開始/終端イベントを、境界付きでメタデータのみの監査台帳へ投影します。この投影は、プロンプト、メッセージ、ツール引数、ツール結果、または生エラーをトランスクリプト/ランタイム経路の外へコピーすることなく、来歴と結果コードを記録します。

​

チャットチャネル処理

Assistant デルタはチャット delta メッセージへバッファリングされます。チャット final は ライフサイクル end/error で送出されます。

​

タイムアウト

​

スタックしたセッションの診断

診断を有効にすると、diagnostics.stuckSessionWarnMs（デフォルト 120000 ms）は、観測された返信、ツール、ステータス、ブロック、ACP 進行がない長時間の processing セッションを分類する。

• アクティブな埋め込み実行、モデル呼び出し、ツール呼び出しは session.long_running として報告される。所有されている無音のモデル呼び出しは、diagnostics.stuckSessionAbortMs まで session.long_running のままになるため、遅いプロバイダーやストリーミングしないプロバイダーが早すぎる段階で停止としてフラグ付けされることはない。
• 最近の進行がないアクティブな作業は session.stalled として報告される。所有されているモデル呼び出しは、中断しきい値以降で session.stalled に切り替わる。所有者のない古いモデル/ツールアクティビティは、長時間実行中として隠されない。
• session.stuck は、古い所有者なしモデル/ツールアクティビティを伴うアイドル状態のキュー済みセッションを含む、復旧可能な古いセッション bookkeeping 用に予約されている。

diagnostics.stuckSessionAbortMs は、デフォルトで少なくとも 5 分かつ警告しきい値の 3 倍になる。古いセッション bookkeeping は、復旧ゲートの通過直後に影響を受けたセッションレーンを解放する。停止した埋め込み実行は中断しきい値の後にのみ中断ドレインされるため、単に遅いだけの実行を打ち切らずにキュー済み作業が再開する。復旧は構造化された要求済み/完了済みの結果を発行する。診断状態は、同じ処理世代がまだ現在のものである場合にのみアイドルとしてマークされ、セッションが変わらない間は繰り返しの session.stuck 診断がバックオフする。

​

早期終了が発生し得る場所

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

​

関連

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