Plugin フック

Documentation Index

Fetch the complete documentation index at: https://docs.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 - バックグラウンドモニターおよびライフサイクル Plugin 向けに 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 - セッションライフサイクル境界を追跡する
• 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 - Skills または 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 アーキテクチャ内部