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