1. OpenClaw hooks 是什么能帮你自动做什么OpenClaw hooks 是 OpenClaw 里的事件钩子机制说白了就是给系统装上一排“感应开关”当某个事件发生时比如收到新消息、会话结束、工具调用完成OpenClaw 会自动去执行你写好的脚本。你不用一直盯着程序跑也不用轮询状态事件一触发逻辑自己就跑起来了。它适合谁适合想把重复动作自动化的人比如收到消息自动记日志、Agent 报错自动通知、会话结束自动备份记录这些场景都能用 hooks 接住。我先把核心概念讲清楚不然后面配置容易懵。OpenClaw hooks 有两个关键点事件类型和钩子脚本。事件类型决定“什么时候触发”钩子脚本决定“触发后干什么”。OpenClaw 内置了一批事件常见的有message.received收到新消息、message.sent消息发送完成、session.started新会话开始、session.ended会话结束、agent.errorAgent 发生错误、tool.executed工具调用完成、channel.connected渠道连接成功、channel.disconnected渠道断开。你写的脚本放在~/.openclaw/hooks/目录下OpenClaw 启动时会扫描这个目录把发现的钩子注册进来。管理这些钩子靠的是openclaw hooks命令族它有几个子命令list列出所有已发现的钩子enable启用指定钩子disable禁用指定钩子info查看钩子详情。这几个命令是你日常调试的主力尤其是list和info排查问题时几乎离不开。为什么值得花时间学 hooks因为它把“被动响应”变成了“主动自动化”。举个例子你运营一个客服 Agent每次收到消息都想知道内容手动翻日志太累。写一个message.received钩子把消息写进本地文件或者推送到你的监控面板整个过程零人工。再比如 Agent 出错时你希望第一时间知道agent.error钩子就能触发通知脚本。这些都不是理论是能直接跑起来的。不过 hooks 本身只负责“触发”脚本里如果要调用大模型能力比如让 Agent 分析消息内容、生成摘要就需要一个稳定的 API 通道。这里我用 TaoToken 来统一管理 Key 和调用入口后面第三节会给完整配置。先把 hooks 的基础操作跑通再接入模型调用顺序别乱。这一节你先记住三件事hooks 是事件驱动的自动化机制脚本放~/.openclaw/hooks/管理命令是openclaw hooks list/enable/disable/info。下一节我们把环境准备好把第一个钩子跑起来。2. 前置准备TaoToken 统一 Key 与 OpenClaw 环境在写第一个 hook 之前得先把两件事搞定OpenClaw 本身能跑以及模型调用通道配好。很多人卡在第二步因为脚本里一旦要调模型Key 管理、Base URL、模型 ID 三样缺一不可。我用 TaoToken 来做统一入口原因是它把 Key 和 API 通道收敛到一处脚本里不用散落多个密钥换模型也不用改一堆文件。先确认 OpenClaw 已安装并能执行命令。打开终端输入openclaw --version如果能看到版本号说明主程序就绪。接着确认 hooks 目录存在ls -la ~/.openclaw/hooks/目录不存在就手动建一个mkdir -p ~/.openclaw/hooks然后是 TaoToken 的接入准备。你需要拿到两样东西API Key 和 Base URL。API Key 在控制台的 API Keys 页面创建地址是https://taotoken.net/api-keys创建后复制保存后面配置里要用。Base URL 固定为https://taotoken.net/api注意这个地址不带任何查询参数直接写进配置即可。模型 ID 根据你要用的模型填比如对话类、代码类各有对应 ID在模型对话页面能看到当前可用的模型列表地址是https://taotoken.net/chat。如果你打算长期跑编码类 Agent可以了解 Coding Plan入口在https://taotoken.net/coding-plan。这些链接先记着配置时按需取用。环境变量方式是最省事的做法。在~/.bashrc或~/.zshrc里加两行export TAOTOKEN_API_KEY你的API Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api保存后执行source ~/.bashrc让配置生效。验证一下echo $TAOTOKEN_API_KEY能打印出 Key 就说明环境变量没问题。这样做的好处是钩子脚本里直接读环境变量不用把密钥硬编码进代码安全性和可维护性都好很多。还有一点容易被忽略Node.js 环境。OpenClaw 的钩子脚本通常是.js文件需要 Node 运行时。确认一下node --version建议用 Node 18 以上版本。如果版本太低钩子脚本里的现代语法可能报错。到这里OpenClaw 命令可用、hooks 目录就绪、TaoToken 的 Key 和 Base URL 准备好、Node 环境正常四件事齐了。下一节直接写配置和脚本。3. 可复制配置写第一个 hook 并接入 TaoToken这一节是核心我会给出一份能直接复制的钩子脚本以及配套的配置片段。目标场景很明确当 OpenClaw 收到新消息message.received时触发脚本把消息内容通过 TaoToken 的 API 通道发给模型做一次摘要然后把摘要写到本地日志。这个场景覆盖了事件触发、脚本执行、模型调用三个环节跑通它其他钩子就是换事件名和换逻辑的事。先建脚本文件touch ~/.openclaw/hooks/log-messages.js然后用编辑器打开写入以下内容// ~/.openclaw/hooks/log-messages.js const fs require(fs); const path require(path); const LOG_FILE path.join(process.env.HOME, .openclaw, hooks, messages.log); const API_KEY process.env.TAOTOKEN_API_KEY; const BASE_URL process.env.TAOTOKEN_BASE_URL || https://taotoken.net/api; const MODEL_ID 你的模型ID; module.exports { name: log-messages, event: message.received, priority: 100, enabled: true, async handler(context) { const { message } context; const timestamp new Date().toISOString(); const raw [${timestamp}] ${JSON.stringify(message)}\n; fs.appendFileSync(LOG_FILE, raw); try { const resp await fetch(${BASE_URL}/v1/chat/completions, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${API_KEY} }, body: JSON.stringify({ model: MODEL_ID, messages: [ { role: system, content: 你是一个消息摘要助手用一句话概括用户消息。 }, { role: user, content: message.content || } ] }) }); const data await resp.json(); const summary data.choices?.[0]?.message?.content || 无摘要; fs.appendFileSync(LOG_FILE, 摘要: ${summary}\n); } catch (err) { fs.appendFileSync(LOG_FILE, 摘要失败: ${err.message}\n); } } };这份脚本做了两件事先把原始消息追加到messages.log再调用 TaoToken 的/v1/chat/completions接口拿摘要追加到同一文件。注意MODEL_ID要替换成你在模型对话页面看到的实际模型 ID别照抄占位符。如果你更习惯用配置文件声明钩子OpenClaw 也支持在~/.openclaw/config.json里登记。参考片段如下{ hooks: { log-messages: { event: message.received, script: ~/.openclaw/hooks/log-messages.js, priority: 100, enabled: true } }, api: { baseUrl: https://taotoken.net/api, apiKeyEnv: TAOTOKEN_API_KEY, defaultModel: 你的模型ID } }这份 JSON 里hooks段声明钩子名、事件、脚本路径、优先级和启用状态api段把 Base URL、Key 的环境变量名、默认模型统一登记。这样脚本里读process.env.TAOTOKEN_API_KEY配置里读api.baseUrl两边一致不会出现 Key 写错地方的问题。三件套再强调一遍Base URL 是https://taotoken.net/apiKey 从 API Keys 页面创建后放进环境变量Model ID 从模型对话页面获取。这三样在脚本和配置里必须对齐任何一处写错都会导致调用失败。写完脚本和配置后先别急着启用用openclaw hooks list确认 OpenClaw 是否发现了这个钩子。如果没发现检查文件名和路径是否在~/.openclaw/hooks/下以及脚本是否导出了name和event字段。下一节我们做触发验证。4. 验证请求触发 hook 并确认成功结果配置写完接下来是验证。验证分两步先确认钩子被正确发现和启用再实际触发一次事件看日志里有没有预期输出。第一步列出所有钩子openclaw hooks list正常输出类似NAME EVENT STATUS PRIORITY log-messages message.received enabled 100如果log-messages出现在列表里且状态是enabled说明发现和注册都成功。如果状态是disabled执行openclaw hooks enable log-messages再查一次确认状态变了。如果列表里根本没有这个钩子回到上一节检查脚本路径和导出字段。第二步查看钩子详情确认事件和脚本路径对得上openclaw hooks info log-messages输出会包含事件类型、状态、优先级、脚本路径、最近运行时间和运行次数。这里重点看Script字段指向的路径是不是你实际写的文件以及Event是不是message.received。第三步实际触发。触发方式取决于你的 OpenClaw 运行环境最直接的办法是发一条测试消息给 Agent。发完之后查看日志文件cat ~/.openclaw/hooks/messages.log如果看到类似下面的内容说明整条链路跑通了[2025-01-15T14:30:22.000Z] {content:你好帮我看看这个报错} 摘要: 用户请求协助排查一个报错信息。原始消息和模型摘要都写进去了说明事件触发、脚本执行、TaoToken 调用三个环节全部正常。如果只有原始消息没有摘要说明模型调用那一步出了问题往下看第五节排查。也可以用 JSON 格式输出钩子列表方便脚本化检查openclaw hooks list --json按事件类型过滤openclaw hooks list --event message.received按状态过滤openclaw hooks list --status enabled这几个过滤命令在钩子多了以后特别有用能快速定位某个事件下挂了哪些钩子。验证通过后你可以把log-messages的逻辑复制成其他钩子比如把事件换成agent.error逻辑换成发通知就是一个错误告警钩子。事件类型列表在前面第一节已经列过按需取用即可。5. 常见报错排查401、local proxy failed 与 choices 读取失败钩子跑不起来报错通常集中在几类。这一节我按真实遇到的顺序列出来对照着查。第一类401 未授权。日志里出现401 Unauthorized或者invalid api key基本是 Key 的问题。检查三处环境变量TAOTOKEN_API_KEY是否真的导出成功脚本里读取的变量名是否和导出的一致Key 是否在 API Keys 页面被删除或过期。用echo $TAOTOKEN_API_KEY确认终端里能打印出来如果打印为空说明source没生效或者写错了文件。另外注意 Key 前后不要有空格复制时容易带上。第二类local proxy failed或连接超时。这类报错说明请求根本没发到 TaoToken或者网络层被拦了。先确认 Base URL 写的是https://taotoken.net/api不要多加斜杠或路径。再确认脚本里拼接的完整地址是${BASE_URL}/v1/chat/completions路径拼错也会导致连接失败。如果本机有网络策略限制检查是否能正常访问该域名。这类问题不要往 Key 上想方向是地址和网络。第三类reading choices或Cannot read properties of undefined。这个报错说明接口返回了但返回结构里没有choices字段脚本去读data.choices[0]就崩了。常见原因是模型 ID 写错接口返回了错误信息而不是正常补全结果。解决办法是在脚本里先判断resp.ok不 ok 就把返回体打出来if (!resp.ok) { const errText await resp.text(); fs.appendFileSync(LOG_FILE, 接口错误 ${resp.status}: ${errText}\n); return; }这样能看到具体错误信息而不是被choices的报错掩盖。模型 ID 从模型对话页面核对别用猜测的值。第四类OAuth 相关报错。如果你用的是需要 OAuth 授权的客户端比如某些编码工具报错里可能出现OAuth token expired或invalid_grant。这类问题不在 hooks 脚本本身而在客户端的授权配置。检查客户端的授权文件是否过期重新走一次授权流程。如果是 Codex 这类工具授权信息通常在auth.json里确认里面的字段完整。这类报错和 hooks 无关但会表现为“钩子没触发”容易误判所以单独列出来。第五类钩子被发现但没执行。openclaw hooks list能看到但触发事件后日志没变化。检查优先级是否被其他钩子拦截以及事件名是否拼写正确。message.received和message.recieved差一个字母就不会触发。用openclaw hooks info name看Last Run时间如果一直是初始值说明根本没被调用。排查顺序建议先看openclaw hooks list确认发现和启用再看日志文件确认脚本是否执行最后看接口返回确认模型调用是否成功。三段式定位比盲目改配置快得多。6. 把 hooks 用起来从单钩子到自动化流程跑通第一个钩子之后真正的价值在于组合。单个log-messages只是记录把多个钩子按事件串起来就能形成自动化流程。比如session.started触发初始化脚本message.received触发摘要和日志agent.error触发告警session.ended触发归档。四个钩子各管一段互不干扰靠事件驱动衔接。优先级字段在这里很关键。同一个事件下挂多个钩子时priority决定执行顺序数值小的先跑。比如你希望先记录原始消息再生成摘要就把记录钩子的优先级设成 50摘要钩子设成 100。如果顺序反了摘要可能基于不完整的数据。这个细节在钩子多了以后特别重要建议一开始就规划好优先级。脚本里的模型调用统一走 TaoToken 的通道好处是换模型只改一个MODEL_ID不用动请求逻辑。如果你要长期跑编码类 AgentCoding Plan 的入口在https://taotoken.net/coding-plan适合把多个钩子的模型调用收敛到一套配额里管理。需要新建 Key 或者轮换 Key去https://taotoken.net/api-keys。接入细节和参数说明在文档里地址是https://taotoken.net/doc。想先试试模型返回效果模型对话页面在https://taotoken.net/chat可以直接对话验证。最后给一个实用建议钩子脚本里所有外部调用都加 try/catch并且把错误写进日志。钩子是在事件触发时执行的一旦抛异常没人接可能影响主流程。把错误吞掉并记录比让整个事件处理崩掉要好。日志文件定期清理避免无限增长。做到这两点hooks 就能稳定长期运行。