Fundamentals

エージェントループ

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

エントリーポイント

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

実行シーケンス

agent RPC はパラメーターを検証し、セッション（sessionKey/sessionId）を解決し、セッションメタデータを永続化して、直ちに { runId, acceptedAt } を返します。
agentCommand はターンを実行します。モデルと thinking/verbose/trace のデフォルトを解決し、Skills のスナップショットを読み込み、runEmbeddedAgent を呼び出します。また、組み込みループがまだ発行していない場合は、フォールバックの ライフサイクル終了/エラー を発行します。
runEmbeddedAgent: セッション単位およびグローバルキューを介して実行を直列化し、モデルと認証プロファイルを解決し、OpenClaw セッションを構築し、ランタイムイベントを購読し、アシスタント/ツールの差分をストリーミングし、実行タイムアウトを適用して（期限切れ時に中止）、ペイロードと使用量メタデータを返します。Codex app-server のターンでは、受理されたターンが終端イベントの前に app-server の進行を生成しなくなった場合も中止します。
subscribeEmbeddedAgentSession はランタイムイベントを agent ストリームへ橋渡しします。ツールイベントは stream: "tool"、アシスタント差分は stream: "assistant"、ライフサイクルイベントは stream: "lifecycle"（phase: "start" | "end" | "error"）へ送られます。
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_model_resolve`	セッション前（`messages` なし）。解決前にプロバイダー/モデルを決定論的に上書きします。
`before_prompt_build`	セッション読み込み後（`messages` あり）。送信前に `prependContext`、`systemPrompt`、`prependSystemContext`、または `appendSystemContext` を注入します。ターン単位の動的テキストには `prependContext` を使用し、システムプロンプト領域に属する安定したガイダンスにはシステムコンテキストフィールドを使用します。
`before_agent_reply`	インラインアクションの後、LLM 呼び出しの前。Plugin がターンを引き受け、合成された返信を返すか、完全に無応答にできます。
`agent_end`	完了後。最終メッセージリストと実行メタデータを伴います。
`before_compaction` / `after_compaction`	Compaction サイクルを監視または注釈します。
`before_tool_call` / `after_tool_call`	ツールのパラメーター/結果をインターセプトします。
`before_install`	オペレーターのインストールポリシー実行後、ステージングされた Skills/Plugin インストール素材に対して、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 フックを参照してください。

ハーネスはこれらのフックに適応できます。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 は、ライフサイクル終了/エラー 時に発行されます。

タイムアウト

タイムアウト	デフォルト	注記
`agent.wait`	30s	待機のみに適用されます。`timeoutMs` パラメーターで上書きできます。基盤となる実行は停止しません。
エージェントランタイム（`agents.defaults.timeoutSeconds`）	172800s (48h)	`runEmbeddedAgent` の中止タイマーによって適用されます。実行時間の上限をなくすには `0` を設定します。その場合も、モデルストリームの稼働監視ウォッチドッグは引き続き適用されます。
CLI バックエンドの出力なしウォッチドッグ	CLI の新規実行または再開ごとに算出	エージェントランタイムとは別で、登録済みのバックエンド Plugin が所有します。CLI 内部のバックグラウンドタスクは親サブプロセスを共有するため、エージェント全体のタイムアウト後も存続することはありません。
Cron の分離されたエージェントターン	cron が所有	スケジューラーは実行開始時に独自のタイマーを開始し、設定された期限に達すると実行を中止します。その後、タイムアウトを記録する前に時間制限付きのクリーンアップを実行するため、古い子セッションによってレーンが停止したままになることはありません。
モデルのアイドルタイムアウト	クラウド 120s、セルフホスト 300s	アイドル時間枠が終了するまでに応答チャンクが到着しない場合、OpenClaw はモデルリクエストを中止します。`models.providers.<id>.timeoutSeconds` は、低速なローカルまたはセルフホストプロバイダー向けにこのアイドルウォッチドッグを延長します。ただし、より短い有限の `agents.defaults.timeoutSeconds` または実行固有のタイムアウトがある場合、それらはエージェント実行全体を管理するため、その時間内に制限されます。実行時間の上限がない場合でも、プロバイダークラスのアイドルウォッチドッグは維持されます。明示的なモデルまたはエージェントのタイムアウトがない Cron 起動のクラウドモデル実行にも同じデフォルトが適用されます。Cron 実行のタイムアウトが明示されている場合、設定済みのモデルフォールバックを Cron の外側の期限までに実行できるよう、クラウドモデルのストリーム停止は最大 60s に制限されます。実際にローカルなエンドポイント（loopback/private baseUrl）で Cron から起動された実行では、ローカルのアイドル監視無効化が維持されます。ネットワーク baseUrl 上のセルフホストプロバイダーには、暗黙的な 300s のウォッチドッグが適用されます。Cron 実行のタイムアウトが明示されている場合、ローカルまたはセルフホストの停止時間はそのタイムアウトまでに制限されます。低速なローカルプロバイダーには `models.providers.<id>.timeoutSeconds` を設定してください。
プロバイダーの HTTP リクエストタイムアウト	`models.providers.<id>.timeoutSeconds`	そのプロバイダーに対する接続、ヘッダー、本文、SDK リクエストタイムアウト、保護された fetch の中止処理、およびモデルストリームのアイドルウォッチドッグを対象とします。エージェントランタイム全体のタイムアウトを延長する前に、低速なローカルまたはセルフホストプロバイダー（Ollama など）に使用してください。モデルリクエストをより長く実行する必要がある場合は、エージェントまたはランタイムのタイムアウトも少なくとも同じ長さに設定してください。

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

診断を有効にすると、組み込みの 2 分間のしきい値により、応答、ツール、ステータス、ブロック、または ACP の進行が観測されない長時間の processing セッションが分類されます。

アクティブな埋め込み実行、モデル呼び出し、およびツール呼び出しは session.long_running として報告されます。所有されている無応答のモデル呼び出しは中止しきい値まで session.long_running のままとなるため、低速または非ストリーミングのプロバイダーが早すぎる段階で停止と判定されることはありません。
最近の進行がないアクティブな処理は session.stalled として報告されます。所有されているモデル呼び出しは、中止しきい値以降に session.stalled へ切り替わります。所有者のいない古いモデルまたはツールのアクティビティが、長時間実行として隠されることはありません。
session.stuck は、所有者のいない古いモデルまたはツールのアクティビティがあるアイドル状態のキュー済みセッションなど、復旧可能な古いセッション管理情報のために予約されています。

中止しきい値は 5 分以上かつ警告しきい値の 3 倍です。復旧ゲートを通過すると、古いセッション管理情報によって影響を受けたセッションレーンは直ちに解放されます。停止した埋め込み実行は中止しきい値の経過後にのみ中止およびドレインされるため、単に低速な実行を途中で終了させることなく、キュー内の処理が再開されます。復旧時には、要求および完了の結果が構造化された形式で出力されます。診断状態がアイドルとして記録されるのは、同じ処理世代が引き続き最新である場合に限られます。また、セッションに変化がない間は、繰り返される session.stuck 診断の間隔が段階的に延長されます。

処理が早期終了する場合

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