> ## Documentation Index > Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt > Use this file to discover all available pages before exploring further. # エージェントループ エージェントループは、メッセージをアクションと返信に変換する、セッションごとに直列化された実行です。取り込み、コンテキスト組み立て、モデル推論、ツール実行、ストリーミング、永続化を行います。 ## エントリーポイント * 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）を選択します。[コマンドキュー](/ja-JP/concepts/queue)を参照してください。 トランスクリプト書き込みは、セッションファイル上のセッション書き込みロックでも保護されます。このロックはプロセスを認識するファイルベースのロックであるため、プロセス内キューを迂回する書き込みや別プロセスからの書き込みを検出します。書き込み側は、セッションをビジーとして報告する前に最大 `session.writeLock.acquireTimeoutMs`（デフォルト `60000` ms、環境変数オーバーライド `OPENCLAW_SESSION_WRITE_LOCK_ACQUIRE_TIMEOUT_MS`）まで待機します。 セッション書き込みロックはデフォルトで非再入です。1 つの論理的な書き込み側を維持しながら同じロックの取得を意図的にネストするヘルパーは、`allowReentrant: true` でオプトインする必要があります。 ## セッションとワークスペースの準備 * ワークスペースが解決され、作成されます。サンドボックス化された実行では、サンドボックスワークスペースルートへリダイレクトされる場合があります。 * Skills が読み込まれ（またはスナップショットから再利用され）、env とプロンプトに注入されます。 * ブートストラップ/コンテキストファイルが解決され、システムプロンプトに注入されます。 * ストリーミング開始前にセッション書き込みロックが取得され、`SessionManager` が開かれて準備されます。その後のトランスクリプト再書き込み、Compaction、切り詰め経路は、トランスクリプトファイルを開く、または変更する前に同じロックを取得する必要があります。 ## プロンプト組み立て システムプロンプトは、OpenClaw のベースプロンプト、Skills プロンプト、ブートストラップコンテキスト、実行ごとのオーバーライドから構築されます。モデル固有の制限と Compaction 予約トークンが適用されます。モデルが見る内容については、[システムプロンプト](/ja-JP/concepts/system-prompt)を参照してください。 ## フック OpenClaw には 2 つのフックシステムがあります。 * **内部フック**（Gateway フック）: コマンドとライフサイクルイベント向けのイベント駆動スクリプト。 * **Plugin フック**: エージェント/ツールのライフサイクルと Gateway パイプライン内の拡張ポイント。 ### 内部フック（Gateway フック） * **`agent:bootstrap`**: システムプロンプトが確定される前、ブートストラップファイルの構築中に実行されます。ブートストラップコンテキストファイルを追加または削除するために使用します。 * **コマンドフック**: `/new`、`/reset`、`/stop`、その他のコマンドイベント（Hooks ドキュメントを参照）。 設定と例については、[フック](/ja-JP/automation/hooks)を参照してください。 ### Plugin フック これらはエージェントループまたは Gateway パイプライン内で実行されます。 | フック | 実行内容 | | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `before_model_resolve` | セッション前（`messages` なし）に、解決前のプロバイダー/モデルを決定論的にオーバーライドします。 | | `before_prompt_build` | セッション読み込み後（`messages` あり）に、送信前の `prependContext`、`systemPrompt`、`prependSystemContext`、または `appendSystemContext` を注入します。ターンごとの動的テキストには `prependContext` を使用し、システムプロンプト空間に属する安定したガイダンスにはシステムコンテキストフィールドを使用します。 | | `before_agent_start` | どちらのフェーズでも実行される可能性があるレガシー互換フックです。上記の明示的なフックを優先してください。 | | `before_agent_reply` | インラインアクション後、LLM 呼び出し前。Plugin がターンを引き受けて合成返信を返す、または完全に無音にできます。 | | `agent_end` | 完了後、最終メッセージリストと実行メタデータ付きで実行されます。 | | `before_compaction` / `after_compaction` | Compaction サイクルを監視または注釈付けします。 | | `before_tool_call` / `after_tool_call` | ツールのパラメーター/結果をインターセプトします。 | | `before_install` | オペレーターのインストールポリシー実行後、現在のプロセスに Plugin フックが読み込まれている場合に、ステージングされた Skills/Plugin インストール素材に対して実行されます。 | | `tool_result_persist` | ツール結果が OpenClaw 所有のセッショントランスクリプトへ書き込まれる前に、同期的に変換します。 | | `message_received` / `message_sending` / `message_sent` | 受信および送信メッセージフック。 | | `session_start` / `session_end` | セッションライフサイクル境界。 | | `gateway_start` / `gateway_stop` | Gateway ライフサイクルイベント。 | 送信/ツールガードのフック判定ルール: * `before_tool_call`: `{ block: true }` は終端であり、低優先度のハンドラーを停止します。`{ block: false }` は何もせず、以前のブロックを解除しません。 * `before_install`: 上記と同じ終端/無操作セマンティクスです。CLI インストールと更新経路をカバーする必要がある、オペレーター所有のインストール許可/ブロック判定には、`before_install` ではなく `security.installPolicy` を使用してください。 * `message_sending`: `{ cancel: true }` は終端であり、低優先度のハンドラーを停止します。`{ cancel: false }` は何もせず、以前のキャンセルを解除しません。 フック API と登録の詳細については、[Plugin フック](/ja-JP/plugins/hooks)を参照してください。 ハーネスはこれらのフックを適応できます。Codex アプリサーバーハーネスは、文書化されたミラー対象サーフェスの互換性契約として OpenClaw Plugin フックを維持します。Codex ネイティブフックは、別個の低レベル Codex メカニズムです。 ## ストリーミング * Assistant デルタは、エージェントランタイムから `assistant` イベントとしてストリーミングされます。 * ブロックストリーミングは、`text_end` または `message_end` で部分返信を送出できます。 * 推論ストリーミングは、別ストリームにすることも、ブロック返信にすることもできます。 * チャンク化とブロック返信の挙動については、[ストリーミング](/ja-JP/concepts/streaming)を参照してください。 ## ツール実行 * ツールの start/update/end イベントは `tool` ストリーム上に送出されます。 * ツール結果は、ログ記録/送出前にサイズと画像ペイロードについてサニタイズされます。 * メッセージングツールの送信は、重複する assistant 確認を抑制するために追跡されます。 ## 返信の整形 最終ペイロードは、assistant テキスト（任意の推論を含む）、インラインツール要約（verbose かつ許可されている場合）、モデルエラー時の assistant エラーテキストから組み立てられます。 * 正確な無音トークン `NO_REPLY` は送信ペイロードからフィルターされます。 * メッセージングツールの重複は、最終ペイロードリストから削除されます。 * レンダリング可能なペイロードが残っておらず、ツールでエラーが発生していた場合、メッセージングツールがすでにユーザーに見える返信を送信していない限り、フォールバックのツールエラー返信が送出されます。 ## Compaction とリトライ 自動 Compaction は `compaction` ストリームイベントを送出し、リトライをトリガーできます。リトライ時には、重複出力を避けるためにインメモリバッファとツール要約がリセットされます。[Compaction](/ja-JP/concepts/compaction)を参照してください。 ## イベントストリーム * `lifecycle`: `subscribeEmbeddedAgentSession` により送出されます（また、`agentCommand` によりフォールバックとして送出されます）。 * `assistant`: エージェントランタイムからストリーミングされるデルタ。 * `tool`: エージェントランタイムからストリーミングされるツールイベント。 Gateway は、ライフサイクルおよびツールの開始/終端イベントを、境界付きでメタデータのみの[監査台帳](/cli/audit)へ投影します。この投影は、プロンプト、メッセージ、ツール引数、ツール結果、または生エラーをトランスクリプト/ランタイム経路の外へコピーすることなく、来歴と結果コードを記録します。 ## チャットチャネル処理 Assistant デルタはチャット `delta` メッセージへバッファリングされます。チャット `final` は **ライフサイクル end/error** で送出されます。 ## タイムアウト | タイムアウト | デフォルト | 注記 | | ---------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `agent.wait` | 30s | 待機のみ。`timeoutMs` パラメータで上書きされる。基盤となる実行は停止しない。 | | エージェントランタイム (`agents.defaults.timeoutSeconds`) | 172800s (48h) | `runEmbeddedAgent` の中断タイマーによって強制される。 | | Cron 分離エージェントターン | Cron が所有 | スケジューラは実行開始時に独自のタイマーを開始し、設定された期限で実行を中断してから、タイムアウトを記録する前に境界付きのクリーンアップを実行するため、古い子セッションによってレーンが詰まったままになることはない。 | | モデルアイドルタイムアウト | `agents.defaults.timeoutSeconds`、デフォルトでは最大 120s | OpenClaw は、アイドルウィンドウ内に応答チャンクが到着しない場合、モデルリクエストを中断する。`models.providers..timeoutSeconds` は、遅いローカル/セルフホストプロバイダー向けにこのアイドルウォッチドッグを延長するが、より低い `agents.defaults.timeoutSeconds` または実行固有のタイムアウトがある場合はそれらによって制限される。これらはエージェント実行全体を管理するため。明示的なモデル/エージェントタイムアウトがない Cron 起動のクラウドモデル実行では、同じデフォルトを使用する。明示的な Cron 実行タイムアウトがある場合、クラウドモデルストリームの停止は 60s に制限されるため、外側の Cron 期限の前に設定済みのモデルフォールバックを引き続き実行できる。Cron 起動のローカル/セルフホストモデル実行では、明示的なタイムアウトが設定されていない限り、暗黙のウォッチドッグを無効にする。遅いローカルプロバイダーには `models.providers..timeoutSeconds` を設定する。 | | プロバイダー HTTP リクエストタイムアウト | `models.providers..timeoutSeconds` | そのプロバイダーの接続、ヘッダー、本文、SDK リクエストタイムアウト、保護された fetch の中断処理、モデルストリームのアイドルウォッチドッグを対象とする。エージェントランタイム全体のタイムアウトを引き上げる前に、遅いローカル/セルフホストプロバイダー（例: Ollama）に使用する。モデルリクエストをより長く実行する必要がある場合は、エージェント/ランタイムタイムアウトを少なくとも同じ長さに保つ。 | ### スタックしたセッションの診断 診断を有効にすると、`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` タイムアウト（待機のみ、エージェントは停止しない） ## 関連 * [ツール](/ja-JP/tools) - 利用可能なエージェントツール * [フック](/ja-JP/automation/hooks) - エージェントライフサイクルイベントによってトリガーされるイベント駆動スクリプト * [Compaction](/ja-JP/concepts/compaction) - 長い会話を要約する方法 * [実行承認](/ja-JP/tools/exec-approvals) - シェルコマンドの承認ゲート * [思考](/ja-JP/tools/thinking) - 思考/推論レベルの設定