Plugin フック

​

クイックスタート

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 },
    );
  },
});

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

​

フックカタログ

• subagent_spawned / subagent_ended - サブエージェントの起動と完了を観測します。
• subagent_delivery_target - コアのセッションバインディングでルートを投影できない場合の完了配信用互換フックです。
• subagent_spawning - 非推奨の互換フックです。現在、コアはsubagent_spawnedが発火する前に、チャンネルのセッションバインディングアダプターを通じてthread: trueサブエージェントバインディングを準備します。
• subagent_spawnedには、OpenClawが起動前に子セッションのネイティブモデルを解決している場合、resolvedModelとresolvedProviderが含まれます。
• subagent_endedは、targetSessionKey（ID - subagent_spawned.childSessionKeyと一致）、targetKind（"subagent"または"acp"）、reason、任意のoutcome（"ok"、"error"、"timeout"、"killed"、"reset"、または"deleted"）、任意のerror、runId、endedAt、accountId、sendFarewellを持ちます。agentIdまたはchildSessionKeyは含みません。一致するsubagent_spawnedイベントとの関連付けにはtargetSessionKeyを使用してください。

​

チャンネルペアリング要求

api.on("channel_pairing_requested", async (event) => {
  await notifyOperator({
    text: `New ${event.channel} pairing request from ${event.senderId}: ${event.code}`,
  });
});

​

デバッグランタイムフック

​

ツール呼び出しポリシー

• event.toolName
• event.params
• 任意の event.toolKind と event.toolInputKind: 意図的に名前を共有するツール向けの、ホストが権威を持つ判別子。たとえば、外側のコードモード exec 呼び出しは toolKind: "code_mode_exec" を使用し、入力言語が既知の場合は toolInputKind: "javascript" | "typescript" を含みます
• 任意の event.derivedPaths: apply_patch などの既知のツールエンベロープに対してホストがベストエフォートで導出した対象パスのヒント。これらのパスは、ツールが実際に触れる内容に対して不完全または過大近似である場合があります（たとえば、不正な形式または部分的な入力の場合）
• 任意の event.runId
• 任意の event.toolCallId
• ctx.agentId、ctx.sessionKey、ctx.sessionId、ctx.runId、ctx.toolKind、ctx.toolInputKind、診断用の 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";
    allowedDecisions?: Array<"allow-once" | "allow-always" | "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 承認の両方を承認できます。Codex app-server レポートモードのネイティブ PreToolUse リレーでは、これは対応する app-server 承認リクエストに委譲されます。Codex harness runtime を参照してください。
• 高優先度のフックが承認を要求した後でも、低優先度の block: true はブロックできます。
• onResolution は解決済みの決定を受け取ります: allow-once、allow-always、deny、timeout、または cancelled。

​

Exec 環境フック

• event.sessionKey
• event.toolName、現在は常に "exec"
• event.host、"gateway"、"sandbox"、または "node" のいずれか
• ctx.agentId、ctx.sessionKey、ctx.messageProvider、ctx.channelId などのコンテキストフィールド

​

ツール結果の永続化

• 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: 現在のプロンプト、準備済みセッションメッセージ、このセッション向けに排出された正確に一度だけのキュー済み注入を受け取ります。prependContext または appendContext を返します。
• before_prompt_build: 現在のプロンプトとセッションメッセージを受け取ります。prependContext、appendContext、systemPrompt、prependSystemContext、または appendSystemContext を返します。
• heartbeat_prompt_contribution: Heartbeat ターンでのみ実行され、prependContext または appendContext を返します。ユーザー起点のターンを変更せずに現在状態を要約する必要があるバックグラウンドモニター向けです。

