Plugin フック

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.

​

クイックスタート

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";

export default definePluginEntry({
  id: "tool-preflight",
  name: "Tool Preflight",
  register(api) {
    api.on(
      "before_tool_call",
      async (event) => {
        if (event.toolName !== "web_search") {
          return;
        }

        return {
          requireApproval: {
            title: "Run web search",
            description: `Allow search query: ${String(event.params.query ?? "")}`,
            severity: "info",
            timeoutMs: 60_000,
            timeoutBehavior: "deny",
          },
        };
      },
      { priority: 50 },
    );
  },
});

• priority - ハンドラーの順序（高いほど先に実行）。
• timeoutMs - フックごとの任意の予算。設定すると、フックランナーは予算経過後にそのハンドラーを中断し、次のハンドラーへ進みます。遅いセットアップやリコール処理が呼び出し元に設定されたモデルタイムアウトを消費し続けることを防ぎます。省略すると、フックランナーが汎用的に適用するデフォルトの観測/判断タイムアウトを使用します。

{
  "plugins": {
    "entries": {
      "my-plugin": {
        "hooks": {
          "timeoutMs": 30000,
          "timeouts": {
            "before_prompt_build": 90000,
            "agent_end": 60000
          }
        }
      }
    }
  }
}

​

フックカタログ

• before_model_resolve - セッションメッセージが読み込まれる前にプロバイダーまたはモデルを上書きします
• agent_turn_prepare - キュー済みの plugin ターン注入を消費し、プロンプトフックの前に同一ターンのコンテキストを追加します
• before_prompt_build - モデル呼び出しの前に動的コンテキストまたはシステムプロンプトテキストを追加します
• before_agent_start - 互換性専用の結合フェーズです。上記 2 つのフックを優先してください
• before_agent_run - モデル送信前に最終プロンプトとセッションメッセージを検査し、必要に応じて実行をブロックします
• before_agent_reply - 合成返信または沈黙でモデルターンを短絡します
• before_agent_finalize - 自然な最終回答を検査し、もう 1 回のモデルパスを要求します
• agent_end - 最終メッセージ、成功状態、実行時間を観測します
• heartbeat_prompt_contribution - バックグラウンドモニターおよびライフサイクル plugins 向けに、Heartbeat 専用コンテキストを追加します

• model_call_started / model_call_ended - プロンプトやレスポンス内容なしで、サニタイズされたプロバイダー/モデル呼び出しメタデータ、タイミング、結果、境界付きリクエスト ID ハッシュを観測します
• llm_input - プロバイダー入力（システムプロンプト、プロンプト、履歴）を観測します
• llm_output - プロバイダー出力を観測します

• before_tool_call - ツールパラメーターを書き換え、実行をブロックし、または承認を要求します
• after_tool_call - ツール結果、エラー、所要時間を観測します
• tool_result_persist - ツール結果から生成されたアシスタントメッセージを書き換えます
• before_message_write - 進行中のメッセージ書き込みを検査またはブロックします（まれ）

• inbound_claim - エージェントルーティング前に受信メッセージを要求します（合成返信）
• message_received - 受信内容、送信者、スレッド、メタデータを観測します
• message_sending - 送信内容を書き換える、または配信をキャンセルします
• message_sent - 送信配信の成功または失敗を観測します
• before_dispatch - チャネル引き渡し前に送信ディスパッチを検査または書き換えます
• reply_dispatch - 最終返信ディスパッチパイプラインに参加します

• session_start / session_end - セッションライフサイクル境界を追跡します。イベントの reason は、new、reset、idle、daily、compaction、deleted、shutdown、restart、または unknown のいずれかです。shutdown と restart の値は、セッションがまだアクティブな状態でプロセスが停止または再起動された場合に、gateway シャットダウンファイナライザーから発火します。これにより、メモリやトランスクリプトストアなどの下流 plugins は、再起動をまたいで開いた状態のまま残るはずだったゴースト行を確定できます。低速な plugin が SIGTERM/SIGINT をブロックできないよう、ファイナライザーには境界があります。
• before_compaction / after_compaction - Compaction サイクルを観測または注釈付けします
• before_reset - セッションリセットイベント（/reset、プログラムによるリセット）を観測します

• subagent_spawning / subagent_delivery_target / subagent_spawned / subagent_ended - サブエージェントルーティングと完了配信を調整します

• gateway_start / gateway_stop - Gateway とともに plugin 所有サービスを開始または停止します
• cron_changed - gateway 所有の Cron ライフサイクル変更（追加、更新、削除、開始、終了、スケジュール）を観測します
• before_install - skill または plugin のインストールスキャンを検査し、必要に応じてブロックします

​

ツール呼び出しポリシー

