Webhooks

首先，我们要打开这个小门铃。就像打开玩具的开关一样，我们需要在系统的设置文件里，写上几行“魔法咒语”。最重要的咒语是 hooks.enabled: true，意思是“打开门铃”。同时，我们还要设置一个秘密口令 token，这样只有知道口令的人才能按响门铃。门铃的地址 path 默认是 /hooks，你也可以改成别的。

按门铃的时候，必须告诉它秘密口令。最好是把口令放在请求的“头”里，就像把钥匙挂在脖子上。你可以用 Authorization: Bearer <你的口令> 或者 x-openclaw-token: <你的口令> 这两种方式。注意，不能把口令放在网址里（比如 ?token=...），那样是无效的，门铃会生气地拒绝。

门铃有不同的按法，会触发不同的事情：

1. 按“叫醒”门铃 (POST /hooks/wake)：这就像轻轻推一下正在睡觉的“主助手”，告诉它“有事情发生啦！”。你需要告诉它发生了什么事（text），比如“收到新邮件了”。还可以选择是立刻叫醒它 (mode: now)，还是等它自己下次检查时再说 (mode: next-heartbeat)。

2. 按“小助手”门铃 (POST /hooks/agent)：这可以直接派一个“小助手”去执行一个任务。你需要告诉它：

   • message：要小助手做什么，这是必须的。
   • agentId：指定哪个小助手去干活。如果不认识这个名字，就派默认的小助手去。
   • wakeMode：和上面一样，选择立刻行动还是稍等一下。
   • 你还可以告诉它把结果送到哪里（channel 和 to），用哪个大脑模型（model），想问题要想得多深（thinking），以及最多给它多少时间（timeoutSeconds）。

这里有个很重要的安全规则：默认情况下，不允许按门铃的人自己决定用哪个“任务本”（sessionKey）。这就像你不能让陌生人随便选你家的哪个本子来写字。推荐的做法是，在设置里固定一个任务本名字，比如 defaultSessionKey: "hook:ingress"，并且把 allowRequestSessionKey 设为 false。

除了上面两个固定的门铃，你还可以设置自己的“专属门铃”，比如 /hooks/gmail。这需要在设置里定义“映射”（mappings），告诉系统“如果有人按这个专属门铃，就把他的请求变成上面两种按法之一”。你甚至可以用一小段代码（transform.module）来改变收到的信息。

最后，要记住保护你的小门铃：

• 最好只让你信任的软件（比如在同一个电脑或内部网络里）来按它。
• 一定要用一个专门的、复杂的口令（token）。
• 如果有人连续输错口令，系统会暂时不让他按（429 错误）。
• 在设置里，可以用 allowedAgentIds 来限制别人可以指定哪些小助手。
• 尽量不要在日志里记录门铃收到的原始信息，以防泄露秘密。