• ctx.senderId - チャンネルスコープの送信者 ID（例: Feishu open_id、Discord ユーザー ID）。実行が既知の送信者メタデータを持つユーザーメッセージに由来する場合に設定されます。
• ctx.chatId - トランスポートネイティブの会話識別子（例: Feishu chat_id、Telegram chat_id）。起点チャンネルがネイティブ会話 ID を提供する場合に設定されます。
• ctx.channelContext.sender.id - ctx.senderId と同じ送信者 ID。Plugin がチャンネル固有フィールドで拡張できるチャンネル所有オブジェクト配下にあります。
• ctx.channelContext.chat.id - ctx.chatId と同じ会話 ID。Plugin がチャンネル固有フィールドで拡張できるチャンネル所有オブジェクト配下にあります。

declare module "openclaw/plugin-sdk/channel-inbound" {
  interface PluginHookChannelSenderContext {
    unionId?: string;
    userId?: string;
  }
}

buildChannelInboundEventContext({
  // ...
  channelContext: {
    sender: { id: senderOpenId, unionId, userId },
    chat: { id: chatId },
  },
});

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

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

​

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

​

メッセージ hooks

• message_received: 受信コンテンツ、送信者、threadId、 messageId、senderId、任意の実行/セッション相関、メタデータを監視します。
• message_sending: content を書き換えるか、{ cancel: true } を返します。
• reply_payload_sending: 正規化済みの ReplyPayload オブジェクト （presentation、delivery、メディア参照、テキストを含む）を書き換えるか、 { cancel: true } を返します。
• message_sent: 最終的な成功または失敗を監視します。

• cancel: true を含む message_sending は終端です。
• cancel: false を含む message_sending は判断なしとして扱われます。
• 書き換えられた content は、後続の hook が配信をキャンセルしない限り、より低優先度の hooks に進みます。
• reply_payload_sending はペイロード正規化後、チャンネル配信前に実行されます。これには発信元チャンネルへ戻る返信も含まれます。 ハンドラーは順番に実行され、各ハンドラーは高優先度ハンドラーによって生成された最新のペイロードを見ます。
• reply_payload_sending のペイロードは、trustedLocalMedia のようなランタイム信頼マーカーを公開しません。plugins はペイロード形状を編集できますが、ローカルメディア信頼を付与することはできません。
• message_sending は、キャンセル時に cancelReason と有界な metadata を返せます。新しいメッセージライフサイクル API は、これを理由 cancelled_by_message_sending_hook の抑制された配信結果として公開します。従来の直接配信は互換性のために空の結果配列を返し続けます。
• message_sent は監視専用です。ハンドラーの失敗はログに記録され、配信結果は変更されません。

​

インストール hooks

​

Gateway ライフサイクル

​

今後の非推奨

• inbound_claim および message_received ハンドラーの 平文チャンネルエンベロープ。 フラットなエンベロープテキストを解析する代わりに、BodyForAgent と構造化されたユーザーコンテキストブロックを読んでください。 平文チャンネルエンベロープ → BodyForAgent を参照してください。
• before_agent_start は互換性のために残っています。新しい plugins は、結合フェーズの代わりに before_model_resolve と before_prompt_build を使用してください。
• subagent_spawning は古い plugins との互換性のために残っていますが、新しい plugins はここからスレッドルーティングを返すべきではありません。core は subagent_spawned が発火する前に、チャンネルのセッションバインディングアダプターを通じて thread: true のサブエージェントバインディングを準備します。
• deactivate は、2026-08-16 以降まで、非推奨のクリーンアップ互換エイリアスとして残ります。新しい plugins は gateway_stop を使用してください。
• before_tool_call の onResolution は、自由形式の string ではなく、型付きの PluginApprovalResolution union（allow-once / allow-always / deny / timeout / cancelled）を使用するようになりました。
• api.registerSessionExtension / api.enqueueNextTurnInjection は、トップレベルの互換エイリアスとして残っています。新しい plugins は api.session.state.registerSessionExtension(...) と api.session.workflow.enqueueNextTurnInjection(...) を使用してください。

​

関連

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