外掛鉤子

​

快速開始

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 子代理繫結。
• 當 OpenClaw 已在啟動前解析子工作階段的原生模型時，subagent_spawned 會包含 resolvedModel 和 resolvedProvider。
• subagent_ended 會攜帶 targetSessionKey（身分 - 符合 subagent_spawned.childSessionKey）、targetKind（"subagent" 或 "acp"）、reason、選用的 outcome（"ok"、"error"、"timeout"、"killed"、"reset" 或 "deleted"）、選用的 error、runId、endedAt、accountId 和 sendFarewell。它不包含 agentId 或 childSessionKey；請使用 targetSessionKey 關聯相符的 subagent_spawned 事件。

​

頻道配對要求

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 會暫停代理程式執行，並透過外掛核准向使用者詢問。/approve 可以同時核准 exec 和外掛核准。在 Codex app-server 報告模式原生 PreToolUse 轉送中，這會讓渡給相符的 app-server 核准請求；請參閱 Codex 測試框架執行階段。
• 較低優先順序的 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 會在供應商重播和壓縮輸入前移除 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：只在心跳偵測回合執行，並回傳 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，位於頻道擁有的物件下，外掛可用頻道特定欄位擴充該物件。
• ctx.channelContext.chat.id - 與 ctx.chatId 相同的對話 ID，位於頻道擁有的物件下，外掛可用頻道特定欄位擴充該物件。

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 會繼續傳遞給較低優先序的 hooks，除非後續 hook 取消傳遞。
• reply_payload_sending 會在承載內容正規化後、通道傳遞前執行，包括路由回原始通道的回覆。處理常式會依序執行，且每個處理常式都會看到較高優先序處理常式產生的最新承載內容。
• reply_payload_sending 承載內容不會公開執行階段信任標記，例如 trustedLocalMedia；外掛可以編輯承載內容形狀，但不能授予本機媒體信任。
• message_sending 可以在取消時回傳 cancelReason 和有界的 metadata。新的訊息生命週期 API 會將其公開為原因為 cancelled_by_message_sending_hook 的已抑制傳遞結果；舊版直接傳遞為了相容性仍會回傳空結果陣列。
• message_sent 僅供觀察。處理常式失敗會被記錄，且不會改變傳遞結果。

​

安裝 hooks

​

閘道生命週期

​

即將棄用

• 純文字通道信封，位於 inbound_claim 和 message_received 處理常式中。請讀取 BodyForAgent 和結構化使用者內容區塊，而不是剖析扁平信封文字。請參閱 純文字通道信封 → BodyForAgent。
• before_agent_start 會為了相容性保留。新的外掛應使用 before_model_resolve 和 before_prompt_build，而不是合併階段。
• subagent_spawning 會為了與較舊外掛相容而保留，但新的外掛不應從中回傳執行緒路由。核心會在 subagent_spawned 觸發前，透過通道工作階段繫結配接器準備 thread: true 子代理繫結。
• deactivate 會作為已棄用的清理相容性別名保留到 2026-08-16 之後。新的外掛應使用 gateway_stop。
• before_tool_call 中的 onResolution 現在使用具型別的 PluginApprovalResolution 聯集（allow-once / allow-always / deny / timeout / cancelled），而不是自由格式的 string。
• api.registerSessionExtension / api.enqueueNextTurnInjection 會作為頂層相容性別名保留。新的外掛應使用 api.session.state.registerSessionExtension(...) 和 api.session.workflow.enqueueNextTurnInjection(...)。

​

相關

• 外掛 SDK 遷移 - 作用中的棄用項目與移除時間表
• 建置外掛
• 外掛 SDK 概觀
• 外掛進入點
• 內部 hooks
• 外掛架構內部細節