从我用 OpenClaw 做实际项目的经验来看Hooks 机制是最值得先吃透的一块。你刚接触这个开源 Agent 框架时可能最关心的是怎么把它跑起来、怎么接入微信、怎么接本地模型但一旦进入真实业务场景——比如消息要过滤、指令要自定义、调用模型前后要埋点——你就会发现所有灵活性的答案都指向同一个地方Hooks。这篇文章不聊泛泛的概念直接拆解 OpenClaw Hooks 的设计思路、核心细节、完整实操和踩坑实录适合正在用或准备用 OpenClaw 的开发者尤其是想做插件扩展、二次开发的朋友。读完你能自己写一个可用的 Hook 插件也能理解这套机制为什么值得这么设计。1. OpenClaw Hooks 的整体设计思路为什么一个 Agent 框架要把扩展做成“钩子”1.1 先从“Hook 是什么”开始Hook钩子这个词在软件工程里不算新东西。它本质上是一种事件回调机制框架在主流程的某些节点上预留了“插槽”你把自己的逻辑塞进插槽里当执行流经过这个节点时你的逻辑就会被调用。你可以把 Agent 的完整运行流程想象成一条流水线消息从一端进来经过理解、规划、调用工具、生成回复从另一端出去。Hooks 就是流水线上预设的那些“工位”你不改动流水线本身的构造但可以在某个工位上加入自己的工序。在 OpenClaw 这样的 Agent 框架里Hooks 的典型使用场景包括消息进入对话上下文之前做格式转换或者敏感词过滤在请求 LLM 之前注入额外的系统提示词在 LLM 返回之后解析和校验结果在工具调用之前做权限检查在 Agent 启动或关闭时加载和保存状态。这些场景有一个共同点它们都是“横切关注点”和 Agent 的核心对话逻辑关系不大但每个业务都绕不开。如果把这些逻辑全部写进 Agent 核心代码里项目会迅速变成一锅粥。1.2 为什么选择 Hooks 而不是继承或者配置开关很多框架解决扩展问题时会想到“继承基类重写方法”或者“开一堆配置开关”OpenClaw 选择 Hooks 机制是有明确理由的。继承的方式要求你理解 Agent 内部类的关系然后创建子类、覆写方法这套模式接口耦合很重。你为了改一个消息处理逻辑可能需要继承好几个类而且子类和父类的生命周期很难管理。配置开关则更僵化你没法通过一个开关实现任意逻辑你只能选“开”或者“关”别人预设好的功能。Hooks 的优势在于它是事件驱动的、松耦合的。核心流程只发布事件不关心谁在监听。插件开发者只需要知道“在什么事件上挂什么函数”不需要理解 Agent 内部完整的类结构。运行期还可以动态加载、卸载、调整优先级这对插件生态非常友好。注意Hooks 不是 OpenClaw 独有的设计。很多 Agent 框架都有类似机制只是叫法不同有的叫 Middleware中间件有的叫 Plugin Hook。但核心思想一致在固定节点上执行可插拔逻辑。1.3 Hooks 在 OpenClaw 整个架构里的位置OpenClaw 的架构大致可以拆成四层接入层各种 IM 平台、命令行、Agent 核心层对话管理、状态维护、工具编排、模型层LLM 调用、本地模型适配、扩展层插件、Hooks、记忆。Hooks 就像扩展层的骨架它横跨在接入层、Agent 核心层和模型层之间。举个例子一条消息从微信进来后路径是这样的接入层收到微信消息转成 OpenClaw 内部统一的消息结构。消息进入 Agent 核心触发message.received钩子你可以在这里做拦截或改写。Agent 判断需要调用工具触发tool.before_call钩子你可以在这里做权限校验。Agent 请求 LLM触发llm.before_request钩子你可以在这里追加提示词。LLM 返回内容触发llm.after_response钩子你可以在这里解析结构化输出。消息回复给用户前触发message.sending钩子你可以在这里做最后的格式化。这个链路说明一个问题Hooks 不是一个单一入口而是一组分散在关键路径上的事件点。你理解了这条链路就掌握了 OpenClaw 扩展的“地图”后面写插件就是往地图上填点位。2. Hooks 机制的核心细节与实现原理事件、注册、上下文、执行顺序2.1 事件类型与触发点分类OpenClaw 的 Hook 事件类型按我的实际使用经验可以分成四类生命周期类agent.start、agent.stop、session.reset。这类事件适合做资源初始化和清理。比如在 Agent 启动时连接数据库、在会话重置时清掉临时记忆。消息类message.received、message.sending、message.edited。消息的收发路径上触发。适合做消息预处理、回复后处理、内容过滤。LLM 调用类llm.before_request、llm.after_response、llm.error。请求大模型前后触发。适合做提示词注入、响应校验、重试逻辑、成本统计。工具调用类tool.before_call、tool.after_call、tool.error。Agent 调用外部工具时触发。适合做权限控制、参数改写、结果记录。事件类型是 Hooks 机制的地基。你写插件前第一件事不是写代码而是搞清楚你要挂在哪类事件上。挂错事件逻辑对了也不会有预期效果。2.2 钩子的注册与加载方式OpenClaw 的钩子注册方式和多数 Python 框架类似可以在实现插件时通过注册函数/装饰器来挂载。例如from openclaw import hooks hooks.on(message.received) async def my_handler(ctx): # 处理逻辑 pass但如果只靠装饰器插件无法被动态管理。所以 OpenClaw 的插件体系里通常还有一个“注册表”概念。插件被加载时会向全局注册表写入自身信息包括插件名、版本、支持的 Hook 事件列表卸载时再移除。注册机制是插件化的关键它决定了框架能不能在运行期感知到你的插件。加载方式上OpenClaw 支持两类一种是在配置文件里静态声明要加载哪些插件目录另一种是运行期通过 API 动态加载。静态声明适合部署场景配置清晰、可复现动态加载适合你在调试阶段快速测试。我刚上手时直接用动态注册调试快但项目一正式部署就发现还是配置文件更稳建议两种方式都掌握。2.3 钩子上下文与数据传递每个 Hook 函数会接收到一个context对象通常简写为ctx这是钩子和 Agent 核心之间共享数据的桥梁。ctx里一般包含当前事件类型、命中的消息内容、对话历史片段、当前 Agent 状态、原始事件的元数据比如消息来自哪个平台、哪个用户、以及插件自定义的临时存储区域。这里有一个重要设计上下文是贯穿整个请求链路的。你在message.received钩子里写入某个标记到llm.before_request钩子里是可以读到的。这种设计让多个钩子之间可以通过上下文协作而不是依赖全局变量。但要注意上下文对象本身的修改规则需要看清楚。有的字段是只读的比如事件元数据有的字段是可写的比如消息内容、附加参数。如果你试图修改只读字段框架会忽略或者抛异常。我的习惯是需要跨钩子传递自定义数据时统一放ctx.extra或插件专属的 key 下面不污染框架原生的字段。2.4 钩子的执行顺序与优先级同一事件上可能挂了多个钩子它们的执行顺序由优先级决定。OpenClaw 的钩子 API 一般支持在注册时传入优先级参数例如hooks.on(message.received, priority10) async def first_handler(ctx): pass hooks.on(message.received, priority20) async def second_handler(ctx): pass数值越小越先执行还是越大越先执行不同框架定义不同OpenClaw 官方文档里会明确我这里强调的重点是不要依赖默认顺序显式指定优先级。因为插件多了之后隐式顺序很容易出问题。举个例子我接入了两个插件都监听message.received。一个负责敏感词过滤一个负责日志记录。如果过滤钩子不先执行日志里就会打出未过滤的原文这时候数据链路就出现了问题。显式设置优先级可以保证过滤逻辑在前、记录逻辑在后。另一个和顺序相关的细节是钩子可以中断事件传播。某些事件类型支持钩子返回特殊标记来阻止后续钩子继续执行。这在“拦截型”场景里非常有用。比如消息来了你的钩子判断这条消息是 spam直接标记为已处理并返回后面的钩子就不用白费功夫了。3. 实操从零写一个 OpenClaw Hook 插件做消息过滤和 LLM 请求日志3.1 场景定义我们需要什么为了把 Hooks 机制讲透我设计一个相对完整的插件场景这个场景我在真实项目里也基本是这么干的某个内部群里的机器人需要过滤包含敏感词的消息不让它进入 LLM。群里的/status指令希望机器人直接回复系统状态不调用大模型省 token。每次请求 LLM 之前记录消息来源群、用户、消息长度、模型名方便月底核算成本。这三个需求分别对应三个不同的事件message.received过滤 拦截指令、llm.before_request记录日志、message.sending对/status做直接回复。注意第三点message.sending是为了让机器人能主动回复而不是走 LLM 生成。3.2 插件目录结构与基本配置按照 OpenClaw 插件规范一个合法插件通常包含固定目录结构和配置文件。我的目录如下my_biz_plugin/ ├── plugin.yaml ├── hooks/ │ ├── __init__.py │ ├── message_filter.py │ └── llm_logger.py └── config.yamlplugin.yaml用于声明插件元信息name: my_biz_plugin version: 1.0.0 description: 业务插件消息过滤与LLM请求日志 entry: hooks.message_filter events: - message.received - llm.before_request - message.sendingconfig.yaml里放可动态调整的配置比如敏感词列表和开关filter: enabled: true keywords: - 广告 - 加群 reply: 消息中含敏感词已拦截。 log_llm: enabled: true通过配置文件而不是硬编码来管理业务参数是插件开发的基本素养。改敏感词不用动代码改完热加载配置即可。3.3 钩子函数的实现与注册消息过滤与指令拦截# hooks/message_filter.py import yaml from openclaw import hooks, plugin_config CONFIG plugin_config.load(config.yaml) hooks.on(message.received, priority10) async def filter_keywords(ctx): if not CONFIG[filter][enabled]: return content ctx.message.content for kw in CONFIG[filter][keywords]: if kw in content: # 直接拦截不回 LLM原路回复提示 await ctx.reply(CONFIG[filter][reply]) # 标记消息已处理阻断后续钩子 return ctx.break_processing()这段代码的逻辑很清晰优先级设为 10保证它比其他钩子先跑。命中敏感词就回复一句提示然后调用ctx.break_processing()中断事件传播。如果你不中断过滤后的消息还是会继续传给 LLM等于白过滤。让/status不调用大模型hooks.on(message.received, priority5) async def status_command(ctx): content ctx.message.content.strip() if content /status: status_text 当前运行正常内存占用正常插件 my_biz_plugin 已加载。 await ctx.reply(status_text) return ctx.break_processing()我把status_command放在优先级 5比filter_keywords更高。这样指令拦截优先于敏感词过滤避免万一敏感词列表里有个“状态”之类的词把指令给误伤了。这个顺序很容易被忽略但实际跑过之后你就会明白插件之间甚至同一插件的不同钩子之间优先级设计都要有逻辑梯度。LLM 请求日志# hooks/llm_logger.py import logging from openclaw import hooks, plugin_config logger logging.getLogger(my_biz_plugin) CONFIG plugin_config.load(config.yaml) hooks.on(llm.before_request, priority20) async def log_llm_request(ctx): if not CONFIG[log_llm][enabled]: return logger.info( LLM request | group%s | user%s | msg_len%d | model%s, ctx.message.group_id, ctx.message.user_id, len(ctx.message.content), ctx.llm_request.model )LLM 日志钩子的用途不光是排查问题更是成本核算的数据来源。Agent 每调一次模型都是钱记录下每个群、每个用户触发了多少请求月底一看就知道哪些场景该优化。3.4 加载插件与验证在 OpenClaw 的配置里启用插件# openclaw_config.yaml plugins: - path: ./my_biz_plugin启动 OpenClaw 后日志里会出现类似plugin my_biz_plugin loaded的记录。验证步骤我建议按三条走功能验证在群里发一条含敏感词的测试消息确认机器人回复“消息中含敏感词已拦截”并且后端日志里没有对应的 LLM 请求。拦截验证发/status确认机器人直接返回状态文本不进入 LLM 调用流程。日志验证发一条正常消息确认llm_logger在日志中输出了包含群 ID、用户 ID、消息长度的记录。这三步都通过这个插件就算合格了。别急着加复杂度跑通一条最小链路比什么都重要。4. 常见问题与排查技巧实录Hooks 为什么没生效、顺序乱了、性能崩了4.1 钩子不触发的排查思路钩子不触发是新手最常见的问题。按我踩过的坑排查顺序应该是看插件是否真的加载了。OpenClaw 启动日志里会列出所有已加载插件如果没有你的插件去看配置路径对不对、entry是否写对、目录下有没有__init__.py。看事件名是否拼写正确。Hook 事件名是字符串匹配大小写和连字符都必须精确。message.received写成message_received或Message.Received都匹配不上而且框架不会报错因为这个错是静默的。看优先级是否被其他钩子拦截了。如果你的事件里还有另一个更高优先级的钩子它可能调用了break_processing()导致低优先级的钩子永远轮不到。调试时可以临时提高你的钩子优先级或者干脆暂时禁用其他插件看它能不能触发。看是否抛了异常但被吞了。OpenClaw 某些钩子机制会捕获并记录异常而不是向上抛出。如果你hooks.on装饰器用的函数抛了TypeError日志里会有 trace但 Agent 主流程不会中断。检查一下日志等级别只看控制台输出。4.2 钩子执行顺序混乱怎么办顺序混乱的根源大多是“默认优先级”和“实际需求”不一致。两个插件都挂在message.received上A 插件注册时没写优先级B 插件写了priority0最后执行顺序可能和你的预期完全相反。解决方式只有一个所有生产环境的钩子注册都显式写 priority。没有例外。你可能会说“就几个钩子不会乱”但插件一多或者过了两个星期你自己回来加代码就一定会乱。另外要注意优先级数值的语义。OpenClaw 的钩子调度逻辑一般是priority 越小越先执行类似 Linux nice 值或者 Spring 的 order但你务必看一遍官方源码或者文档确认不要在不明规则的情况下凭感觉写。4.3 异步钩子阻塞和超时问题OpenClaw 是异步框架钩子函数如果写成异步的async def框架会await它如果你的钩子内部又调用了同步阻塞的代码比如requests.get、time.sleep整个事件循环可能被卡住结果就是 Agent 回复超时、其他钩子也排队。我踩过的真实案例在llm.after_response钩子里调用了某个外部接口做内容审核用的是同步requests结果每次审核要 3 秒期间 Agent 完全没法处理其他消息。解决方式是把它改成异步调用或者丢到线程池里跑import asyncio from openclaw import hooks hooks.on(llm.after_response, priority30) async def content_audit(ctx): # 不直接调用同步接口用 asyncio.to_thread 避免阻塞事件循环 result await asyncio.to_thread(call_audit_api, ctx.llm_response.content) if not result.ok: await ctx.reply(抱歉这条回复没有通过审核。) return ctx.break_processing()另一个超时场景是钩子函数内部写了死循环、或者等待一个永远等不到的事件。给钩子函数加超时保护是成熟框架经常做的事但 OpenClaw 里可能没有默认的超时所以你自己写的钩子要有“会死”的预期。写钩子时尽量保持逻辑短小重活能扔给后台任务就扔后台。4.4 异常处理与日志定位钩子里抛异常要不要影响主流程我的原则是业务类钩子比如日志、埋点不应该影响主流程安全类钩子比如权限校验必须严格失败关闭。OpenClaw 的钩子在设计上一般会建议你自己捕获异常。同一个事件上的多个钩子如果 A 抛异常框架可能会中断后面的钩子。所以在写插件时兜底写法是这样的hooks.on(tool.before_call, priority10) async def check_permission(ctx): try: # 权限校验逻辑 allowed is_user_allowed(ctx.message.user_id) if not allowed: await ctx.reply(你没有权限调用此工具。) return ctx.break_processing() except Exception: # 权限校验失败默认拒绝 logger.exception(permission check failed, deny by default) await ctx.reply(权限校验异常禁止调用。) return ctx.break_processing()日志方面我强烈建议给插件创建一个独立的 logger而不是直接用print或 root logger。这样执行grep my_biz_plugin openclaw.log就能精准过滤出你插件的所有运行记录排查效率高非常多。5. Hooks 机制背后的架构哲学从“能用”到“好扩展”5.1 开闭原则在 Agent 框架里的落地开闭原则说“对扩展开放对修改关闭”。OpenClaw 核心引擎的代码是相对稳定的你不需要改它的agent.py才能加功能你只需要加新的 Hook 监听器。这带来一个实际好处框架升级时你的插件代码基本不用动。我经历过几次 OpenClaw 小版本升级核心 API 变了但我的插件只是改了一下配置项和事件名映射逻辑全部保留。如果当初是魔改源码方式做的二次开发升级就是一场噩梦。5.2 事件驱动带来的松耦合Hooks 的事件驱动本质让插件的互相依赖降到了最低。A 插件处理message.receivedB 插件也处理message.received它们彼此不知道对方存在。如果你想移除其中一个直接停用插件即可不影响另一个。这在团队协作时非常有用不同的开发者可以独立开发自己的 Hook 插件不用约定共同的接口只要事件契约一致就行。但是松耦合不等于无耦合。当多个插件确实需要协作时我建议通过上下文自定义字段来传递数据而不是直接 import 对方的模块。比如 A 插件在ctx.extra[is_spam] TrueB 插件读取这个标记决定是否放行。这样 A 和 B 之间的关系是“通过数据接口协作”而不是“通过代码调用协作”以后替换起来更容易。5.3 可观测性和治理能力Hooks 机制天然提供了可观测性。每个事件节点都是埋点位置而且因为事件是结构化的包含事件名、上下文对象你可以很容易地把它们接入日志系统或监控平台。我在生产环境做的是写一个全局的metrics插件监听所有核心事件把事件发生次数、处理耗时通过钩子开始结束时间差聚合并上报到 Prometheus。这个插件不改任何业务逻辑但它给整个系统提供了“体检报告”——哪个工具调用慢了、哪条消息路径耗时长了、哪个群触发的 LLM 请求最多一清二楚。如果没有 Hooks 机制你想给整个 Agent 加监控就只能去改框架源码这是绝大多数人不愿意做的事。5.4 从 Hooks 到插件生态扩展性的边界Hooks 是插件系统的基础能力但插件系统的完整形态还包括插件清单管理、依赖管理、权限模型、配置热更新、插件市场等。OpenClaw 的 Hooks 机制相当于给插件生态打好了“地基”而往上能盖多高取决于社区怎么用。从架构演进角度我个人看好这个方向Hooks 把“扩展点”暴露出来插件作者只需要关注业务逻辑未来如果官方提供更丰富的 SDK比如内置记忆服务、向量检索、Agent 编排工具插件作者就能用更少代码实现更复杂的功能。这也是为什么我建议你尽早熟悉 Hooks 机制——学的不只是 API而是一种思考 Agent 可扩展性的方式。6. 几个额外的实战建议如果你打算在团队里推广 OpenClaw 的插件化开发最后给你几条实打实的建议插件版本控制。给你的插件打上语义化版本号plugin.yaml里的version别一直写1.0.0。Hooks 机制允许你调用新 API但也允许你写坏逻辑。版本号是回滚的依据。多环境隔离。本地调试、测试环境、生产环境最好加载不同的插件配置。敏感词过滤的规则在测试环境可以宽松生产环境必须严格。利用config.yaml和环境变量做切换不要同一套配置走天下。重视钩子函数的幂等性。同一个消息可能因为网络重试、框架重放而被处理两次。你的钩子函数要考虑如果同一个事件触发两次会不会产生重复回复、重复扣费、重复埋点在关键处理逻辑里加上去重标记比如基于消息 ID是必要的。读一遍官方源码里的事件列表。文档写的事件可能不全源码的events/或者hooks/目录才是权威。我见过很多开发者只依赖文档结果文档没写的事件他完全不知道错过了很多扩展点。花一小时把这些源码文件过一遍你会发现 OpenClaw 能“钩”的地方比你想象的更多。我在实际使用 OpenClaw 的过程中最大的体会就是Hooks 机制决定了这个框架能陪你走多远。项目刚开始可能只需要一个简单的对话机器人但随着业务深入你会需要越来越多的定制逻辑而这些逻辑如果都能以 Hook 插件的形式存在你的核心系统始终保持简单稳定每次新增功能都是在“搭积木”而不是“推倒重来”。建议你在正式做复杂插件之前先用一个最小案例把消息流和 LLM 调用链路的钩子全跑一遍弄清楚每个节点能做什么、不能做什么后面就顺畅了。
OpenClaw Hooks机制全解析：事件驱动、插件化与实战踩坑
从我用 OpenClaw 做实际项目的经验来看Hooks 机制是最值得先吃透的一块。你刚接触这个开源 Agent 框架时可能最关心的是怎么把它跑起来、怎么接入微信、怎么接本地模型但一旦进入真实业务场景——比如消息要过滤、指令要自定义、调用模型前后要埋点——你就会发现所有灵活性的答案都指向同一个地方Hooks。这篇文章不聊泛泛的概念直接拆解 OpenClaw Hooks 的设计思路、核心细节、完整实操和踩坑实录适合正在用或准备用 OpenClaw 的开发者尤其是想做插件扩展、二次开发的朋友。读完你能自己写一个可用的 Hook 插件也能理解这套机制为什么值得这么设计。1. OpenClaw Hooks 的整体设计思路为什么一个 Agent 框架要把扩展做成“钩子”1.1 先从“Hook 是什么”开始Hook钩子这个词在软件工程里不算新东西。它本质上是一种事件回调机制框架在主流程的某些节点上预留了“插槽”你把自己的逻辑塞进插槽里当执行流经过这个节点时你的逻辑就会被调用。你可以把 Agent 的完整运行流程想象成一条流水线消息从一端进来经过理解、规划、调用工具、生成回复从另一端出去。Hooks 就是流水线上预设的那些“工位”你不改动流水线本身的构造但可以在某个工位上加入自己的工序。在 OpenClaw 这样的 Agent 框架里Hooks 的典型使用场景包括消息进入对话上下文之前做格式转换或者敏感词过滤在请求 LLM 之前注入额外的系统提示词在 LLM 返回之后解析和校验结果在工具调用之前做权限检查在 Agent 启动或关闭时加载和保存状态。这些场景有一个共同点它们都是“横切关注点”和 Agent 的核心对话逻辑关系不大但每个业务都绕不开。如果把这些逻辑全部写进 Agent 核心代码里项目会迅速变成一锅粥。1.2 为什么选择 Hooks 而不是继承或者配置开关很多框架解决扩展问题时会想到“继承基类重写方法”或者“开一堆配置开关”OpenClaw 选择 Hooks 机制是有明确理由的。继承的方式要求你理解 Agent 内部类的关系然后创建子类、覆写方法这套模式接口耦合很重。你为了改一个消息处理逻辑可能需要继承好几个类而且子类和父类的生命周期很难管理。配置开关则更僵化你没法通过一个开关实现任意逻辑你只能选“开”或者“关”别人预设好的功能。Hooks 的优势在于它是事件驱动的、松耦合的。核心流程只发布事件不关心谁在监听。插件开发者只需要知道“在什么事件上挂什么函数”不需要理解 Agent 内部完整的类结构。运行期还可以动态加载、卸载、调整优先级这对插件生态非常友好。注意Hooks 不是 OpenClaw 独有的设计。很多 Agent 框架都有类似机制只是叫法不同有的叫 Middleware中间件有的叫 Plugin Hook。但核心思想一致在固定节点上执行可插拔逻辑。1.3 Hooks 在 OpenClaw 整个架构里的位置OpenClaw 的架构大致可以拆成四层接入层各种 IM 平台、命令行、Agent 核心层对话管理、状态维护、工具编排、模型层LLM 调用、本地模型适配、扩展层插件、Hooks、记忆。Hooks 就像扩展层的骨架它横跨在接入层、Agent 核心层和模型层之间。举个例子一条消息从微信进来后路径是这样的接入层收到微信消息转成 OpenClaw 内部统一的消息结构。消息进入 Agent 核心触发message.received钩子你可以在这里做拦截或改写。Agent 判断需要调用工具触发tool.before_call钩子你可以在这里做权限校验。Agent 请求 LLM触发llm.before_request钩子你可以在这里追加提示词。LLM 返回内容触发llm.after_response钩子你可以在这里解析结构化输出。消息回复给用户前触发message.sending钩子你可以在这里做最后的格式化。这个链路说明一个问题Hooks 不是一个单一入口而是一组分散在关键路径上的事件点。你理解了这条链路就掌握了 OpenClaw 扩展的“地图”后面写插件就是往地图上填点位。2. Hooks 机制的核心细节与实现原理事件、注册、上下文、执行顺序2.1 事件类型与触发点分类OpenClaw 的 Hook 事件类型按我的实际使用经验可以分成四类生命周期类agent.start、agent.stop、session.reset。这类事件适合做资源初始化和清理。比如在 Agent 启动时连接数据库、在会话重置时清掉临时记忆。消息类message.received、message.sending、message.edited。消息的收发路径上触发。适合做消息预处理、回复后处理、内容过滤。LLM 调用类llm.before_request、llm.after_response、llm.error。请求大模型前后触发。适合做提示词注入、响应校验、重试逻辑、成本统计。工具调用类tool.before_call、tool.after_call、tool.error。Agent 调用外部工具时触发。适合做权限控制、参数改写、结果记录。事件类型是 Hooks 机制的地基。你写插件前第一件事不是写代码而是搞清楚你要挂在哪类事件上。挂错事件逻辑对了也不会有预期效果。2.2 钩子的注册与加载方式OpenClaw 的钩子注册方式和多数 Python 框架类似可以在实现插件时通过注册函数/装饰器来挂载。例如from openclaw import hooks hooks.on(message.received) async def my_handler(ctx): # 处理逻辑 pass但如果只靠装饰器插件无法被动态管理。所以 OpenClaw 的插件体系里通常还有一个“注册表”概念。插件被加载时会向全局注册表写入自身信息包括插件名、版本、支持的 Hook 事件列表卸载时再移除。注册机制是插件化的关键它决定了框架能不能在运行期感知到你的插件。加载方式上OpenClaw 支持两类一种是在配置文件里静态声明要加载哪些插件目录另一种是运行期通过 API 动态加载。静态声明适合部署场景配置清晰、可复现动态加载适合你在调试阶段快速测试。我刚上手时直接用动态注册调试快但项目一正式部署就发现还是配置文件更稳建议两种方式都掌握。2.3 钩子上下文与数据传递每个 Hook 函数会接收到一个context对象通常简写为ctx这是钩子和 Agent 核心之间共享数据的桥梁。ctx里一般包含当前事件类型、命中的消息内容、对话历史片段、当前 Agent 状态、原始事件的元数据比如消息来自哪个平台、哪个用户、以及插件自定义的临时存储区域。这里有一个重要设计上下文是贯穿整个请求链路的。你在message.received钩子里写入某个标记到llm.before_request钩子里是可以读到的。这种设计让多个钩子之间可以通过上下文协作而不是依赖全局变量。但要注意上下文对象本身的修改规则需要看清楚。有的字段是只读的比如事件元数据有的字段是可写的比如消息内容、附加参数。如果你试图修改只读字段框架会忽略或者抛异常。我的习惯是需要跨钩子传递自定义数据时统一放ctx.extra或插件专属的 key 下面不污染框架原生的字段。2.4 钩子的执行顺序与优先级同一事件上可能挂了多个钩子它们的执行顺序由优先级决定。OpenClaw 的钩子 API 一般支持在注册时传入优先级参数例如hooks.on(message.received, priority10) async def first_handler(ctx): pass hooks.on(message.received, priority20) async def second_handler(ctx): pass数值越小越先执行还是越大越先执行不同框架定义不同OpenClaw 官方文档里会明确我这里强调的重点是不要依赖默认顺序显式指定优先级。因为插件多了之后隐式顺序很容易出问题。举个例子我接入了两个插件都监听message.received。一个负责敏感词过滤一个负责日志记录。如果过滤钩子不先执行日志里就会打出未过滤的原文这时候数据链路就出现了问题。显式设置优先级可以保证过滤逻辑在前、记录逻辑在后。另一个和顺序相关的细节是钩子可以中断事件传播。某些事件类型支持钩子返回特殊标记来阻止后续钩子继续执行。这在“拦截型”场景里非常有用。比如消息来了你的钩子判断这条消息是 spam直接标记为已处理并返回后面的钩子就不用白费功夫了。3. 实操从零写一个 OpenClaw Hook 插件做消息过滤和 LLM 请求日志3.1 场景定义我们需要什么为了把 Hooks 机制讲透我设计一个相对完整的插件场景这个场景我在真实项目里也基本是这么干的某个内部群里的机器人需要过滤包含敏感词的消息不让它进入 LLM。群里的/status指令希望机器人直接回复系统状态不调用大模型省 token。每次请求 LLM 之前记录消息来源群、用户、消息长度、模型名方便月底核算成本。这三个需求分别对应三个不同的事件message.received过滤 拦截指令、llm.before_request记录日志、message.sending对/status做直接回复。注意第三点message.sending是为了让机器人能主动回复而不是走 LLM 生成。3.2 插件目录结构与基本配置按照 OpenClaw 插件规范一个合法插件通常包含固定目录结构和配置文件。我的目录如下my_biz_plugin/ ├── plugin.yaml ├── hooks/ │ ├── __init__.py │ ├── message_filter.py │ └── llm_logger.py └── config.yamlplugin.yaml用于声明插件元信息name: my_biz_plugin version: 1.0.0 description: 业务插件消息过滤与LLM请求日志 entry: hooks.message_filter events: - message.received - llm.before_request - message.sendingconfig.yaml里放可动态调整的配置比如敏感词列表和开关filter: enabled: true keywords: - 广告 - 加群 reply: 消息中含敏感词已拦截。 log_llm: enabled: true通过配置文件而不是硬编码来管理业务参数是插件开发的基本素养。改敏感词不用动代码改完热加载配置即可。3.3 钩子函数的实现与注册消息过滤与指令拦截# hooks/message_filter.py import yaml from openclaw import hooks, plugin_config CONFIG plugin_config.load(config.yaml) hooks.on(message.received, priority10) async def filter_keywords(ctx): if not CONFIG[filter][enabled]: return content ctx.message.content for kw in CONFIG[filter][keywords]: if kw in content: # 直接拦截不回 LLM原路回复提示 await ctx.reply(CONFIG[filter][reply]) # 标记消息已处理阻断后续钩子 return ctx.break_processing()这段代码的逻辑很清晰优先级设为 10保证它比其他钩子先跑。命中敏感词就回复一句提示然后调用ctx.break_processing()中断事件传播。如果你不中断过滤后的消息还是会继续传给 LLM等于白过滤。让/status不调用大模型hooks.on(message.received, priority5) async def status_command(ctx): content ctx.message.content.strip() if content /status: status_text 当前运行正常内存占用正常插件 my_biz_plugin 已加载。 await ctx.reply(status_text) return ctx.break_processing()我把status_command放在优先级 5比filter_keywords更高。这样指令拦截优先于敏感词过滤避免万一敏感词列表里有个“状态”之类的词把指令给误伤了。这个顺序很容易被忽略但实际跑过之后你就会明白插件之间甚至同一插件的不同钩子之间优先级设计都要有逻辑梯度。LLM 请求日志# hooks/llm_logger.py import logging from openclaw import hooks, plugin_config logger logging.getLogger(my_biz_plugin) CONFIG plugin_config.load(config.yaml) hooks.on(llm.before_request, priority20) async def log_llm_request(ctx): if not CONFIG[log_llm][enabled]: return logger.info( LLM request | group%s | user%s | msg_len%d | model%s, ctx.message.group_id, ctx.message.user_id, len(ctx.message.content), ctx.llm_request.model )LLM 日志钩子的用途不光是排查问题更是成本核算的数据来源。Agent 每调一次模型都是钱记录下每个群、每个用户触发了多少请求月底一看就知道哪些场景该优化。3.4 加载插件与验证在 OpenClaw 的配置里启用插件# openclaw_config.yaml plugins: - path: ./my_biz_plugin启动 OpenClaw 后日志里会出现类似plugin my_biz_plugin loaded的记录。验证步骤我建议按三条走功能验证在群里发一条含敏感词的测试消息确认机器人回复“消息中含敏感词已拦截”并且后端日志里没有对应的 LLM 请求。拦截验证发/status确认机器人直接返回状态文本不进入 LLM 调用流程。日志验证发一条正常消息确认llm_logger在日志中输出了包含群 ID、用户 ID、消息长度的记录。这三步都通过这个插件就算合格了。别急着加复杂度跑通一条最小链路比什么都重要。4. 常见问题与排查技巧实录Hooks 为什么没生效、顺序乱了、性能崩了4.1 钩子不触发的排查思路钩子不触发是新手最常见的问题。按我踩过的坑排查顺序应该是看插件是否真的加载了。OpenClaw 启动日志里会列出所有已加载插件如果没有你的插件去看配置路径对不对、entry是否写对、目录下有没有__init__.py。看事件名是否拼写正确。Hook 事件名是字符串匹配大小写和连字符都必须精确。message.received写成message_received或Message.Received都匹配不上而且框架不会报错因为这个错是静默的。看优先级是否被其他钩子拦截了。如果你的事件里还有另一个更高优先级的钩子它可能调用了break_processing()导致低优先级的钩子永远轮不到。调试时可以临时提高你的钩子优先级或者干脆暂时禁用其他插件看它能不能触发。看是否抛了异常但被吞了。OpenClaw 某些钩子机制会捕获并记录异常而不是向上抛出。如果你hooks.on装饰器用的函数抛了TypeError日志里会有 trace但 Agent 主流程不会中断。检查一下日志等级别只看控制台输出。4.2 钩子执行顺序混乱怎么办顺序混乱的根源大多是“默认优先级”和“实际需求”不一致。两个插件都挂在message.received上A 插件注册时没写优先级B 插件写了priority0最后执行顺序可能和你的预期完全相反。解决方式只有一个所有生产环境的钩子注册都显式写 priority。没有例外。你可能会说“就几个钩子不会乱”但插件一多或者过了两个星期你自己回来加代码就一定会乱。另外要注意优先级数值的语义。OpenClaw 的钩子调度逻辑一般是priority 越小越先执行类似 Linux nice 值或者 Spring 的 order但你务必看一遍官方源码或者文档确认不要在不明规则的情况下凭感觉写。4.3 异步钩子阻塞和超时问题OpenClaw 是异步框架钩子函数如果写成异步的async def框架会await它如果你的钩子内部又调用了同步阻塞的代码比如requests.get、time.sleep整个事件循环可能被卡住结果就是 Agent 回复超时、其他钩子也排队。我踩过的真实案例在llm.after_response钩子里调用了某个外部接口做内容审核用的是同步requests结果每次审核要 3 秒期间 Agent 完全没法处理其他消息。解决方式是把它改成异步调用或者丢到线程池里跑import asyncio from openclaw import hooks hooks.on(llm.after_response, priority30) async def content_audit(ctx): # 不直接调用同步接口用 asyncio.to_thread 避免阻塞事件循环 result await asyncio.to_thread(call_audit_api, ctx.llm_response.content) if not result.ok: await ctx.reply(抱歉这条回复没有通过审核。) return ctx.break_processing()另一个超时场景是钩子函数内部写了死循环、或者等待一个永远等不到的事件。给钩子函数加超时保护是成熟框架经常做的事但 OpenClaw 里可能没有默认的超时所以你自己写的钩子要有“会死”的预期。写钩子时尽量保持逻辑短小重活能扔给后台任务就扔后台。4.4 异常处理与日志定位钩子里抛异常要不要影响主流程我的原则是业务类钩子比如日志、埋点不应该影响主流程安全类钩子比如权限校验必须严格失败关闭。OpenClaw 的钩子在设计上一般会建议你自己捕获异常。同一个事件上的多个钩子如果 A 抛异常框架可能会中断后面的钩子。所以在写插件时兜底写法是这样的hooks.on(tool.before_call, priority10) async def check_permission(ctx): try: # 权限校验逻辑 allowed is_user_allowed(ctx.message.user_id) if not allowed: await ctx.reply(你没有权限调用此工具。) return ctx.break_processing() except Exception: # 权限校验失败默认拒绝 logger.exception(permission check failed, deny by default) await ctx.reply(权限校验异常禁止调用。) return ctx.break_processing()日志方面我强烈建议给插件创建一个独立的 logger而不是直接用print或 root logger。这样执行grep my_biz_plugin openclaw.log就能精准过滤出你插件的所有运行记录排查效率高非常多。5. Hooks 机制背后的架构哲学从“能用”到“好扩展”5.1 开闭原则在 Agent 框架里的落地开闭原则说“对扩展开放对修改关闭”。OpenClaw 核心引擎的代码是相对稳定的你不需要改它的agent.py才能加功能你只需要加新的 Hook 监听器。这带来一个实际好处框架升级时你的插件代码基本不用动。我经历过几次 OpenClaw 小版本升级核心 API 变了但我的插件只是改了一下配置项和事件名映射逻辑全部保留。如果当初是魔改源码方式做的二次开发升级就是一场噩梦。5.2 事件驱动带来的松耦合Hooks 的事件驱动本质让插件的互相依赖降到了最低。A 插件处理message.receivedB 插件也处理message.received它们彼此不知道对方存在。如果你想移除其中一个直接停用插件即可不影响另一个。这在团队协作时非常有用不同的开发者可以独立开发自己的 Hook 插件不用约定共同的接口只要事件契约一致就行。但是松耦合不等于无耦合。当多个插件确实需要协作时我建议通过上下文自定义字段来传递数据而不是直接 import 对方的模块。比如 A 插件在ctx.extra[is_spam] TrueB 插件读取这个标记决定是否放行。这样 A 和 B 之间的关系是“通过数据接口协作”而不是“通过代码调用协作”以后替换起来更容易。5.3 可观测性和治理能力Hooks 机制天然提供了可观测性。每个事件节点都是埋点位置而且因为事件是结构化的包含事件名、上下文对象你可以很容易地把它们接入日志系统或监控平台。我在生产环境做的是写一个全局的metrics插件监听所有核心事件把事件发生次数、处理耗时通过钩子开始结束时间差聚合并上报到 Prometheus。这个插件不改任何业务逻辑但它给整个系统提供了“体检报告”——哪个工具调用慢了、哪条消息路径耗时长了、哪个群触发的 LLM 请求最多一清二楚。如果没有 Hooks 机制你想给整个 Agent 加监控就只能去改框架源码这是绝大多数人不愿意做的事。5.4 从 Hooks 到插件生态扩展性的边界Hooks 是插件系统的基础能力但插件系统的完整形态还包括插件清单管理、依赖管理、权限模型、配置热更新、插件市场等。OpenClaw 的 Hooks 机制相当于给插件生态打好了“地基”而往上能盖多高取决于社区怎么用。从架构演进角度我个人看好这个方向Hooks 把“扩展点”暴露出来插件作者只需要关注业务逻辑未来如果官方提供更丰富的 SDK比如内置记忆服务、向量检索、Agent 编排工具插件作者就能用更少代码实现更复杂的功能。这也是为什么我建议你尽早熟悉 Hooks 机制——学的不只是 API而是一种思考 Agent 可扩展性的方式。6. 几个额外的实战建议如果你打算在团队里推广 OpenClaw 的插件化开发最后给你几条实打实的建议插件版本控制。给你的插件打上语义化版本号plugin.yaml里的version别一直写1.0.0。Hooks 机制允许你调用新 API但也允许你写坏逻辑。版本号是回滚的依据。多环境隔离。本地调试、测试环境、生产环境最好加载不同的插件配置。敏感词过滤的规则在测试环境可以宽松生产环境必须严格。利用config.yaml和环境变量做切换不要同一套配置走天下。重视钩子函数的幂等性。同一个消息可能因为网络重试、框架重放而被处理两次。你的钩子函数要考虑如果同一个事件触发两次会不会产生重复回复、重复扣费、重复埋点在关键处理逻辑里加上去重标记比如基于消息 ID是必要的。读一遍官方源码里的事件列表。文档写的事件可能不全源码的events/或者hooks/目录才是权威。我见过很多开发者只依赖文档结果文档没写的事件他完全不知道错过了很多扩展点。花一小时把这些源码文件过一遍你会发现 OpenClaw 能“钩”的地方比你想象的更多。我在实际使用 OpenClaw 的过程中最大的体会就是Hooks 机制决定了这个框架能陪你走多远。项目刚开始可能只需要一个简单的对话机器人但随着业务深入你会需要越来越多的定制逻辑而这些逻辑如果都能以 Hook 插件的形式存在你的核心系统始终保持简单稳定每次新增功能都是在“搭积木”而不是“推倒重来”。建议你在正式做复杂插件之前先用一个最小案例把消息流和 LLM 调用链路的钩子全跑一遍弄清楚每个节点能做什么、不能做什么后面就顺畅了。