Events，翻译成中文就是事件，这可能是OpenClaw底层基础知识中不大好理解的一部分，但请相信老马，拆解完你会感觉很有意思。

因为你能知道小龙虾里面的一些事件，到底是怎样完成自动化响应和外部集成的。

也就是每天启动OpenClaw的时候 ，小龙虾干了什么事。你说话的时候，小龙虾是怎样回应的。别人叫你的小龙虾时，它又干了什么事情。

Events在OpenClaw中，我们需要把它当成是一个事件的系统，因为它包含了消息事件、Hooks与Webhooks三个部分。

想象你养了一只特别聪明的电子宠物狗（OpenClaw）。Events（事件系统）就是这只狗的“感官神经”。

它不用你一直盯着，只要发生了特定的事，它就会自动做出反应。

当有人喊它（消息事件）的时候，比如你在飞书群里@它，它立马跳出来回复你。

当它每天早上起床（系统启动）时，自己伸懒腰（Hooks），就像是自动去门口巡视一圈，然后发个报平安的消息。

当快递员（外部系统，如股票软件、GitHub）给它打个电话说快递到了，就像是收到快递通知（Webhooks），它立马跑去取货并告诉你。

Events就是让AI从你问它才答，变成有事它主动办。所以Events的大致架构图如下：

┌─────────────────────────────────────────────────────────┐
│                    OpenClaw Gateway                      │
│                                                          │
│  ┌──────────────┐     ┌──────────────┐     ┌──────────┐│
│  │   Event      │     │   Event      │     │  Event   ││
│  │  Sources     │────▶│   Router     │────▶│ Handlers ││
│  │  (事件源)    │     │  (路由器)    │     │ (处理器) ││
│  └──────────────┘     └──────────────┘     └──────────┘│
│         ▲                                       │       │
│         │                                       ▼       │
│  ┌──────┴───────┐     ┌──────────────┐     ┌──────────┐│
│  │  消息渠道    │     │   Hooks      │     │ Webhooks ││
│  │ QQ/飞书/...  │     │  生命周期    │     │  外部 API ││
│  └──────────────┘     └──────────────┘     └──────────┘│
│                                                          │
└─────────────────────────────────────────────────────────┘

另外，有些小伙伴可能会觉得Events跟OpenClaw的定时任务有点像。看起来都是达到了某个条件，小龙虾就会去干活。

但其实它们之间是两个不搭噶的东西，Events是因为有了事件才会触发，而定时任务是时间到了就会触发，前者被动，后者主动，区别如下表：

下面我们深入Events，挨个详细了解一下消息事件、Hooks、Webhooks。

消息事件（Message Events）

消息事件是最好的理解一个，就是当你在QQ、飞书等地方给机器人发消息时，触发的小龙虾一系列动作。

从应用场景来看，除了让小龙虾与我们日常的沟通中，做到句句有精确回应之外，还可以用来管理一下社群。

比如在飞书群里，设置一个机器人社群管家，加上触发的关键词，只要有人在群里发广告，它直接自动回一句再发广告就抱你出去。

另外一个是常见的7×24小时客服，像大半夜有人问怎么充值，小龙虾自动把充值教程甩过去，不用你半夜爬起来回消息。

还有就是消息备份，假设你给小龙虾发了一份重要文档，它可以自动同步保存一份到飞书文档。

核心的消息事件类型主要有以下这些：

由于消息事件是跟你的OpenClaw绑定的Channel（频道）关联的，比如你接入的是QQ机器人，那对应的设置就是QQ机器人的一些事件回复。

因此除了上面表格中列出来核心消息事件类型，接入的不同频道，它们还有拓展的消息事件类型。

比如飞书机器人还支持群聊消息、文档更新、日历事件等消息事件类型，与此同时，你还能够通过创建Skill，设置Hooks去自定义一些消息事件类型。

你需要设置消息事件时，直接跟小龙虾对话，让它帮你进行设置即可，不用自己去修改添加添加配置。

以小龙虾作为一个客服机器人为例，我们配置一下当小龙虾收到的关键词是怎么用、帮助中心、操作教程时，自动回复指引，示例的配置如下：

{
  "type": "message.received",
  "filter": {
    "keywords": ["帮助", "help", "怎么用"]
  },
  "response": {
    "type": "text",
    "content": " 你好！我可以帮助你：\n1. 查询股票行情\n2. 设置定时提醒\n3. 管理文件\n\n请告诉我具体需求~"
  }
}

以上示例配置仅供参考，还是那句话，你需要用自然语言描述清楚自己需要设置什么消息事件，或者再加上上面的这段示例配置，一起发给小龙虾即可。

Hooks（生命周期钩子）

Hooks钩子对于程序员来说是再熟悉不过的函数，在普通用户眼里，我们可以把它看成是OpenClaw系统的贴心管家那样子。

它是在特定时间点自动干活的指令，想象成你给管家定的规矩。出门前（启动时）记得锁门，客人走之后（会话结束）记得打扫房间。

从应用场景来看，比如我们设置一个Gateway网关启动的Hooks，那么当小龙虾重启好了，自动给你发一条消息：本聋瞎满血复活，随时待命！

又或者每次新对话开始，自动把你的喜好文件（如USER.md）读一遍，不用你重复介绍自己。

虽然AGENTS.md里有写这样的要求，但是添加一个Hooks去强制加载USER.md，能兜底小龙虾遗漏的情况，需要强制加载其它md文件也是一样的思路。

另外也可以设置一个 Hooks，让小龙虾每次用了什么工具（比如查了天气、算了卦），自动记在小本本上，方便以后查账。

