OpenClaw hook-钩子机制详解

前言OpenClaw 的钩子Hook系统是其核心扩展能力的载体通过事件驱动的方式实现对代理Agent和网关Gateway全生命周期的灵活管控与深度集成。整个钩子系统清晰分为两大类——内部钩子Internal Hooks和插件钩子Plugin Hooks二者各司其职、协同工作同时遵循统一的发现机制和决策规则为用户提供多样化的扩展可能。以下结合官方文档细节对其钩子机制进行全面详解。一、钩子系统整体分类OpenClaw 钩子系统的核心分类基于运行环境和功能定位分为内部钩子与插件钩子两大类二者在运行载体、响应范围和集成深度上存在明确差异共同覆盖从基础生命周期到深度业务扩展的全场景需求。一内部钩子Internal Hooks内部钩子是运行在 Gateway 内部的事件驱动脚本核心作用是响应各类命令执行和系统生命周期事件是 OpenClaw 基础运行逻辑的重要补充其相关定义可参考官方文档 hooks.md:11-16。内部钩子紧密绑定 Gateway 运行流程无需额外插件依赖即可实现对核心操作的监听与响应。1. 核心事件类型内部钩子主要监听以下事件参考 hooks.md:38-53覆盖命令、会话、网关、消息等核心场景每个事件对应明确的触发时机便于精准拦截和处理事件类型触发时机command:new/new 命令发出时command:reset/reset 命令发出时command:stop/stop 命令发出时command任何命令事件通用监听器session:compact:before压缩总结历史之前session:compact:after压缩完成后session:patch会话属性被修改时agent:bootstrap工作区引导文件注入之前gateway:startup通道启动和钩子加载后message:received来自任何通道的入站消息message:transcribed音频转录完成后message:preprocessed所有媒体和链接理解完成后message:sent出站消息发送后2. 内置内部钩子示例OpenClaw 内置了多个常用内部钩子参考 hooks.md:154-160无需用户自行开发启用后即可实现基础功能降低扩展成本session-memory自动保存会话上下文到 workspace/memory/ 目录实现会话记忆的持久化bootstrap-extra-files在 agent bootstrap 阶段工作区引导文件注入前注入额外的引导文件扩展代理初始化逻辑command-logger将所有命令操作记录到 ~/.openclaw/logs/commands.log 文件便于审计和问题排查boot-md在 Gateway 启动时自动运行 BOOT.md 文件实现启动阶段的自定义脚本执行。二插件钩子Plugin Hooks插件钩子是运行在 agent 循环或 gateway 管道中的扩展点相比内部钩子提供更深度的集成能力可实现对代理运行流程的精细化干预参考 agent-loop.md:80-96。插件钩子依赖插件部署通常用于复杂业务场景的扩展支持更灵活的功能定制。1. 主要插件钩子类型插件钩子覆盖代理运行、会话管理、工具调用、消息流转等全流程每个钩子都有明确的运行时机和核心用途具体如下钩子名称运行时机用途before_model_resolve会话前无 messages确定性地覆盖 provider/model实现模型的灵活切换before_prompt_build会话加载后有 messages注入上下文或修改系统提示优化 LLM 推理逻辑before_agent_start兼容性钩子旧版兼容建议使用上述两个明确钩子替代before_agent_reply内联操作后LLM 调用前声明回合并返回合成回复干预代理回复逻辑agent_end完成后检查最终消息列表和运行元数据进行后续处理before_compaction / after_compaction压缩周期观察或注释压缩周期干预会话历史压缩逻辑before_tool_call / after_tool_call工具执行前后拦截工具参数/结果实现工具调用的安全管控和结果优化before_install安装前检查内置扫描结果并阻止安装保障系统安全tool_result_persist持久化前同步转换工具结果确保持久化数据格式规范message_received / message_sending / message_sent消息流入站和出站消息钩子实现消息的过滤、修改和监控session_start / session_end会话生命周期会话边界监听实现会话的初始化和清理逻辑gateway_start / gateway_stopGateway 生命周期Gateway 事件监听实现网关启动和停止的自定义处理二、钩子核心规则OpenClaw 钩子机制遵循明确的决策规则和发现机制确保钩子的有序执行、优先级管控和安全运行避免冲突和异常。一钩子决策规则针对出站消息和工具调用相关的守卫类钩子OpenClaw 制定了明确的终止性规则参考 agent-loop.md:97-105用于规范钩子的执行效果避免重复干预或无效操作before_tool_call: { block: true }属于终止性操作会停止低优先级处理器的执行强制拦截工具调用before_tool_call: { block: false }属于无操作不会影响后续处理器执行也不会清除先前设置的阻止状态before_install: { block: true }属于终止性操作会直接阻止插件或工具的安装流程message_sending: { cancel: true }属于终止性操作会取消出站消息的发送流程。二钩子发现机制OpenClaw 会按固定的优先级顺序发现和加载钩子参考 hooks.md:133-141优先级从高到低依次为确保核心钩子优先执行避免冲突内置钩子随 OpenClaw 系统一同提供优先级最高无法被覆盖确保系统基础功能的稳定性插件钩子安装在插件内的钩子优先级次之由插件管理随插件的启用/禁用而生效/失效托管钩子部署在 ~/.openclaw/hooks/ 目录下由用户安装可跨工作区共享优先级低于插件钩子工作区钩子部署在 workspace/hooks/ 目录下针对单个代理生效默认处于禁用状态优先级最低。三、OpenClaw 钩子编写规范与示例OpenClaw 支持两种钩子编写方式分别为内部钩子目录发现式和插件钩子API 注册式以下是详细编写规范、实现示例及最佳实践。一、内部钩子编写规范1.1 目录结构要求每个内部钩子必须包含固定目录结构参考 hooks.md:58-64缺一不可my-hook/ # 钩子根目录名称可自定义├── HOOK.md # 钩子元数据、描述及详细文档└── handler.ts # 钩子核心逻辑处理器实现1.2 HOOK.md 格式规范HOOK.md 需遵循固定的 Frontmatter 格式开头用 --- 包裹元数据后续为详细文档示例如下--- name: my-hook # 钩子唯一名称必填description: 钩子简短描述 # 钩子功能简要说明必填metadata: # OpenClaw 专属元数据必填{ openclaw: { emoji: , events: [command:new], requires: { bins: [node] } } } ---# My Hook # 文档标题建议与 name 一致首字母大写详细文档... # 可选用于补充钩子功能、使用场景、参数说明等1.3 HOOK.md 关键字段说明metadata.openclaw 下的关键字段参考 hooks.md:81-91用于定义钩子的核心配置emojiCLI 界面显示的钩子图标可选如 、⚡events钩子监听的事件数组必填如 [command:new] 表示监听 new 命令触发export处理器的命名导出方式可选默认值为 defaultos钩子支持的操作系统平台可选如 [windows, macos, linux]requires钩子运行依赖检查可选支持 3 类依赖bins依赖的可执行程序如 [node, git]env依赖的环境变量如 [OPENCLAW_TOKEN]config依赖的 OpenClaw 配置项如 [plugin.enable]always是否跳过资格检查可选布尔值true 表示始终执行钩子1.4 Handler 处理器实现规范handler.ts 是钩子的核心逻辑文件需导出一个异步函数接收 event 参数事件对象示例如下// handler.ts const handler async (event) { // 早期过滤不相关事件立即返回推荐实践 if (event.type ! command || event.action ! new) { return; } // 钩子核心业务逻辑 console.log([my-hook] New command triggered); // 你的自定义逻辑如数据处理、接口调用等 // 可选向用户发送反馈消息会在 CLI/界面显示 event.messages.push(Hook executed!); }; // 导出处理器默认导出与 export 字段对应 export default handler;1.5 事件结构说明handler 接收的 event 参数事件对象结构参考 hooks.md:111-129包含以下固定字段type事件类型如 command 表示命令事件、lifecycle 表示生命周期事件action事件动作如 new 表示命令触发、exit 表示程序退出sessionKey当前会话唯一标识用于关联会话上下文timestamp事件触发时间戳毫秒级messages可向用户推送的消息数组push 新增消息会实时反馈给用户context事件特定数据不同事件类型的 context 结构不同如命令事件包含命令参数二、插件钩子编写规范插件钩子通过 API 注册方式实现需在插件的入口文件中通过 api 对象注册钩子分为两种场景注册内部事件钩子、注册生命周期钩子。2.1 注册内部事件钩子监听 OpenClaw 内部事件如命令触发通过 api.registerHook 注册示例如下// 插件入口文件如 index.ts export default function register(api) { // 注册钩子监听 command:new 事件 api.registerHook( command:new, // 监听的事件与内部钩子 events 字段格式一致 async () { // 钩子逻辑与内部钩子 handler 逻辑一致 // 你的自定义逻辑如拦截命令、补充参数等 console.log(New command triggered from plugin hook); }, { // 钩子元数据可选 name: my-plugin.command-new, // 插件钩子唯一名称建议前缀为插件ID description: 当 /new 命令被调用时运行, // 钩子描述 }, ); }2.2 注册生命周期钩子监听 OpenClaw 生命周期事件如提示词构建前、程序启动后通过 api.on 注册示例如下// 插件入口文件如 index.ts export default function register(api) { // 注册生命周期钩子提示词构建前触发 api.on( before_prompt_build, // 生命周期事件名称 (event, ctx) { // 钩子逻辑event 为事件对象ctx 为上下文 // 示例向系统上下文添加自定义规则 return { prependSystemContext: Follow company style guide., }; }, { priority: 10 }, // 可选钩子优先级数值越大执行越靠前 ); }三、实际示例测试钩子创建以下为通过代码动态创建测试用内部钩子的示例模拟目录创建、HOOK.md 和 handler.js 写入// 依赖 fs 和 path 模块Node.js 环境 import fs from fs; import path from path; // 动态创建测试钩子 async function createTestHook(hookDir, params) { // 写入 HOOK.md元数据文档 await fs.writeFile( path.join(hookDir, HOOK.md), [ ---, name: ${params.hookName}, // 动态传入钩子名称 description: ${params.hookName} test hook, // 动态描述 metadata: {openclaw:{events:[command:new]}}, // 监听 new 命令 ---, , # ${params.hookName}, // 文档标题 ].join(\n), utf-8, ); // 写入 handler.js简单处理器逻辑 await fs.writeFile( path.join(hookDir, handler.js), export default async function(event) { // 向用户推送消息 event.messages.push(${params.hookName} hook executed!); }\n, utf-8, ); }四、钩子编写最佳实践遵循以下实践可提升钩子稳定性、性能及可维护性参考 hooks.md:266-270保持处理器快速钩子在命令处理期间同步运行避免耗时操作重任务需使用void processInBackground(event)异步处理不阻塞主流程。优雅处理错误对文件操作、接口调用等风险操作使用 try-catch 包裹不要直接抛出异常避免影响主程序运行。早期过滤事件在 handler 开头判断事件类型/动作不相关的事件立即 return减少无效逻辑执行。使用特定事件键events 数组优先使用具体事件如 [command:new]而非模糊事件如 [command]提升钩子触发精度减少冗余执行。四、补充说明与注意事项为确保钩子机制的正常运行和灵活使用结合官方文档补充以下关键注意事项钩子覆盖规则工作区钩子可以添加新的钩子名称但无法覆盖名称相同的内置钩子、托管钩子或插件钩子参考 hooks.md:140-141避免低优先级钩子篡改核心功能插件钩子注册插件可通过 api.registerHook() 方法注册内部钩子或通过 api.on() 方法注册类型化运行时生命周期钩子参考 plugin.md:998-1036实现插件与钩子系统的深度集成插件钩子管理插件管理的钩子在执行 openclaw hooks list 命令时会显示为 plugin:id 格式无法通过 openclaw hooks enable/disable 命令直接启用/禁用需通过启用/禁用插件本身实现参考 plugin.md:1015-1019。总结OpenClaw 的钩子机制通过内部钩子与插件钩子的分类设计实现了“基础管控深度扩展”的双重能力。内部钩子聚焦 Gateway 核心事件保障系统基础运行的灵活性插件钩子聚焦 Agent 循环和 Gateway 管道提供精细化的业务扩展能力。同时明确的决策规则和发现机制确保了钩子执行的有序性、安全性和可维护性。用户可根据自身需求通过内置钩子快速实现基础功能或通过开发自定义钩子、部署插件钩子实现更贴合业务场景的扩展充分发挥 OpenClaw 的可定制化优势。相关参考文档Tool Policies Filtering (openclaw/openclaw)Plugin Architecture (openclaw/openclaw)插件架构详细说明Skills System (openclaw/openclaw)技能系统与钩子的联动说明