OpenClaw 用了一段时间之后我遇到的第一道坎不是模型效果而是怎么让它在关键节点上听我的。默认配置能完成基础对话和工具调用但一旦想加一点自己的业务逻辑——比如把指定对话写入 Obsidian、在公司场景下强制注入统一的提示词、或者把简单的请求路由到本地小模型——就只能改主代码或者在外面起脚本轮询状态。改主代码升级时痛苦起轮询又拿不到内部上下文。后来我把希望放在 OpenClaw Hooks 上在事件流的关键节点插入自定义代码不动核心源码也能实现对会话、模型调用、工具调用和输出后处理的完整控制。这篇文章就是我对这几个月 Hooks 使用经验的完整记录。适合已经装好 OpenClaw、准备真正把它当作生产力工具来折腾的人。如果你刚好在 Windows 下用 WSL 2 部署里面也有对应的环境处理建议。1. OpenClaw Hooks 的设计初衷与定位1.1 没有 Hooks 之前自定义逻辑为什么痛苦很多框架都面临这个问题。OpenClaw 本身把会话、模型、工具三件套做得比较顺但每个人的业务场景都不同。举个例子我做了一个客服知识库助手要求所有发给模型的提示词里都带上一句话回答必须基于以下知识库内容知识库内没有的信息请明确说不知道。如果没有 Hooks我只能去改构建提示词那块的源码或者用一层反向代理去拦截请求。改源码的问题是OpenClaw 迭代速度不算慢我每升一次版本本地补丁就要重新打一遍几个冲突文件能让人耗掉一晚上。写死配置也是个办法但配置只能解决开关级别的问题。你很难在配置文件里表达当用户消息超过 200 字时切换模型、否则维持原模型这种条件逻辑。至于外部脚本轮询它跟框架内部状态是脱节的——你轮询不到提示词刚刚组装完毕这样的中间时刻自然也就做不了精确的干预。Hooks 给我的体验相当于在 OpenClaw 这条事件流水线上给我留了几个可以直接插手的工作台。我不需要知道流水线每一颗螺丝怎么拧只需要在对应的工位上处理我关心的那一段。这个抽象把想自定义行为和需要理解框架全部内部实现之间的成本降下来一大截。1.2 Hooks 在事件链路中的位置先把我自己理解的 OpenClaw 事件链路说清楚。不需要代码也能看明白它为什么能覆盖绝大多数自定义场景用户消息进入系统系统把消息放进会话上下文。系统根据会话历史、角色设定、工具列表构建提示词。提示词被发送给模型服务等待返回。模型输出到达系统做初步解析。解析出的工具调用会被执行结果回填。最终回复返回给用户。Hooks 可以挂在上面任意一步的前后。第 2 步结束之后你可以注入一段额外的系统指令第 3 步之前你可以改模型名称、温度参数第 4 步之后你可以把回复写进本地文件第 5 步之前你可以决定某个工具能不能被调用。挂在哪个位置决定了你能拿到什么上下文、能修改什么字段。实际使用中我发现选择正确的挂载点比写 Hook 逻辑本身更重要。同样是让模型看不到某些词挂在 onMessageReceived 改用户消息和挂在 onPromptBuilt 改提示词效果完全不同。前者会改变会话历史的原始记录后者只影响这一次请求的输入。理解这个差异能免去很多改了没生效的困惑。1.3 和 React Hooks 的相似与不同看到 OpenClaw Hooks 这个概念写过 React 的人第一反应肯定是这不就是 Hooks 吗对思想确实同源React Hooks 让你在组件渲染生命周期里注入逻辑OpenClaw Hooks 让你在智能体运行生命周期里注入逻辑都是把控制权交还给使用方。但千万别把 React 的经验直接搬过来它们有几点本质区别。第一React Hooks 的执行次数是相对确定的——组件每渲染一次相关 Hooks 就按顺序执行一次。OpenClaw Hooks 则不同它更像服务端中间件同一个事件钩子在一个会话里可能执行很多次也可能一次都不执行完全由运行时的事件决定。如果你带着每次调用必然触发的预期去写很容易漏掉边界场景。第二React Hooks 的规则里有一条不能写在条件语句里那是因为它依赖调用顺序做状态关联。OpenClaw Hooks 没有这个限制它更接近注册制你只负责注册事件处理器触发条件由框架判断。这也意味着 hook 内部可以用流程控制语句不用像 React 那样为了顺序牺牲可读性。第三上下文处理方式不同。React Hooks 共享状态靠顶层组件或者 ContextOpenClaw Hooks 共享状态靠一个统一的事件上下文对象ctx。你在前面的 hook 里往ctx.state里写了个值后面的 hook 就能读到。这个机制用好了可以在不改框架的前提下实现多步协作逻辑。2. Hooks 到底能钩住什么事件类型与上下文2.1 常用事件钩子一览OpenClaw 的 Hooks 机制里事件名是核心入口。以我当前使用的版本来讲我接触到的常用事件大概有下面这些。我按事件发生的先后顺序列出来方便对照记忆事件名触发时机典型用途onMessageReceived用户消息进入会话、被处理之前记录日志、敏感词过滤、消息改写onPromptBuilt提示词组装完成、发送模型之前注入系统指令、追加少量示例、动态上下文onModelRequest即将发起模型 API 调用修改模型名、温度和 max_tokens、做模型路由onModelResponse模型结果返回、进入后处理之前解析输出、格式校验、落盘持久化onToolCall工具调用被执行之前权限校验、参数改写、拦截高风险操作onToolResult工具执行返回之后结果校验、失败重试、日志汇总onSessionEnd一个会话生命周期收尾时生成会话摘要、统计数据、清理临时文件这张表记熟之后你在写 hook 时就不会再纠结我该用哪个事件。判断方式很简单你想干预的是哪一步就选哪个事件事件名跟触发时机的字面意思是严格对应的。有一点需要提醒不同小版本对某个事件的支持程度不完全一样。我曾在 0.8.x 版本里以为 onModelResponse 可以改回复正文但那只读换到 0.9.x 之后才能写。所以拿到新版本先跑一遍官方示例 hooks 是最快的验证方式别拿旧记忆硬套。2.2 Hook 配置文件的基本结构OpenClaw 里注册 Hooks 最常用的方式是提供一个 hooks 配置文件。我自己的项目里用的是hooks.js放在 OpenClaw 工作目录里然后在主配置里指定它的路径。结构大概是这样// hooks.js module.exports { hooks: [ { event: onMessageReceived, order: 10, handler: async (ctx) { console.log([hook] onMessageReceived, ctx.message.text.slice(0, 50)); return ctx; }, }, { event: onPromptBuilt, order: 20, handler: async (ctx) { // 在提示词末尾追加一句系统指令 ctx.prompt.system \n回答时必须先给出结论再解释原因。; return ctx; }, }, ], };从这段代码可以看到三个关键字段。event指定触发时机order决定同一事件下多个钩子的执行顺序数值小的先跑handler是真正干活的异步函数接收上下文对象并返回上下文对象。我用数组加 order 而不是纯数组顺序是因为在多人协作或者叠加多个插件提供的 hooks 时order 可以避免别人新增了一个钩子我这边全得改顺序的尴尬。给第一个钩子留 10 而不是 1也是这个目的——给自己留出在它前面插队的余量。2.3 上下文对象里到底有什么ctx是 Hooks 机制里最核心的数据结构。我习惯把它理解成一个运行时的快递箱每个阶段该有什么件OpenClaw 会装进去你取出需要的件处理完再放回去。我用过的字段大致有这些ctx.sessionId当前会话的唯一标识跨多个 hooks 定位会话就靠它。ctx.message当前用户消息对象通常包含role、text、attachments等。ctx.history会话历史数组按时间排序越往后越接近当前。ctx.prompt组装后的提示词对象包含system、user等分段。ctx.request即将发送给模型 API 的请求结构包含model、temperature、max_tokens等。ctx.response模型返回的结果结构包含content、reasoning等。ctx.toolCall当前工具调用的描述对象包含name、args。ctx.toolResult工具执行后的返回结果。ctx.tools当前会话可用的工具列表。ctx.state一个动态的键值存储专门给 hooks 之间传递数据。我把ctx.state称为Hooks 之间的便签纸。比如我在 onMessageReceived 里判定了这个消息属于高优先级客户把ctx.state.priority high写进去到 onPromptBuilt 里就能根据这个标记追加不同的提示词片段。数据用完后该清理就清理避免长时间运行的内存膨胀。3. 从零到一跑通第一个 Hooks 的全过程3.1 部署 OpenClawUbuntu 24.04 的准备步骤如果你跟我一样先在本地 Ubuntu 上折腾流程不会太长。我假设你手上有一台干净的 Ubuntu 24.04 服务器或者虚拟机Node.js 环境是前提。先装依赖。OpenClaw 是基于 Node.js 的建议安装 18 以上的 LTS 版本。我用的命令curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs git装完确认一下版本node -v能看到 v20 开头就没问题。然后从官方源拉取 OpenClaw 项目文件并在工作目录初始化git clone 你的 OpenClaw 仓库地址 openclaw cd openclaw npm install npx openclaw init my-appinit会生成一个最小的可运行配置目录包含主配置文件、模型配置示例、以及一个空的 hooks 目录。随后改主配置里的模型 provider 和 api key先跑npx openclaw start确认服务能起来再开始写 hooks。这里提一句 Windows 用户。我有一台 Windows 笔记本尝试直接跑 OpenClaw最省心的方案还是 WSL 2 里装 Ubuntu。如果你在 PowerShell 执行wsl --status看到 WSL 2 没有正确启用先按提示升级内核或执行wsl --update再重新进入 Ubuntu 环境。之前遇到OpenClaw 无法安全验证环境类似提示时多半是 WSL 发行版状态异常把发行版注销重新导入通常能解决。我没有在这里展开 Windows 原生支持因为我的实际经验就是 WSL 2 路线最稳。3.2 写一个最小可用的消息改写 Hook环境通了之后第一个 hook 建议做得足够小小到你能完全预期它的行为变化。我第一个成功跑通的 hook 是把用户消息里的今天替换成真实日期function replaceToday(str) { const today new Date().toISOString().slice(0, 10); return str.replace(/今天/g, today); } module.exports { hooks: [ { event: onMessageReceived, order: 10, handler: async (ctx) { ctx.message.text replaceToday(ctx.message.text); console.log([hook] 改写消息: ${ctx.message.text}); return ctx; }, }, ], };为什么先做这个因为它覆盖了一个 Hook 的全部关键动作拿到上下文、修改字段、返回上下文、通过日志验证结果。改动是确定性的任何可观测的变化都能立刻被你发现最适合用来确认链路通没通。修改完文件之后重启 OpenClaw然后在命令行里给会话发一条包含今天的消息看看服务端日志里有没有打印[hook] 改写消息。有打印并且模型回复里能看出日期变化说明你的第一个 Hook 已经完整生效。3.3 用调试模式观察 Hook 的执行细节只靠 console.log 也能排查大部分问题但遇到更细的场景我会用 OpenClaw 自带的调试模式。启动时加--debugnpx openclaw start --debug调试模式会打印出事件链路的明细包括每个 hook 的注册顺序、执行时长、以及上下文对象里关键字段的当前值。有一次我发现某个 hook 没有按预期触发最后就是在调试日志里看到的那个事件在当前场景下根本不会派发自然就不会触发。这种问题不看内部日志光猜是猜不出来的。3.4 修改 Hook 文件后的热重载问题写 hooks 的过程中改文件非常频繁每次改完都重启整个服务会很快消磨掉耐心。我用的版本支持文件修改监听检测到hooks.js变化会自动重载控制台会输出类似[runtime] hooks reloaded的提示。如果你的版本不支持两个替代方案供参考一是用 nodemon 监听运行二是把开发时的 hooks 独立成一个 npm script通过npm run dev启动带--watch的调试进程。有一点要特别注意热重载之后的进程里旧 hook 里创建的定时器或长连接可能还残留。如果你的 hook 里有setInterval重载前最好在逻辑里判断一下并清理否则你会看到同一个定时器被重复注册的诡异现象。4. 实战场景用 Hooks 接管会话、模型与工具调用4.1 在模型调用前注入会话级上下文我维护的客服知识库助手有一个强需求所有模型请求必须携带当前客服坐席的姓名和当前日期。没做 Hook 之前我需要把这些信息写死在提示词里每天手动改日期。后来我用 onPromptBuilt 事件统一注入{ event: onPromptBuilt, order: 20, handler: async (ctx) { const agent ctx.state.agentName || 默认坐席; const today new Date().toLocaleDateString(zh-CN, { timeZone: Asia/Shanghai, }); ctx.prompt.system (ctx.prompt.system || ) \n[环境信息] 当前坐席${agent}当前日期${today} \n回答规范先给出结论再给出依据不确定的内容明确说明。; return ctx; }, }注入之后模型每次生成回复都会考虑这些环境信息回答语气和格式明显稳定。这个场景充分说明了一个问题提示词工程并不只能在配置里做静态模板配合 Hooks 之后它变成了一种按会话动态计算的逻辑。4.2 在模型返回后做输出落盘与敏感信息过滤模型返回结果的保存是另一个典型场景。我想把每一个会话的最终输出追加到一个本地归档文件里方便后续分析。直接在代码里改处理函数是最快但最笨的方式用 Hook 则干净得多const fs require(fs); const path require(path); const ARCHIVE_DIR path.join(__dirname, archive); function appendToArchive(sessionId, content) { if (!fs.existsSync(ARCHIVE_DIR)) fs.mkdirSync(ARCHIVE_DIR, { recursive: true }); const file path.join(ARCHIVE_DIR, ${sessionId}.md); fs.appendFileSync(file, \n---\n${new Date().toISOString()}\n${content}, utf8); } module.exports { hooks: [ { event: onModelResponse, order: 10, handler: async (ctx) { const content ctx.response.content; const cleaned content.replace(/手机号[^\n。]*/g, [已脱敏]); ctx.response.content cleaned; appendToArchive(ctx.sessionId, cleaned); return ctx; }, }, ], };这个例子顺手演示了敏感信息过滤把疑似手机号的内容替换为脱敏标记。用到正则表达式如果你在生产环境也这么写记得做单元测试覆盖边界——光靠正则防不住所有格式。保存归档用的是同步 APIappendFileSync在低频场景没问题如果你的 hooks 跑在高并发下建议换成fs.promises.appendFile配合 await避免阻塞事件循环。4.3 接入 Qwen2.5-3B做一个按消息复杂度路由模型的 HookOpenClaw 本身支持配置 OpenAI 兼容接口所以我可以在同一套框架里同时接入云端大模型和本地小模型。我有一台带 6GB 显存的旧 GPU 机器用 Ollama 跑 Qwen2.5-3B效果虽然不如云端大模型但胜在免费、低延迟、数据不出本机。核心思路是通过 Hook 做模型路由短问题走本地小模型长问题或复杂推理走云端大模型。{ event: onModelRequest, order: 10, handler: async (ctx) { const text ctx.message.text; const length text.length; const hasComplex /(计算|分析|总结|对比|推荐)/.test(text); if (length 100 !hasComplex) { ctx.request.model qwen2.5:3b; ctx.request.provider ollama; } else { ctx.request.model ctx.request.model || default-cloud-model; } console.log([hook] 消息长度${length} 复杂度${hasComplex} 路由到${ctx.request.model}); return ctx; }, }实际跑下来大概有七成简单问答直接落在本地模型上模型 API 的费用降了一大截响应时间也快了不少。Qwen2.5-3B 在短句问答、上下文理解这类任务上的表现足够好但是一旦涉及多轮复杂推理它还是明显不如云端大模型这时候路由到云端是对的。我额外踩过一个小坑不能只改模型名不换 provider。如果你的 OpenClaw 配置里默认 provider 是云端修改 model 字段并不会自动把请求发往本地 Ollama 地址必须像上面的代码一样把 provider 也一并切换。这类字段在不同版本里名称可能略有差异最好的确认方式是查看本地配置模板里 provider 出现的位置。4.4 给工具调用加一道闸门工具调用是高危扩展点。我跑过一个自动化项目AI 会调用执行系统命令的工具。默认配置下只要模型认为需要它就能发起任意命令这显然不安全。我用 onToolCall 事件做了一层白名单{ event: onToolCall, order: 10, handler: async (ctx) { const toolName ctx.toolCall.name; const allowed new Set([list_files, read_file]); if (!allowed.has(toolName)) { console.warn([hook] 拦截工具调用: ${toolName}); ctx.toolCall.blocked true; return ctx; } ctx.toolCall.blocked false; return ctx; }, }关键在于ctx.toolCall.blocked这个约定。设置成 true 后框架会在执行工具前中止调用并给模型返回一个固定提示。具体字段名要以你装的版本为准我是看了调试日志才确认它叫 blocked。安全类 Hook 建议写在 order 最小、最靠近触发源头的位置避免其他 hook 先做了某些旁路处理。5. 避坑指南作用域、异步与错误处理5.1 闭包陷阱多个会话共享同一个全局变量Hook 的 handler 虽然是有状态的但模块顶层的全局变量在 OpenClaw 常驻进程里是跨会话共享的。我犯过一个低级错误为了统计当前会话工具调用次数在模块顶层写了个let toolCallCount 0结果 A 会话调用工具之后B 会话看到的计数器已经是 A 的值。解决方案不复杂把会话级数据放到ctx.state里按 sessionId 隔离。如果你想共享一个只读的信息表比如配置字典模块顶层变量还是可以用的但任何可变的、跟会话相关的数据都别放顶层。排查这类问题的经验是如果两个会话互相影响先怀疑模块顶层可变状态再看是不是 handler 内部引用了外部闭包变量。日志里把 sessionId 打出来是定位问题最快的抓手。5.2 异步 Hook 的错误传播与兜底异步函数里抛异常处理不当会让整个事件链路崩溃。我在早期版本踩过一个坑某个 hook 里调用了一个外部 API对方超时返回 500异常直接抛了出来导致一条用户消息整个处理流程失败用户得不到任何回复。现在的规范做法是hook 内部自己兜住异常尽量不让它冒泡到框架层。我一般这样写{ event: onModelResponse, order: 10, handler: async (ctx) { try { const result await externalCheck(ctx.response.content); ctx.state.checked result; } catch (err) { console.error([hook] 外部检查失败跳过, err.message); ctx.state.checked false; } return ctx; }, }把失败降级成标记为未检查而不是中断主流程这是中间件开发的通用哲学可选逻辑不该绑架核心链路。如果你确实需要失败即中断再考虑直接抛出异常并配置框架的全局错误处理。5.3 给外部调用加上超时与降级值上面提到了超时这里给一个我常用的工具函数。在 hook 里访问外部 HTTP 服务时如果不用它一个迟迟不返回的请求会让整个对话卡几十秒。用 Promise.race 强制超时可以让问题可控function withTimeout(promise, ms, fallback) { return Promise.race([ promise, new Promise((resolve) setTimeout(() resolve(fallback), ms)), ]); } // 使用示例 const weather await withTimeout( fetchWeather(ctx.message.city), 2000, 天气服务暂时不可用 );超时值建议根据 OpenClaw 链路整体的可接受延迟来定。我一般控制在 1.5 到 3 秒之间既要给外部服务留出响应窗口也不能让用户觉得对话卡顿。fallback的选择同样重要选一个让后续逻辑可继续的降级值比抛异常更稳妥。5.4 改错字段事件选对了但数据没传对接触 Hooks 两个月时我自以为很熟练了却犯了个经典错误想在 onModelRequest 阶段往提示词里加内容于是去改ctx.prompt.system结果模型压根没收到。原因很简单onModelRequest 事件的上下文里prompt 并不是标准接口的一部分那个节点的关键字段是request。真正应该改的是ctx.request.messages里的 system 元素或者干脆回到更早的 onPromptBuilt 事件去改。这一点也说明了为什么我前面强调每个事件的上下文内容不同。写 hook 之前先搞清楚你手上的事件上下文里到底有哪些字段再决定改哪里。调试模式下多打印几次Object.keys(ctx)比反复翻文档更有效率。6. 生态联动把 Hooks 用进 Obsidian、服务器与生产环境6.1 把会话摘要写进 Obsidian 笔记库我习惯把和 AI 的重要对话沉淀到 Obsidian 里做知识管理。之前是手动复制粘贴后来我用 onSessionEnd 事件来自动落盘。思路会话结束时把对话摘要追加到 Obsidian vault 的某个日记文件里。const fs require(fs); const path require(path); const VAULT_PATH /home/me/Documents/obsidian-vault/ai-journal; module.exports { hooks: [ { event: onSessionEnd, order: 30, handler: async (ctx) { const dateStr new Date().toISOString().slice(0, 10); const filePath path.join(VAULT_PATH, ${dateStr}.md); const { sessionId } ctx; const summary ctx.state.finalSummary || 未生成摘要; const line \n- ${new Date().toLocaleTimeString()} 会话 ${sessionId}${summary}; fs.appendFileSync(filePath, line, utf8); return ctx; }, }, ], };跑起来要注意两件事。一是路径权限OpenClaw 运行用户必须对该 vault 目录有写权限否则会静默失败或者直接报错建议先用fs.existsSync检查。二是 Obsidian 的同步插件文件监听如果 vault 目录变化没有同步出去多半是同步插件把写入判断为外部修改需要调整自动同步的触发策略。6.2 云端部署时Hook 的日志到底去了哪里我在阿里云轻量服务器上部署时用 systemd 管理 OpenClaw 服务。这时候有个陷阱hook 里的console.log并不会出现在你敲命令的终端它默认进入 systemd 的 journald需要通过journalctl -u openclaw -f查看。如果你希望日志直接落到固定文件可以在 systemd 服务单元里配置 StandardOutput 和 StandardError。另一个容易被忽略的是时区Node.js 默认输出 UTC 时间而我们在国内观察日志通常习惯Asia/Shanghai。设置方式很简单启动服务前在环境变量里加上TZAsia/Shanghai或者在每个 hook 的日志函数里统一转换。6.3 轻量服务器上的资源优化别让 Hooks 变成内存杀手如果你和我一样把 OpenClaw 和 Ollama 都放在 2 核 2G 的轻量服务器上内存就要精打细算。Hooks 本身逻辑通常很轻但有两个倾向会拖垮内存一是为了处理文本方便引入大型 npm 依赖包。一个完整的 markdown 解析库、一个 Excel 读写库装进来可能让进程常驻内存涨几百兆。在受限服务器上优先用原生实现或者选择专门针对轻量场景的库。二是模型量化。Qwen2.5-3B 建议用 q4_k_m 或更小的量化版本完整版跑在 2G 内存的服务器上加上 OpenClaw 和 Node.js内存很快就见底。我在部署时给 Ollama 设置了OLLAMA_MAX_LOADED_MODELS1只保留一个模型常驻配合 pm2 的max_memory_restart: 1500M兜底跑了一个多月没因为内存崩溃。6.4 给 Hooks 加一点可观测性最后分享一个我最近养成的习惯在 hook 入口统一加一条带时间戳的日志格式类似[hook:onModelRequest] ts1718000000000 session... cost12ms。日志里带 sessionId 和耗时线上出问题的时候可以直接按会话 ID 拉出全链路记录。这套可观测性做起来不难但价值极高。OpenClaw 的 Hooks 运行在事件链路上哪个环节慢了、哪个环节被拦截了数据都在日志里。尽早把日志规范起来等到真正要排障时才不会手足无措。我个人在实际操作中最深的体会是Hooks 这块功能最值钱的不是语法而是在什么时机做什么事的判断力。刚开始可以从最小例子入手跑通一个再慢慢加不要一次性堆五六个 hooks真到线上出问题的时候逐个排查的代价远低于一堆钩子相互影响。最后补一个小技巧动手改造之前先翻一下init生成的 hooks 示例目录里面往往就藏着很多人没注意到的标准写法照着那个风格写后续升级版本时你踩坑的概率会小很多。