这个看起来跟OpenClaw的记忆系统好像有点类似，但又不一样。小龙虾的记忆系统是语义化的、有选择的，会提炼重点但可能遗漏细节，且不一定会主动记忆。

而设置一个Hooks去记录工具的调用情况，这个日志是自动的、完整的、被动的，每次工具调用都会记录，适合查账和审计。

等于你搞一个Hooks钩子钩住它，让系统自动记录每次工具调用的详细信息（工具名、参数、时间、结果），存到专门的日志文件中。

系统级内置的Hooks主要有以下这些：

以上系统内置的Hooks，你是不可以更改的，主要用于系统内部逻辑、插件开发和高级扩展。

除此之外还有跟接入频道相关的消息Hooks，这些也都是固定死的。你可以自定义的Hooks叫Internal Hooks。

Internal Hooks是在OpenClaw.json配置文件中进行设置的，而你在创建Skill的时候，或者让小龙虾写脚本代码的时候，同样可以自定义Hooks。

但大多数情况下，你在了解了Hooks是什么东西，有什么用之后，都可以直接告诉你的小龙虾，让它去设置一个新Hooks，不需要自己动手。

比如我们想在Gateway网关启动时，设置一个Hooks，能够自动地给QQ机器人发送一条消息，告诉我们网关启动成功了，那示例的配置如下：

{
  "hook": "gateway.start",
  "handler": "notify",
  "channels": ["qqbot"],
  "message": " Gateway 已启动\n\n 状态检查：\n- 端口：18789 ✅\n- 渠道：QQ、飞书 ✅\n- 内存：正常 ✅\n\n准备就绪！"
}

Webhooks（外部集成）

Webhooks可以理解成连接外部世界的万能插座，这是最高级的玩法。简单说，就是给机器人一个专用的电话号码或者网址。

外面的世界（股票软件、代码仓库、监控报警）只要往这个号码打个电话（发送数据），小龙虾就开始干活。

Webhooks的架构如下图所示：

外部系统 → Webhook URL → OpenClaw Gateway → 执行任务
   │                          │
   │                          ▼
   │                    事件处理
   │                          │
   │                          ▼
   └────────────────── 返回结果

从应用场景来看，Webhooks可以干的事情就太多了，但你得理解一个关键点，那就是Webhooks是被动接收通知的机制。

经常会用到的，比如作为炒股神器，设定好中科曙光涨到90块，通过行情API监控，一旦达标，小龙虾马上在QQ上通知你快跑，止盈信号来了。

作为程序员的小助手，代码写完提交到仓库，小龙虾自动收到通知，帮你把新程序部署上线，然后汇报老板，新版已发布。

或者作为智能家居联动，家里温度传感器发现太热了，发个信号给小龙虾，它会自动帮你开空调（需空调设备自带功能或配合其他工具）。

以GitHub推送代码时自动部署为例，下面是对应的示例配置：

Webhook URL：https://your-server:5000/github

{
  "path": "/github",
  "method": "POST",
  "handler": "github-handler",
  "secret": "github-secret",
  "filter": {
    "events": ["push"],
    "branches": ["main"]
  },
  "task": "检测到 main 分支推送，执行：\n1. 拉取最新代码\n2. 安装依赖\n3. 重启服务\n4. 发送部署结果通知"
}

但Webhooks毕竟属于高阶的玩法，建议不是那么懂技术的小伙伴可以先不尝试。如果真的感兴趣，可以采用方案引导的方式，让小龙虾帮你一步步配置。

比如，你的提示词可以像老马下面这样去写：

我现在需要设置GitHub Webhooks，实现当我的代码仓库有提交时，能够及时地通知我。

实现方式：在GitHub仓库配置Webhooks，当有push/PR事件时，GitHub会主动推送通知到OpenClaw，小龙虾马上在QQ上告诉我：代码已提交，快来review。

请一步步引导我完成配置，在我没有确认允许进入下一步操作时，绝对不能私自执行任何操作。

当然，Webhooks还有相关的签名和密钥验证机制，用于确保请求来源可信。这个机制的具体实现（如签名算法、Header名称、密钥格式），取决于不同服务提供商的定义。

看不懂没关系，就好像这篇文章一样，有些小伙伴怎么看都理解不了。这种情况就是建议全文丢给你的小龙虾，让它用大白话加举例的方式，翻译给你看。

常用命令速查

Events其实是会有一些常见故障报错的，比如消息事件不触发、Webhooks无法接收、Hooks不执行等情况。

但因为我们现在有了大模型，加上小龙虾这个能干活的身体，一般的故障都可以直接让小龙虾自己去处理，最好是先查明打印出日志，再通过日志去排查原因。

因此下面给大家贴一些常用的命令，以便于遇到问题时快速定位。

（1）Events相关命令

# 查看事件配置
openclaw events list


# 测试事件
openclaw events test message.received


# 查看事件日志
openclaw logs --type events --follow


# 重新加载事件配置
openclaw events reload

（2）Webhooks相关命令

# 查看 Webhooks 状态
openclaw webhooks status


# 测试 Webhook
openclaw webhooks test /github


# 重启 Webhooks 服务
openclaw webhooks restart

（3）Hooks相关命令

# 查看 Hooks 配置
openclaw hooks list


# 手动触发 Hook
openclaw hooks trigger gateway.start


# 查看 Hook 日志
openclaw logs --type hooks

好了，以上就是今天的分享，欢迎关注、点赞、转发一键三连。有任何问题和需求，请在评论区留言，回见！

对了，老马最近刚创建了一个AI学习交流群，有兴趣进群的小伙伴可以添加老马微信号：immajiabin，添加好友时备注：进群（不备注不通过）。