插件钩子

Documentation Index

Fetch the complete documentation index at: https://openclaw.zhcndoc.com/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: "运行网页搜索",
            description: `允许搜索查询：${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 — 在加载 session 消息之前覆盖提供方或模型
• agent_turn_prepare — 在 prompt 钩子之前消费已排队的插件回合注入并添加同回合上下文
• before_prompt_build — 在模型调用前添加动态上下文或系统提示词文本
• before_agent_start — 仅兼容的组合阶段；优先使用上面两个钩子
• 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 — 重写 tool 参数、阻止执行，或要求批准
• after_tool_call — 观察 tool 结果、错误和持续时间
• tool_result_persist — 重写从 tool 结果生成的 assistant 消息
• before_message_write — 检查或阻止正在进行的消息写入（较少见）

• inbound_claim — 在 agent 路由前认领一条入站消息（合成回复）
• message_received — 观察入站内容、发送者、线程和元数据
• message_sending — 重写出站内容或取消传递
• message_sent — 观察出站传递成功或失败
• before_dispatch — 在通道交接前检查或重写一次出站派发
• reply_dispatch — 参与最终的回复派发流水线

• session_start / session_end — 跟踪 session 生命周期边界
• before_compaction / after_compaction — 观察或注释压缩周期
• before_reset — 观察 session 重置事件（/reset、程序化重置）

• subagent_spawning / subagent_delivery_target / subagent_spawned / subagent_ended — 协调 subagent 路由和完成投递

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

​

Tool 调用策略

• 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 会重写执行时的 tool 参数。
• requireApproval 会暂停 agent 运行，并通过插件批准流程询问用户。/approve 命令可以批准 exec 和插件批准。
• 即使较高优先级的钩子请求了批准，较低优先级的 block: true 仍然可以随后阻止。
• onResolution 会接收已解析的批准决策——allow-once、allow-always、deny、timeout 或 cancelled。

​

Tool 结果持久化

• OpenClaw 会在 provider 回放和压缩输入之前去除 toolResult.details，因此元数据不会变成模型上下文。
• 持久化的 session 条目只保留有边界限制的 details。过大的 details 会被替换为紧凑摘要，并标记 persistedDetailsTruncated: true。
• tool_result_persist 和 before_message_write 会在最终持久化上限之前运行。钩子仍应保持返回的 details 足够小，并避免只把与提示词相关的文本放在 details 中；应把模型可见的 tool 输出放在 content 中。

​

提示词与模型钩子

• before_model_resolve：只接收当前提示词和附件元数据。返回 providerOverride 或 modelOverride。
• agent_turn_prepare：接收当前提示词、已准备好的 session 消息，以及为该 session 取出的任何一次性排队注入。返回 prependContext 或 appendContext。
• before_prompt_build：接收当前提示词和 session 消息。返回 prependContext、appendContext、systemPrompt、prependSystemContext 或 appendSystemContext。
• heartbeat_prompt_contribution：仅在 heartbeat 回合运行，返回 prependContext 或 appendContext。它面向需要总结当前状态但不改变用户发起回合的后台监视器。

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

​

Session 扩展与下一回合注入

​

消息钩子

• message_received：观察入站内容、发送者、threadId、messageId、 senderId、可选的运行/会话关联信息以及元数据。
• message_sending：重写 content 或返回 { cancel: true }。
• message_sent：观察最终成功或失败。

• message_sending 携带 cancel: true 时为终态。
• message_sending 携带 cancel: false 时视为没有决策。
• 重写后的 content 会继续传递给低优先级钩子，除非后续某个钩子取消投递。

​

安装钩子

​

网关生命周期

​

即将弃用

• 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 概览
• 插件入口点
• 内部钩子
• 插件架构内部