插件钩子

​

快速开始

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 - 在会话消息加载前覆盖提供方或模型
• 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 - 观察提供方输出、用量，以及在可用时解析后的 contextTokenBudget

• before_tool_call - 重写工具参数、阻止执行，或要求批准
• after_tool_call - 观察工具结果、错误和持续时间
• resolve_exec_env - 向 exec 提供插件拥有的环境变量
• tool_result_persist - 重写由工具结果生成的 assistant 消息
• before_message_write - 检查或阻止正在进行中的消息写入（较少见）

• inbound_claim - 在 agent 路由前声明进入消息的处理权（合成回复）
• message_received — 观察进入内容、发送者、线程和元数据
• message_sending — 重写发出的内容或取消投递
• reply_payload_sending — 在投递前修改或取消规范化的回复负载
• message_sent — 观察发出投递的成功或失败
• before_dispatch - 在通道交接前检查或重写发出调度
• reply_dispatch - 参与最终的回复调度管道

• session_start / session_end - 跟踪 session 生命周期边界。该事件的 reason 取值为 new、reset、idle、daily、compaction、deleted、shutdown、restart 或 unknown 之一。shutdown 和 restart 的值会在 session 仍处于活动状态时进程停止或重启，由 Gateway shutdown finalizer 触发，因此下游插件（例如内存或转录存储）可以完成原本会在重启期间以打开状态遗留的幽灵行。该 finalizer 受到边界限制，因此缓慢的插件不会阻塞 SIGTERM/SIGINT。
• before_compaction / after_compaction - 观察或标注压缩周期
• before_reset - 观察 session 重置事件（/reset、程序化重置）

• subagent_spawned / subagent_ended - 观察 subagent 启动和完成。
• subagent_delivery_target - 当没有核心 session 绑定能够投影路由时，用于完成投递的兼容钩子。
• subagent_spawning - 已弃用的兼容钩子。核心现在会在 subagent_spawned 触发前，通过通道 session-binding 适配器准备 thread: true 的 subagent 绑定。
• 当 OpenClaw 在启动前已解析出子 session 的原生模型时，subagent_spawned 会包含 resolvedModel 和 resolvedProvider。

• gateway_start / gateway_stop - 随 Gateway 启动或停止插件拥有的服务
• deactivate - gateway_stop 的已弃用兼容别名；新插件请使用 gateway_stop
• cron_changed - 观察 Gateway 拥有的 cron 生命周期变化（added、updated、removed、started、finished、scheduled）
• before_install - 检查 skill 或插件安装上下文，并可选择阻止

​

调试运行时钩子

​

工具调用策略

• event.toolName
• event.params
• 可选的 event.toolKind 和 event.toolInputKind，用于有意共享名称的工具的宿主权威区分器；例如，外层 code-mode 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.jobId（在 cron 驱动的运行中设置）、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 会暂停 agent 运行，并通过插件批准向用户请求。/approve 命令可以同时批准 exec 和插件批准。在 Codex app-server report-mode 的原生 PreToolUse 中继里，这会延迟到匹配的 app-server 批准请求；参见 Codex harness runtime。
• 更低优先级的 block: true 即使在更高优先级钩子请求批准后仍然可以阻止。
• onResolution 接收已解析的批准决策 - allow-once、allow-always、deny、timeout 或 cancelled。

​

Exec environment hook

• event.sessionKey
• event.toolName，当前始终为 "exec"
• event.host，取值为 "gateway"、"sandbox" 或 "node"
• 上下文字段，例如 ctx.agentId、ctx.sessionKey、 ctx.messageProvider 和 ctx.channelId

​

Tool result persistence

• 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。它面向需要总结当前状态但不改变用户发起回合的后台监视器。

type BeforeAgentFinalizeRetry = {
    instruction: string;
    idempotencyKey?: string;
    maxAttempts?: number;
};

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

​

Session 扩展与下一回合注入

​

消息钩子

• message_received: 观察入站内容、发送者、threadId、messageId, senderId、可选的运行/会话关联以及元数据。
• message_sending: 重写 content 或返回 { cancel: true }。
• reply_payload_sending: 重写规范化后的 ReplyPayload 对象（包括 presentation、delivery、媒体引用和文本），或返回 { cancel: true }。
• message_sent: 观察最终成功或失败。

• message_sending with cancel: true is terminal.
• message_sending with cancel: false is treated as no decision.
• Rewritten content continues to lower-priority hooks unless a later hook cancels delivery.
• reply_payload_sending runs after payload normalization and before channel delivery, including replies routed back to the originating channel. Handlers run sequentially and each handler sees the latest payload produced by higher-priority handlers.
• reply_payload_sending payloads do not expose runtime trust markers such as trustedLocalMedia; plugins can edit payload shape but cannot grant local media trust.
• message_sending can return cancelReason and bounded metadata with a cancellation. New message lifecycle APIs expose this as a suppressed delivery outcome with reason cancelled_by_message_sending_hook; legacy direct delivery keeps returning an empty result array for compatibility.
• message_sent is observation-only. Handler failures are logged and do not change the delivery result.

​

安装钩子

​

网关生命周期

​

即将弃用

• Plaintext channel envelopes in inbound_claim and message_received handlers. Read BodyForAgent and the structured user-context blocks instead of parsing flat envelope text. See Plaintext channel envelopes → BodyForAgent.
• before_agent_start remains for compatibility. New plugins should use before_model_resolve and before_prompt_build instead of the combined phase.
• subagent_spawning remains for compatibility with older plugins, but new plugins should not return thread routing from it. Core prepares thread: true subagent bindings through channel session-binding adapters before subagent_spawned fires.
• deactivate remains as a deprecated cleanup compatibility alias until after 2026-08-16. New plugins should use gateway_stop.
• onResolution in before_tool_call now uses the typed PluginApprovalResolution union (allow-once / allow-always / deny / timeout / cancelled) instead of a free-form string.

​

相关内容

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