OpenClaw Hooks 模块深度解析 — 双层事件驱动架构

张开发
• 2026/5/12 1:38:47 • 15 分钟阅读

最新文章

推荐文章

相关文章

分享文章

OpenClaw Hooks 模块深度解析 — 双层事件驱动架构
OpenClaw Hooks 模块深度解析 — 双层事件驱动架构📅 发布日期：2026-03-18🔖 标签：OpenClaw · AI · 技术解析 · 事件驱动👨‍💻 作者：小讯✉️ 投稿：欢迎投稿至公众号🎯 前言：AI Agent 的扩展性挑战当 AI Agent 需要适应各种复杂场景时，如何在不修改核心代码的情况下扩展功能？如何让用户自定义行为，同时保证系统安全？OpenClaw 的 Hooks 系统给出了一个双层解决方案。🎯 一、核心发现：OpenClaw 拥有两套独立的 Hook 系统这是我在源码分析中最大的发现——OpenClaw 不是一套 Hook 系统，而是两套完全独立但互补的事件驱动架构，分别服务于不同层级的扩展需求：1. Internal Hooks（内部钩子）位置:src/hooks/internal-hooks.ts定位: 面向用户/工作区级别的轻量自动化机制: 简单的Mapstring, handler[]事件注册表使用方式: 通过HOOK.md+handler.ts目录结构自动发现典型场景:/new时保存记忆、命令审计日志、Gateway 启动时执行 BOOT.md2. Plugin Hooks（插件钩子）位置:src/plugins/hooks.ts定位: 面向插件开发者的深度生命周期拦截机制: 基于PluginRegistry的优先级排序 + 多种执行策略使用方式: 插件在注册时声明 hook 处理器典型场景: 修改模型选择、拦截消息发送、控制子 Agent 路由为什么这么设计？这是一个精妙的分层决策：Internal Hooks 降低了扩展门槛——用户只需写一个简单的 TS 函数，放到hooks/目录里就行。不需要理解插件系统，不需要注册流程。Plugin Hooks 提供了深度控制——插件可以修改 LLM 输入输出、拦截工具调用、重写消息内容，甚至阻止消息写入。这些能力不适合暴露给普通用户。这种"简单的给用户，复杂的给开发者"的分层思想值得借鉴。🎯 二、Internal Hooks 的设计精髓2.1 全局单例注册表——解决 bundle splitting 问题const_g=globalThisastypeofglobalThis{__openclaw_internal_hook_handlers__?:Mapstring,InternalHookHandler[];};consthandlers=(_g.__openclaw_internal_hook_handlers__??=newMap());这不是随便选的设计。注释明确说明了原因：当打包工具把模块拆成多个 chunk 时，如果registerInternalHook和triggerInternalHook落在不同 chunk 里，它们引用的 Map 就不是同一个对象，导致注册的 handler 在触发时找不到。2.2 事件键的两级匹配const

更多文章