用 Webhooks 做安全的外部事件接入

把外部系统接进 OpenClaw 最容易出现的两个问题，不是“连不上”，而是：

• 事件接进来了，但投递到错的会话或错的渠道
• 为了方便调试，把安全边界一起打开了

最新官方 Webhooks 文档其实已经把这两类风险讲得很清楚。更稳的做法不是一开始就写复杂 transform，而是先把接入顺序和权限边界理顺。

第一原则：先有固定入口，再有复杂路由

更稳的外部接入顺序通常是：

1. 启用最小 hooks.enabled + token
2. 用 /hooks/wake 跑通第一条事件
3. 再把固定来源迁移到 hooks.mappings
4. 最后才开放 agentId、sessionKey、transform

如果一开始就把所有灵活能力都打开，后面排错时你根本分不清问题出在：

• 来源系统
• Gateway 鉴权
• 映射逻辑
• 会话路由
• 渠道投递

第二原则：把 token、agent、session 分开管

最容易被低估的，是 agentId 和 sessionKey 的风险。

官方默认就已经在提醒你：

• hooks.allowRequestSessionKey=false
• hooks.allowedAgentIds 应该尽量收窄
• 如果必须允许外部指定 session，最好再限制 hooks.allowedSessionKeyPrefixes

一个更稳的内部规范是：

• token 只负责“能不能进来”
• agentId 只允许极少数专用 agent
• sessionKey 只允许 hook: 这类外部隔离前缀

这样即便接了多个系统，也不容易把外部事件混进人工对话上下文里。

第三原则：不要迷信 channel=last

官方文档里 channel 默认是 last，这在快速起步时很方便，但在正式接线时是个风险点。

一旦你的主会话最近刚在别的渠道活动过，last 很可能不是你以为的那个目的地。

更稳的做法通常是：

• 单来源单目标：直接固定 channel + to
• 同类型事件按映射决定渠道
• 只有个人实验环境才依赖 last

如果是 Gmail、工单、审批这类正式入口，最好不要把最终投递交给“上一次是谁”来决定。

第四原则：来源固定后就别让外部系统自己写 prompt

很多团队刚接外部事件时，会让来源系统直接传很长的文本 prompt 进来。这样短期省事，长期会越来越难维护。

更稳的模式是：

• 来源系统只传结构化 payload
• OpenClaw 用 hooks.mappings 决定 messageTemplate
• 必要时再通过 transform 做定制

这样做的好处是：

• 文案和行为逻辑都留在 OpenClaw 侧
• 外部系统改字段时更容易定位影响
• 统一加安全边界、模型和投递策略更方便

第五原则：把 transform 当成最后一层，而不是第一层

官方提供 transform 是为了处理复杂场景，不是为了替代基本映射。

更适合上 transform 的情况包括：

• payload 结构差异很大
• 需要复杂规则判断
• 要做字段整形、去噪或路由增强

如果只是把 source + title + url 拼成一句话，那普通 messageTemplate 通常就够了。

一个比较稳的来源划分方式

你可以把外部事件先按三类处理：

轻量提醒类

例如：

• 新表单
• 新邮件
• 新审批

适合：

• /hooks/wake
• deliver=true
• 明确渠道投递

结构化工作类

例如：

• GitHub webhook
• 工单系统事件
• 监控报警

适合：

• hooks.mappings
• 专用 agentId
• 隔离 sessionKey

高风险内部系统类

例如：

• 内部 ERP
• 审批回调
• 涉及敏感数据的业务系统

适合：

• 严格 token 管理
• loopback / tailnet / trusted proxy
• 默认保留外部内容安全包装

最应该保留的几个安全默认值

如果你不确定该不该改，建议先保持官方默认：

• hooks.allowRequestSessionKey=false
• 不关闭外部内容安全包装
• 不把 token 放在 query string
• 不开放任意 agentId

这些限制大多不是为了“麻烦你”，而是为了避免外部事件把系统带进不可控状态。

什么情况下说明你该重构接入方案了

如果你已经出现下面这些症状，说明接入策略该重构了：

• 同一类外部事件会送到不同会话
• 调试时必须临时关掉安全边界
• 很多来源系统自己维护一套 prompt
• 渠道投递经常依赖 last

这时候通常不是某条 webhook 坏了，而是路由策略本身需要收口。

下一步推荐

• 先看 用 Webhooks 接外部系统
• 如果来源是 Gmail，再看 Gmail Pub/Sub 接入 OpenClaw
• 如果外部事件会进入长期自动化，再接着看 用 Heartbeat 和 Cron 做低噪音自动化