插件钩子

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 - 消耗排队的插件轮次注入，并在提示词钩子之前添加同轮次上下文
• before_prompt_build - 在模型调用之前添加动态上下文或系统提示词文本
• before_agent_start - 仅兼容用的组合阶段；优先使用上面的两个钩子
• before_agent_run - 在提交给模型之前检查最终提示词和会话消息，并可选择阻止运行
• before_agent_reply - 用合成回复或静默短路模型轮次
• before_agent_finalize - 检查自然最终答案并请求再运行一次模型
• agent_end - 观察最终消息、成功状态和运行时长
• heartbeat_prompt_contribution - 为后台监控和生命周期插件添加仅限 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 网关关闭终结器触发，因此下游插件（例如记忆或转录存储）可以最终确定本来会在重启之间一直处于打开状态的幽灵行。终结器有边界限制，因此缓慢的插件无法阻塞 SIGTERM/SIGINT。
• before_compaction / after_compaction - 观察或注释压缩周期
• before_reset - 观察会话重置事件（/reset、程序化重置）

• subagent_spawning / subagent_delivery_target / subagent_spawned / subagent_ended - 协调子智能体路由和完成投递

• gateway_start / gateway_stop - 随 Gateway 网关启动或停止插件拥有的服务
• cron_changed - 观察 Gateway 网关拥有的 cron 生命周期变更（已添加、已更新、已移除、已启动、已完成、已调度）
• before_install - 检查技能或插件安装扫描，并可选择阻止

​

工具调用策略

• 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 会暂停智能体运行，并通过插件批准向用户询问。/approve 命令可以批准 exec 和插件批准。
• 在更高优先级钩子请求批准之后，更低优先级的 block: true 仍然可以阻止。
• onResolution 会收到已解析的批准决策 - allow-once、allow-always、deny、timeout 或 cancelled。

​

工具结果持久化

• 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：仅在 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 为兼容性仍然保留。新插件应使用 before_model_resolve 和 before_prompt_build，而不是组合阶段。
• before_tool_call 中的 onResolution 现在使用带类型的 PluginApprovalResolution 联合（allow-once / allow-always / deny / timeout / cancelled），而不是自由格式的 string。

​

相关

• 插件 SDK 迁移 - 活跃废弃项和移除时间线
• 构建插件
• 插件 SDK 概览
• 插件入口点
• 内部钩子
• 插件架构内部机制