入站 webhooks
Gateway HTTP 钩子:外部服务如何调用 OpenClaw 来唤醒 agent 或提交一个 agent 回合。属于 Automations 指南的一部分。
Webhooks¶
Gateway HTTP 钩子让外部服务唤醒 agent 或提交一个 agent 回合。
它们默认禁用。这些端点与 内部事件钩子(HOOK.md 处理器)是分开的。它们也与出站自动化 webhook 投递不同:在这里,外部服务调用 OpenClaw。
启用并测试 agent 钩子¶
从一个正在运行的 Gateway 和一个能够完成正常回合的 agent 开始。将此合并到你的配置中,将 token 替换为一个长随机值,并将 main 替换为预期配置的 agent:
{
hooks: {
enabled: true,
token: "<long-random-hook-token>",
path: "/hooks",
allowedAgentIds: ["main"],
allowRequestSessionKey: false,
},
}
使用专用于钩子的 token,而不是 Gateway 身份验证 token 或密码。在 Gateway 主机上使用其 profile/config 运行这些命令。验证配置,重启已安装的服务以加载它,并查看日志:
如果你在前景中运行 Gateway,而不是作为已安装的服务,则改为停止并启动该进程。
在另一个终端中,向本地 Gateway 发送一个无害的测试。替换 token、agent id 和端口以匹配你的配置:
curl --include http://127.0.0.1:18789/hooks/agent \
-H 'Authorization: Bearer <long-random-hook-token>' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: webhook-smoke-001' \
--data '{"message":"Summarize this test event: the sample import completed.","name":"Webhook smoke test","agentId":"main","deliver":false}'
预期的准入响应是 HTTP 200:
这意味着该运行获得了会话/全局放置准入。它不意味着模型已完成、某个工具成功或消息已投递。单个 agent 请求可能最多等待 15 秒以获得准入;响应到达时模型运行时可能仍在准备中。
对于需要在同一请求中获取最终执行和投递事实的调用方,请在直接 /hooks/agent payload 中添加 "waitForCompletion": true。响应在准入后保持打开,并在已准入的运行结束时返回 HTTP 200:
{
"ok": true,
"runId": "<hook-request-run-id>",
"completion": {
"status": "ok",
"replyDisposition": "silent",
"delivered": false,
"deliveryAttempted": true,
"deliverySuppressionReason": "silent"
}
}
replyDisposition 记录模型的最终回复是 visible、silent 还是 empty,而不暴露其文本。准入后的执行或投递失败是 completion 中的最终数据,而不是可重试的 HTTP 失败。deliveryError(如果存在)是固定的分类值 "delivery-failed";提供方、运行时、模型、目标、会话和诊断详情保持私有。响应从不包含模型输出或摘要。使用幂等键,以便丢失的响应可以重放同一已准入运行和完成结果,而无需再次派发。
在 openclaw logs --follow 中,搜索 hook agent run completed 和确切的 HTTP runId。具有 status=ok 且没有显式投递错误的运行会在 info 级别记录日志;所有非 ok 状态(包括被跳过的运行)、抛出的错误以及显式投递错误会在 warn 级别记录日志。对于这个 deliver: false 测试,预期 status=ok 且没有成功通知。带有 status=ok 和 deliveryError 的警告表示执行成功但投递失败。它不会触发另一次通知尝试。
结构化最终记录包含已接受的 agentId、jobId、钩子名称和源路径,以及 logicalSessionKey。当 runner 返回它们时,sessionId 关联运行转录,sessionKey 标识运行时会话键。精确运行的续接别名可以在完成后退役;该键不保证单独的持久会话行。缺失的会话事实仍未知。诊断信息会被脱敏、单行化,并且每个字符串限制在 500 个字符以内。成功输出不会记录日志:请检查 agent 的运行会话以查看它。HTTP runId 用于关联钩子日志;它不是要传递给 openclaw automations runs 的自动化作业 ID。
sessionMode 默认为 isolated,因此该测试会获得一个新的运行会话和一个生成的逻辑 hook:<uuid> 键。存储的会话可以使用 cron:...:run:... 键;逻辑钩子键并不保证转录的存储键。固定的 defaultSessionKey 会串行化共享该键的请求,即使在 isolated 模式下也是如此;仅当预期该顺序时使用它。
身份验证¶
每个请求都必须通过以下其中一个请求头包含钩子 token:
Authorization: Bearer <token>(推荐)。x-openclaw-token: <token>。
查询字符串 ?token=... 身份验证会被拒绝。使用 Content-Type: application/json 发送 JSON。所有钩子端点仅接受 POST。Hooks 参考 列出了 payload 字段、限制、路由策略和错误响应。
POST /hooks/wake
为所选 agent 的主会话入队一条可信通知。立即唤醒使用普通会话执行:
curl --include http://127.0.0.1:18789/hooks/wake \
-H 'Authorization: Bearer <long-random-hook-token>' \
-H 'Content-Type: application/json' \
--data '{"text":"The sample import completed","mode":"now","agentId":"main"}'
HTTP 200 在队列接受唤醒时包含 eventOutcome: "queued",或在同一唤醒已经是队列中最近的待处理事件时包含 eventOutcome: "coalesced"。使用 mode: "now" 时,响应确认已获准进入普通会话执行,而不是执行或投递已完成。该事件会排在该会话中现有工作之后,且不依赖心跳频率或活跃时段。使用 mode: "next-heartbeat" 可将事件保留到下一次心跳。
当会话队列已满时,系统会返回 HTTP 503 并附带可操作的错误,而不是驱逐已接受的事件。请让会话先处理其待处理事件,然后再重试。这也适用于映射的唤醒操作;当队列已满时,重复的唤醒仍可能合并。
提供的 `agentId` 必须指向一个已配置的 agent。当 fleet 没有隐式或保留的遗留所有者时,请显式提供它。调用方选择的 `sessionKey` 需要 `mode: "now"`、`hooks.allowRequestSessionKey: true` 以及已配置的前缀策略;延迟唤醒使用主会话。
唤醒文本是一个系统事件,而不是一个隔离的、带安全包装的邮件阅读器回合。只发送你控制的简短通知。将原始邮件、文档或其他不可信内容通过带有受限阅读器的 `agent` 操作进行路由。
POST /hooks/agent
提交一个 agent 回合,其中 message 为必填项。可选的路由、模型、思考、超时和幂等性字段在 负载参考 中有说明。
对于全新上下文,请保持 sessionMode: "isolated"。仅当重复事件应复用先前上下文时,才设置为 "persistent":此时直接请求需要显式的 sessionKey、hooks.allowRequestSessionKey: true 以及非空的 hooks.allowedSessionKeyPrefixes。
当提供 sessionKey 时,它必须是非空字符串。格式错误或空白的键会返回 400,而不是静默选择默认或生成的会话键。
对于直接通道投递,请同时提供具体的 channel 和 to;添加 accountId 以选择已启用的通道账户。仅提供目标的一部分、使用 channel: "last" 或选择无效账户会在分发前返回 400。直接钩子不会继承主会话的上一个收件人。
在没有目标时,默认 deliver: true 允许在目标 agent 的主会话上产生完成系统事件。设置 deliver: false 可抑制成功通知并忽略目标字段;完成状态会改为记录日志。非正常结果仍会产生失败事件。禁用通知不是工具限制:如果 agent 不得发送消息,请单独限制其工具。
<Accordion title="映射钩子 (POST /hooks/hooks.mappings 解析。第一个匹配的映射优先,先于预设。模板或受信任的本地 JS/TS 转换会将负载转换为 wake 或 agent 操作;返回 null 的转换会产生 HTTP 204,且不执行运行。参见 映射详情。
转换可以双向覆盖已配置的唤醒时序:对于唤醒操作,返回 `mode: "now"` 或 `mode: "next-heartbeat"`;对于 agent 操作,返回对应的 `wakeMode`。
持久映射钩子需要稳定的映射 `sessionKey` 或 `hooks.defaultSessionKey`。模板派生的键需要与请求键相同的调用方键选择加入和前缀策略。
`forEach: "<key>"` 会对顶层负载数组进行扇出。每个项看到的是一个单元素数组,因此 Gmail 预设中的 `messages[0]` 表示当前邮件。Agent 扇出准入在最多约 8 秒的分发等待后给出答复;待处理项会在后台继续,部分批次返回非 2xx。重试同一批次会复用待处理或已准入的 agent 项,同时有界的内存重放缓存会保留它们。这不是持久化的恰好一次投递;映射的唤醒操作没有重放身份,队列可能会合并重复的唤醒。参考文档涵盖批次上限和响应形状。
验证并排查钩子请求¶
| 观察 | 检查或下一步操作 |
|---|---|
401 |
检查钩子令牌,而不是 Gateway 身份验证;确保代理转发身份验证头。 |
404 |
检查 hooks.enabled、hooks.path,以及自定义路径是否匹配某个映射。 |
400 |
阅读响应错误:JSON、agent 选择、会话策略或投递坐标可能无效。重试前请更正请求。 |
405、408 或 413 |
使用 POST;及时发送请求体;保持在文档规定的请求体限制内。 |
429 |
重复的身份验证失败已被限流。更正令牌并遵守 Retry-After。 |
409 |
重试前请解决目标会话冲突。 |
502 或 503 |
检查 Gateway 日志中的准备、容量或重启/暂停失败。单次运行准入超时会取消排队的工作;扇出待处理工作仍可能开始。 |
200,但没有聊天消息 |
先检查完成日志。deliver: false 会故意抑制成功通知;直接投递需要同时提供 channel 和 to。HTTP 准入不能证明投递。 |
204 |
映射故意未产生任何操作,例如 null 转换或空的扇出数组。 |
| 观察 | 检查或下一步操作 |
|---|---|
对于已启用投递的请求,请同时验证在目标渠道、账户和接收方处是否收到。检查终端警告中的 deliveryError,包括
status=ok 时。仅凭 delivered: false 不能证明失败,
deliveryAttempted: true 也不能证明已收到。显式抑制和
消息工具投递可能已满足运行器的投递处理;
缺失的投递标志仍表示未知。
对于重试的智能体请求,请复用 Idempotency-Key 和相同负载。
参考 说明了其
作用范围和生命周期。新测试请使用新密钥;重放的 200 不会再次运行
智能体。
Warning
将端点保留在回环、tailnet 或受信任的反向代理之后。远程调用请使用 HTTPS, 并仅暴露所需路径。
- 使用专用的 hook 令牌和专用子路径;
/会被拒绝。 - 限制
hooks.allowedAgentIds,包括生效的默认智能体路径。 - 除非必要,请保持
hooks.allowRequestSessionKey: false;启用时,限制hooks.allowedSessionKeyPrefixes。 - 将外部事件内容视为数据。智能体 hook 内容默认会进行安全包装,但包装不会移除工具或工作区访问权限。对不可信输入请使用受限智能体,并保持不安全内容覆盖处于禁用状态。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw