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 - 僅供相容性的合併階段；建議使用上方兩個掛鉤
• before_agent_run - 在提交給模型前檢查最終提示與工作階段訊息，並可選擇封鎖執行
• 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 - 追蹤工作階段生命週期邊界。事件的 reason 是 new、reset、idle、daily、compaction、deleted、shutdown、restart 或 unknown 之一。當程序在工作階段仍作用中時停止或重新啟動，shutdown 與 restart 值會由 gateway 關閉終結器觸發，因此下游 Plugin（例如記憶體或逐字稿儲存）可以完成原本會在重新啟動後留在開啟狀態的幽靈資料列。終結器有界限，因此緩慢的 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：接收目前提示、已準備的工作階段訊息，以及為此工作階段取出的任何正好一次佇列注入。回傳 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
        }
      }
    }
  }
}

​

工作階段擴充與下一 turn 注入

​

訊息 hooks

• message_received：觀察傳入內容、寄件者、threadId、messageId、senderId、選用的執行/工作階段關聯，以及中繼資料。
• message_sending：重寫 content 或回傳 { cancel: true }。
• message_sent：觀察最終成功或失敗。

• 帶有 cancel: true 的 message_sending 是終止決策。
• 帶有 cancel: false 的 message_sending 會被視為沒有決策。
• 重寫的 content 會繼續傳遞給較低優先序 hooks，除非後續 hook 取消傳遞。
• message_sending 可以在取消時回傳 cancelReason 和有界的 metadata。新的訊息生命週期 API 會將此公開為原因為 cancelled_by_message_sending_hook 的受抑制傳遞結果；舊版直接傳遞則為了相容性繼續回傳空結果陣列。
• message_sent 僅供觀察。處理常式失敗會被記錄，且不會變更傳遞結果。

​

安裝 hooks

​

Gateway 生命週期

​

即將棄用

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

​

相關

• Plugin SDK 遷移 - 作用中的棄用項目與移除時程
• 建構 Plugin
• Plugin SDK 概觀
• Plugin 進入點
• 內部 hooks
• Plugin 架構內部