概览

OpenClaw webhook，本质上是把“外部系统发来的 HTTP 请求”接进 OpenClaw，再由 OpenClaw决定：

• 是唤醒一个 agent
• 还是直接向 agent 投递一条消息
• 是否把结果回发到某个渠道
• 回发到哪个渠道、哪个目标

当前已经跑通的是一个很典型的最小场景：

• 外部 POST /hooks/wechat-notify
• OpenClaw 命中 hooks.mappings
• agent 按模板生成一条通知文本
• 通过 openclaw-weixin 渠道发到固定微信目标

当前配置在：

• openclaw.json
• plugin 版会话记录器在 index.js

原理

OpenClaw 的 webhook 入口由这几个配置共同组成：

• hooks.enabled
  打开 webhook 能力
• hooks.token
  用于 Bearer 鉴权
• hooks.path
  webhook 基础路径，当前是 /hooks
• hooks.mappings
  路由规则，决定不同子路径如何处理请求

你现在新增的 wechat-notify 映射可以理解成一句话：

• 当请求命中 /hooks/wechat-notify
• 就把请求体里的 title / text / level / source 套进模板
• 作为一条 agent 消息执行
• 并把最终结果投递到微信渠道 openclaw-weixin
• 收件人固定为 o9cq808hBSqYVWf89mnLZPQYBuss@im.wechat

所以 webhook 不是“直接发微信”的裸转发器，而是：

• HTTP 请求 -> OpenClaw 映射 -> agent 生成最终文本 -> 渠道投递

这也是它灵活的原因。

调用流程

如果结合你现在的落库插件，完整链路还可以看成：

当前实现

你现在实际可用的 webhook 是：

• 路径：/hooks/wechat-notify
• 方法：POST
• 鉴权：Authorization: Bearer shared-secret

当前请求示例：

curl -sk -X POST https://127.0.0.1:18789/hooks/wechat-notify \
  -H 'Authorization: Bearer shared-secret' \
  -H 'Content-Type: application/json' \
  -d '{
    "source": "manual-test",
    "level": "INFO",
    "title": "Webhook 测试通知",
    "text": "这是一条通过 wechat-notify webhook 发送的测试消息。"
  }'

当前成功返回过：

{"ok":true,"runId":"e0a683ce-aec5-4b7d-b8cf-0fd40056a422"}

当前固定目标是：

• channel = openclaw-weixin
• to = o9cq808hBSqYVWf89mnLZPQYBuss@im.wechat

当前固定 session 是：

• agent:main:hook:wechat-notify

这次执行也已经在独立记录库里看到结果：

• session_history_plugin.sqlite3

开发和使用方式

你现在这条 webhook 的开发方式，属于最轻量的一种：

1. 在 openclaw.json 里启用 hooks
2. 在 hooks.mappings 里新增一个映射
3. 指定：
   • match.path
   • action
   • sessionKey
   • messageTemplate
   • deliver
   • channel
   • to
4. 重启 gateway
5. 用 curl 测试

这类 webhook 最适合：

• 输入结构简单
• 输出结构简单
• 不需要复杂条件分支
• 不需要数据库查询
• 不需要调用多个工具

你现在这条配置的关键思路是：

• 外部只传结构化字段
• OpenClaw 用模板拼成 agent 输入
• agent 只负责“整理成最终通知文本”
• 然后直接回发到微信

也就是说，开发重点不是写很多代码，而是把映射规则设计清楚。

当前例子的价值

wechat-notify 是一个很好的实践起点，因为它满足几个条件：

• 路径固定
• 收件人固定
• 字段少
• 易测试
• 结果直观

它主要验证了这几条链路：

• webhook 鉴权是否生效
• hooks.mappings 是否生效
• agent 是否被成功触发
• 微信渠道是否可投递
• 会话记录插件是否能记下问答

所以它既是一个业务功能，也是一个“系统联通性测试用例”。

适合继续扩展的应用场景

在这个基础上，最适合继续做的场景有这些。

1. 服务器异常告警
   请求体里传 title=text=CPU 过高，直接发微信。

2. CI/CD 构建通知
   构建成功、失败、部署完成都可以通过 webhook 发到微信。

3. 定时任务完成提醒
   比如每日同步完成、日报生成完成、爬虫执行完成。

4. 审批提醒
   某个外部系统有待处理事项时，发一条微信通知。

5. 监控心跳
   服务恢复、服务离线、磁盘空间不足等通知。

6. 个人自动化提醒
   本地脚本、cron、数据库备份结果，都可以直接推给微信。

什么时候适合继续升级

如果后面你希望它更强一点，可以考虑这几个方向：

• 改成“完全不走模型润色”
  直接把模板文本原样投递，结果更可控。
• 增加 transform
  用本地 JS 模块先处理 payload，再决定最终 message。
• 增加多个路径
  比如 /hooks/wechat-notify、/hooks/build-alert、/hooks/server-alert
• 增加多个收件人
  不同 webhook 映射到不同微信目标。
• 增加级别样式
  INFO/WARN/ERROR 用不同标题前缀。

一句话总结

你现在这套 webhook 的本质，是把外部事件通过 OpenClaw 映射成一条 agent 消息，再通过微信渠道发出去。当前 wechat-notify 是一个非常适合练手和落地的最小通知场景，结构简单、调试容易、扩展空间也很大。