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 — 選用的每個掛鉤預算。設定後，掛鉤執行器會在預算耗盡後中止該處理常式並繼續下一個，而不是讓緩慢的設定或回想工作消耗呼叫端設定的模型逾時。省略它以使用掛鉤執行器通用套用的預設觀察/決策逾時。

​

掛鉤目錄

• before_model_resolve — 在載入工作階段訊息前覆寫提供者或模型
• agent_turn_prepare — 取用佇列中的 Plugin 回合注入，並在提示掛鉤前加入同回合內容
• before_prompt_build — 在模型呼叫前加入動態內容或系統提示文字
• before_agent_start — 僅供相容性的合併階段；偏好使用上方兩個掛鉤
• before_agent_reply — 以合成回覆或靜默短路模型回合
• before_agent_finalize — 檢查自然最終答案並要求再執行一次模型傳遞
• 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.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：接收目前提示、已準備的工作階段訊息，以及為此工作階段取出的任何精確一次佇列注入。回傳 prependContext 或 appendContext。
• before_prompt_build：接收目前提示與工作階段訊息。回傳 prependContext、appendContext、systemPrompt、prependSystemContext 或 appendSystemContext。
• heartbeat_prompt_contribution：只會在 Heartbeat 回合執行，並回傳 prependContext 或 appendContext。它適用於需要摘要目前狀態、但不改變使用者發起回合的背景監控器。

{
  "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 會繼續傳遞給較低優先順序的掛鉤，除非後續掛鉤取消傳遞。

​

安裝掛鉤

​

Gateway 生命週期

​

即將棄用

• 明文通道信封，位於 inbound_claim 和 message_received 處理常式中。請讀取 BodyForAgent 和結構化的使用者情境區塊，而不是剖析扁平信封文字。請參閱 明文通道信封 → BodyForAgent。
• before_agent_start 會保留以維持相容性。新的 Plugin 應使用 before_model_resolve 和 before_prompt_build，而不是合併階段。
• before_tool_call 中的 onResolution 現在使用具型別的 PluginApprovalResolution 聯集（allow-once / allow-always / deny / timeout / cancelled），而不是自由格式的 string。

​

相關

• Plugin SDK 遷移 — 作用中的棄用項目與移除時程
• 建置 Plugin
• Plugin SDK 概觀
• Plugin 進入點
• 內部掛鉤
• Plugin 架構內部細節