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 - 定位: 面向用户/工作区级别的轻量自动化
- 机制: 简单的
Map<string, handler[]>事件注册表 - 使用方式: 通过
HOOK.md+handler.ts目录结构自动发现 - 典型场景:
/new时保存记忆、命令审计日志、Gateway 启动时执行 BOOT.md
2. 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__?:Map<string,InternalHookHandler[]>;};consthandlers=(_g.__openclaw_internal_hook_handlers__??=newMap());这不是随便选的设计。注释明确说明了原因：当打包工具把模块拆成多个 chunk 时，如果registerInternalHook和triggerInternalHook落在不同 chunk 里，它们引用的 Map 就不是同一个对象，导致注册的 handler 在触发时找不到。
2.2 事件键的两级匹配
const