• event.toolName
• event.params
• 任意の event.derivedPaths。apply_patch などのよく知られたツールエンベロープについて、ホストがベストエフォートで導出した対象パスのヒントを含みます。存在する場合、これらのパスは不完全な場合や、ツールが実際に触れる範囲を過大に近似している場合があります（たとえば、不正な形式または部分的な入力の場合）
• 任意の event.runId
• 任意の event.toolCallId
• ctx.agentId、ctx.sessionKey、ctx.sessionId、ctx.runId、ctx.jobId（Cron 駆動の実行で設定）、診断用の ctx.trace などのコンテキストフィールド

type BeforeToolCallResult = {
  params?: Record<string, unknown>;
  block?: boolean;
  blockReason?: string;
  requireApproval?: {
    title: string;
    description: string;
    severity?: "info" | "warning" | "critical";
    timeoutMs?: number;
    timeoutBehavior?: "allow" | "deny";
    pluginId?: string;
    onResolution?: (
      decision: "allow-once" | "allow-always" | "deny" | "timeout" | "cancelled",
    ) => Promise<void> | void;
  };
};

• block: true は終端であり、低優先度のハンドラーをスキップします。
• block: false は判断なしとして扱われます。
• params は実行用のツールパラメーターを書き換えます。
• requireApproval はエージェント実行を一時停止し、plugin 承認を通じてユーザーに確認します。/approve コマンドは exec と plugin 承認の両方を承認できます。
• 高優先度のフックが承認を要求した後でも、低優先度の block: true は引き続きブロックできます。
• onResolution は解決済みの承認判断（allow-once、allow-always、deny、timeout、または cancelled）を受け取ります。

​

ツール結果の永続化

• OpenClaw は、メタデータがモデルコンテキストにならないように、プロバイダー再生および Compaction 入力の前に toolResult.details を取り除きます。
• 永続化されたセッションエントリは、境界付きの details のみを保持します。大きすぎる details はコンパクトな要約と persistedDetailsTruncated: true に置き換えられます。
• tool_result_persist と before_message_write は最終的な永続化上限の前に実行されます。それでもフックは、返す details を小さく保ち、プロンプトに関連するテキストを details だけに置かないようにするべきです。モデルから見えるツール出力は content に入れてください。

​

プロンプトとモデルフック

• before_model_resolve: 現在のプロンプトと添付メタデータのみを受け取ります。providerOverride または modelOverride を返します。
• agent_turn_prepare: 現在のプロンプト、準備済みセッションメッセージ、このセッションについてドレインされた exactly-once のキュー済み注入を受け取ります。prependContext または appendContext を返します。
• before_prompt_build: 現在のプロンプトとセッションメッセージを受け取ります。prependContext、appendContext、systemPrompt、prependSystemContext、または appendSystemContext を返します。
• heartbeat_prompt_contribution: Heartbeat ターンでのみ実行され、prependContext または appendContext を返します。ユーザー起点のターンを変更せずに現在状態を要約する必要があるバックグラウンドモニター向けです。

type BeforeAgentFinalizeRetry = {
  instruction: string;
  idempotencyKey?: string;
  maxAttempts?: number;
};

{
  "plugins": {
    "entries": {
      "my-plugin": {
        "hooks": {
          "allowConversationAccess": true
        }
      }
    }
  }
}

​

セッション拡張と次ターン注入

​

メッセージフック

• message_received: 受信コンテンツ、送信者、threadId、messageId、 senderId、任意の実行/セッション相関、およびメタデータを監視します。
• message_sending: content を書き換えるか、{ cancel: true } を返します。
• message_sent: 最終的な成功または失敗を監視します。

• cancel: true を伴う message_sending は終端です。
• cancel: false を伴う message_sending は、判定なしとして扱われます。
• 書き換えられた content は、後続のフックが配信をキャンセルしない限り、低優先度のフックへ続きます。
• message_sending は、キャンセルとともに cancelReason と境界付きの metadata を返せます。 新しいメッセージライフサイクル API は、これを理由 cancelled_by_message_sending_hook の抑止された配信結果として公開します。 レガシーの直接配信は、互換性のため空の結果配列を返し続けます。
• message_sent は監視専用です。ハンドラーの失敗はログに記録され、配信結果は変更されません。

​

インストールフック

​

Gateway ライフサイクル

​

今後の非推奨

• inbound_claim および message_received ハンドラーの 平文チャネルエンベロープ。 フラットなエンベロープテキストを解析する代わりに、BodyForAgent と構造化されたユーザーコンテキストブロックを読んでください。 平文チャネルエンベロープ → BodyForAgent を参照してください。
• before_agent_start は互換性のために残っています。新しい Plugin は、結合されたフェーズの代わりに before_model_resolve と before_prompt_build を使用してください。
• before_tool_call の onResolution は、自由形式の string ではなく、型付きの PluginApprovalResolution ユニオン（allow-once / allow-always / deny / timeout / cancelled）を使用するようになりました。

​

関連

• Plugin SDK 移行 - アクティブな非推奨と削除タイムライン
• Plugin の構築
• Plugin SDK 概要
• Plugin エントリポイント
• 内部フック
• Plugin アーキテクチャ内部