跳转至

配置 — 钩子

hooks.* 下的入站 hook 键。

完整的键索引和其他顶级配置域,请参阅配置参考。

Hooks

hooks.* 配置通用的 Gateway HTTP 入站入口。有关设置和经过验证的第一个请求,请参阅Webhooks。这与内部 hooks(hooks.internal、HOOK.md)是分开的。

{
  hooks: {
    enabled: true,
    token: "<long-random-hook-token>",
    path: "/hooks",
    allowedAgentIds: ["main"],
    allowRequestSessionKey: false,
  },
}

将 main 替换为预期配置的代理。Hook 令牌授予的是入站访问权限,而非经过身份验证的发送方身份;应将负载内容视为不可信数据,并单独限制目标代理的工具和工作区。

字段 默认值 约定
enabled false 启用 HTTP 端点。需要非空的 token。
token 未设置 共享的 hook 密钥字符串。请使用专用的长随机值;此处不支持 SecretRef 对象。
path /hooks 专用基础路径;会自动添加开头斜杠并移除末尾斜杠。拒绝 /。
allowedAgentIds 不受限制 有效的代理允许列表,包括默认代理路径。省略或包含 "*" 时允许全部;[] 表示全部拒绝。
defaultSessionKey 未设置 当未提供请求/映射键时的逻辑代理运行键;否则会生成新的 hook:<uuid>。本身不会启用持久会话。
allowRequestSessionKey false 允许来自 /agent、/wake 以及从负载派生的映射/转换值的键。
allowedSessionKeyPrefixes 不受限制 用于显式请求/映射键以及默认/生成的键的不区分大小写前缀。空列表或全为空白项的列表不施加任何限制;否则空白项会被忽略。请参阅下方的会话策略。
presets [] 内建映射会追加在自定义映射之后。可用预设:"gmail";未知名称不会添加任何映射。
mappings [] 有序映射列表;首个匹配生效。请参阅映射详情。
transformsDir <config-dir>/hooks/transforms 转换目录,限制在该根目录内,包括符号链接的包含关系。通常为 ~/.openclaw/hooks/transforms。
gmail 未设置 Gmail 传输和处理默认设置;请参阅Gmail 集成。
internal 独立子系统 内部事件 hook 配置;请参阅Hooks。它不会启用 HTTP 入站。

hooks.token 应区别于当前使用的 Gateway 共享密钥认证(gateway.auth.token / OPENCLAW_GATEWAY_TOKEN 或 gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD)。启动时对重用会记录非致命警告;openclaw security audit 会报告严重发现,包括在审计时提供的密码认证(--auth password --password <password>)。使用 openclaw doctor --fix 轮换已持久化的、被重用的 hook 令牌,然后更新所有外部发送方。

Hook HTTP contract

以下路径假定 hooks.path: "/hooks";如果配置不同,请替换该前缀。发送 POST,附带 JSON 请求体及 Content-Type: application/json。

身份验证接受 Authorization: Bearer <token> 或 x-openclaw-token。非空的 Bearer 令牌优先。token 查询参数会被拒绝并返回 400,即使同时存在有效标头也是如此。缺失或错误的凭据返回 401。在 60 秒窗口内失败 20 次后,来自该客户端的进一步无效身份验证尝试将受到 429 和 Retry-After 限流;有效身份验证会重置计数器。回环地址并不豁免。在暴露代理路由之前,请正确配置受信任的代理归属。

普通请求体限制为 256 KiB,并带有 30 秒的请求体读取超时。Gmail 路径映射会获得下面描述的更大的派生限额。通用 hook 会解析 JSON,但不要求 JSON Content-Type 标头。

端点 载荷与结果
POST /hooks/wake 必填非空 text;可选 mode(默认 "now" 或 "next-heartbeat")、agentId、sessionKey。返回 200 { ok: true, mode, eventOutcome };当队列接受 wake 时,eventOutcome 为 "queued";当同一 wake 已经是队列中最近的待处理事件时,为 "coalesced"。now 允许普通会话事件;该结果并不证明执行或投递已完成。
POST /hooks/agent agent 载荷。默认在会话/全局放置准入后返回 200 { ok: true, runId }。当 waitForCompletion: true 时,等待已准入的运行,并在 completion 中添加有界的最终执行/投递事实。
POST /hooks/<name> 第一个匹配的映射会生成 wake/agent 操作。没有匹配的映射返回 404;没有操作返回 204。agent 扇出具有批量响应契约。

直接的 /wake 和 /agent 端点优先于具有这些名称的映射。/hooks 本身没有操作。

状态 含义
400 JSON、载荷、路由/会话策略或投递/账户选择无效。重试前请阅读 error。
401 Hook 身份验证失败。
404 该路径没有 hook 操作或映射。已禁用的 hook 会回落到 Gateway 路由的其余部分。
405 方法错误;返回 Allow: POST。
408 请求体超时。
413 请求体超过该路径的字节限制。
429 身份验证失败限流;请遵循 Retry-After。
409 agent 准入被拒绝,因为目标会话已更改或无法接受工作。
500 映射/转换异常(hook mapping failed);请检查 Gateway 日志。
502 agent 在准入前准备失败。
503 单次运行未在 15 秒内完成准入;该排队工作会被取消。扇出待处理工作不同:它会在后台继续。Gateway 暂停/重启也可能返回 503 gateway_unavailable。

agent 准入失败使用 { ok: false, error, runId? }。早期的方法/身份验证/路径失败可能是纯文本;不要假设每个错误响应都是 JSON。15 秒准入截止时间与 agent 回合的请求体读取超时和 timeoutSeconds 是分开的。HTTP 成功并不证明模型结果或通道投递。参见 hook 验证。

Hook agent 载荷

| 字段 | 默认值 | 契约 |

字段 默认值 约定
------------------- ------------------------ ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
message 必填 非空的代理输入文本;外部内容会被安全包装。
name "Hook" 用于日志/完成事件中的 Hook 标签。
agentId 解析出的所有者 直接提供时必须指定一个已配置的代理。当无法解析隐式/保留的所有者时必填。
sessionKey 默认/生成的密钥 受调用方密钥选择加入和前缀策略约束。
sessionMode "isolated" "isolated" 创建新的运行会话;"persistent" 复用已解析的会话。
idempotencyKey 未设置 可选的重放密钥;请求头优先。见下文的重试。
waitForCompletion false 仅限直接 /agent。当为 true 时,在准入后保持 HTTP 响应打开,并返回带有 status 和可用投递事实的 completion。映射和扇出仍仅限准入。
wakeMode "now" "now" 或 "next-heartbeat";控制完成事件的唤醒,而不是代理是否立即调度。
deliver true 仅 false 表示退出。没有直接目的地时,成功输出可成为主会话完成事件。false 会记录成功完成而不发送通知,并忽略目的地字段。非正常执行结果会产生状态事件。
channel 直接投递无 已注册的具体渠道 id;必须与 to 配对。直接 /agent 不能使用 "last"。
to 未设置 直接通知投递的非空接收者,与 channel 配对。
accountId 渠道默认 选择一个已配置且已启用的账户;需要 channel 和 to。未知、已禁用或无效的选择会在分发前返回 400。
model 代理/模型默认值 模型 id 或别名覆盖,受模型可用性和允许列表策略约束。
thinking 代理/模型默认值 本次运行的思考覆盖。
timeoutSeconds 代理超时 正数的回合超时覆盖;直接负载值会向下取整到整秒。无效或非正值会被忽略。

省略所有目的地字段时,运行将没有直接通知目的地。 在投递启用时,仅提供目的地的一部分会以 400 失败。 deliver: false 禁用通知,而不是禁用代理使用消息工具的能力;必要时在代理策略中限制这些工具。

Hook 会话与代理策略

直接请求的代理 id 必须存在。映射代理 id 会解析为已配置的代理,对于未知映射 id 使用旧版默认代理回退。如果无法解析所有者,准入会失败,而不是虚构一个代理。有效代理必须通过 allowedAgentIds;全局会话存储所有权也会被强制。带代理前缀的密钥会重新限定到所选代理,并再次进行前缀检查。

对于固定的全局会话存储,省略的目标会优先使用其持久化的 agents.defaults.sessionStore.agentId 所有者,而不是运行时默认值。与该所有者冲突的显式目标会被拒绝。持久化的所有者仍必须通过 allowedAgentIds。

键的解析顺序为:请求/映射,然后 hooks.defaultSessionKey,最后为生成的 hook:<uuid>。已配置的默认值必须匹配前缀允许列表。如果没有默认值,允许列表必须接受生成的 hook: 键。

  • 直接 /agent 持久模式要求显式请求 sessionKey、allowRequestSessionKey: true,以及非空前缀允许列表。
  • 持久映射要求稳定的映射 sessionKey 或 defaultSessionKey。静态映射键不需要调用方键选择加入,但仍须遵守已配置的前缀。
  • 模板化映射键要求在配置解析时具有非空前缀允许列表,并在分发时具有 allowRequestSessionKey: true。这包括内置 Gmail 预设,除非更早的映射覆盖它。
  • /wake 仅在 mode: "now" 且遵循相同的调用方键/前缀策略时接受显式键。如果没有显式键,它会使用所选 agent 的主会话;defaultSessionKey 用于 agent 运行,而不是 wake。

逻辑 hook 键并不总是存储的会话键。隔离运行即使 hook 键稳定,也会使用新的自动化运行会话。持久性控制会话复用,而不是工具权限或沙箱。共享同一规范逻辑键的请求会被串行化直至完成,即使在隔离模式下也是如此。因此,固定的 defaultSessionKey 会排序这些请求,但可能导致后续单个请求在先前运行仍活跃时触发准入超时。

映射详情

自定义 mappings 按数组顺序在 presets 之前运行。第一个匹配项拥有该请求,包括返回 null 的 transform;后续映射不会被尝试。当提供两个匹配谓词时,它们都必须通过。省略它们会匹配任何自定义 hook 路径。

映射字段 默认值 约定
id mapping-<index> 已准入 agent 操作的有界入口源归因,不是经过身份验证的主体或调用者。
match.path 任意自定义路径 hooks.path 之后的子路径,去除前导/尾随斜杠(gmail 匹配 /hooks/gmail)。
match.source 任意来源 与 payload 的字符串 source 字段进行精确匹配。
action "agent" "agent" 或 "wake"。
wakeMode "now" "now" 或 "next-heartbeat";对于 wake 操作,会成为 mode。
name "Hook" 在分发时 模板化 agent 运行标签。
agentId 已解析的所有者 静态目标 agent id;受有效 agent 允许列表约束。
sessionKey 默认/生成的键 静态或模板化逻辑键;参见会话策略。
sessionMode "isolated" 对于 agent 操作,为 "isolated" 或 "persistent"。
messageTemplate 空 agent 输入模板;最终操作必须具有非空 message。
textTemplate 空 wake 文本模板;最终操作必须具有非空 text。请使用受信任的通知文本,而不是原始不可信内容。
forEach 未设置 顶层 payload 数组键;每个条目一个操作,上限 200 个条目。嵌套/原型路径会被拒绝。
deliver true agent 公告策略。与直接 /agent 不同,映射交付可以使用 "last",或将部分目标延迟到自动化交付解析器。
channel "last" 已注册的 channel id 或 "last"。映射不暴露 accountId。
to 未设置 模板化交付目标。优先使用显式 channel 和 to。
model agent/model 默认值 模板化 model 覆盖。
thinking agent/model 默认值 模板化 thinking 覆盖。
timeoutSeconds agent 超时 正整数回合超时。
映射字段 默认值 契约
allowUnsafeExternalContent false 危险:为此映射禁用代理外部内容包装。Gmail 的全局不安全标志也可能禁用包装。
transform.module 未设置 位于 transformsDir 下的安全相对 JS/TS 模块;绝对路径、路径穿越、URL/驱动器形式以及符号链接逃逸均会被拒绝。
transform.export default,然后 transform 命名函数导出;显式命名的导出必须存在。

模板支持 {{payload.field}} 或 {{field}},数组索引,例如 {{messages[0].subject}}、{{headers.x-event-type}}、{{query.kind}}、{{path}}, 以及 {{now}}(ISO 时间戳)。缺失/空值会变成空字符串;对象 序列化为 JSON。空的渲染后会话密钥模板会被拒绝。

转换接收 { payload, headers, url, path },可以返回部分操作覆盖, 必要时可异步返回。操作输出使用 kind: "agent" 或 "wake",分别对应 message 或 text。返回 null 会跳过该操作; 当没有剩余操作时,响应为 204,此时尚未创建任何运行、任务、执行 标识或审计回执。转换异常返回 500。

转换提供的 sessionKey 默认被视为外部派生。只有生成固定密钥的可信 代码才应标记 sessionKeySource: "static";切勿使用该标记来绕过针对负载派生密钥的策略。转换作为可信 Gateway 代码执行,而不是在读取代理的沙箱中执行。它们会被缓存,直到钩子配置重新加载。请将模块保留在钩子转换根目录下,而不是工作区技能目录中;如果 doctor 报告了无效模块,请将它们移动到该位置,或移除无效的 transformsDir。

钩子重试与扇出

代理重放密钥按以下顺序解析:Idempotency-Key、 X-OpenClaw-Idempotency-Key,然后是负载中的 idempotencyKey。仅使用修剪后非空 且最多 256 个字符的字符串。同一密钥仅在同一令牌、路径和已解析的调度字段下重放;更改消息或路由 可能会创建新的运行。待处理准入以及完成未解决的已准入运行会保留,没有 TTL 或大小驱逐。终端完成稳定后,其重放条目在 5 分钟后过期,并计入 1,000 个终端条目的内存上限。重启会清除所有重放状态。失败的准入仍可重试。直接重试可以更改 waitForCompletion,而不更改 调度标识:仅准入的调用方重放 runId,而等待的 调用方共享同一个完成承诺并重放其终端结果。

当请求时,completion.status 为 ok、error 或 skipped, replyDisposition 为 visible、silent 或 empty。此处置仅暴露 终端模型回复是否存在,从不暴露其文本。可选的 投递字段为 delivered、deliveryAttempted、deliveryError 和 deliverySuppressionReason(empty、silent、heartbeat 或 channel_transform)。缺失的投递字段保持未知。准入后的 失败仍返回 HTTP 200;只有准入失败使用上述非 2xx 状态。deliveryError 存在时,是固定的类别值 "delivery-failed"。提供商、运行时、模型、目标、会话、诊断、 输出和摘要详情从不返回。

对于 forEach,模板/转换会看到原始负载,其中选定的 数组被替换为 [currentItem]。缺失、空或非数组值不会产生任何 操作(204)。仅处理前 200 个项;多余项会被 丢弃并产生警告,而不是 HTTP 失败。请在发送方拆分更大的批次。

扇出代理调度最多等待 映射/转换工作完成后的 8 秒。 待处理准入会在后台继续,没有单次运行 15 秒的 取消期限。完全准入的多代理批次返回:

{
  "ok": true,
  "runId": "<first-hook-request-run-id>",
  "runIds": ["<hook-request-run-id-1>", "<hook-request-run-id-2>"],
  "dispatched": 2
}

已结算的单项批次保留 { ok: true, runId }。部分失败或 待处理项会返回非 2xx,并带有 ok: false、不完整批次的 error、已准入的 runIds,以及 errors 中最多五条失败消息。仅待处理的批次使用 503。因此,错误可能与已准入或仍待处理的工作共存。

代理扇出即使没有显式幂等密钥,也会从每个渲染后的操作派生重放标识。相同的重试会在缓存生命周期内协调待处理/已准入项;请保持转换在重试时具有确定性。唤醒操作会立即调度,并且没有重放标识,包括混合 唤醒/代理批次。如果任何唤醒被其队列接受,其响应会包含 eventOutcome: "queued";如果每个唤醒都被其队列合并,则包含 "coalesced"。 这不是持久化的恰好一次处理。

Gmail 集成

Gmail 预设通过 forEach: "messages" 和 sessionKey: "hook:gmail:{{messages[0].id}}" 路由 /hooks/gmail,默认使用隔离模式。自定义匹配映射会在预设之前运行。如果没有映射 agentId,预设会使用已解析的默认代理;会话隔离不会限制该代理的工具或工作区。

在连接不受信任的邮件之前,请应用 受限 Gmail 读取器配置。设置命令配置的是传输,而不是读取器或会话密钥策略。对于模板化密钥,请设置 allowRequestSessionKey: true 和 allowedSessionKeyPrefixes: ["hook:gmail:"],并设置匹配的 defaultSessionKey,或允许更广泛的 "hook:" 命名空间。 若要禁用调用方密钥覆盖,请使用静态 sessionKey 的更早映射替换预设。除非有意复用上下文,否则请保持隔离模式。

{
  hooks: {
    gmail: {
      account: "reader@example.com",
      topic: "projects/<project-id>/topics/gog-gmail-watch",
      subscription: "gog-gmail-watch-push",
      pushToken: "<separate-random-push-token>",
      hookUrl: "http://127.0.0.1:18789/hooks/gmail",
      includeBody: true,
      maxBytes: 20000,
      renewEveryMinutes: 720,
      serve: { bind: "127.0.0.1", port: 8788, path: "/" },
      tailscale: { mode: "funnel", path: "/gmail-pubsub" },
      model: "openai/gpt-6-astra",
      thinking: "high",
    },
  },
}

这是传输配置块,不是完整的 reader 设置。模型仅为示例,且必须对 reader 可用。Gmail 字段:

hooks.gmail 字段 运行时默认值 约定
account 必需 已在 gog 中授权的 Gmail 账户。
label "INBOX" 要监视的 Gmail 标签。启动 watcher 时,OpenClaw 会排除 SPAM、TRASH、DRAFT 和 SENT。
topic 必需 完整的 Pub/Sub 主题路径。Setup 可以创建 gog-gmail-watch 主题。
subscription "gog-gmail-watch-push" Setup 使用的 Pub/Sub 订阅。
pushToken 必需 用于验证发往 watcher 的入站推送。与 hooks.token 不同,后者用于验证转发到 OpenClaw。如果缺失,Setup 会生成一个。
hookUrl 本地 Gateway /hooks/gmail 除非已配置,否则由 hooks.path 和 Gateway 端口构建的转发 URL。
includeBody true 包含邮件正文片段。在配置中设置为 false 可省略它们。
maxBytes 20000 传递给 watcher 的每条消息正文上限,为正整数。也用于推导 Gmail HTTP 正文允许大小。
renewEveryMinutes 720 监视续订间隔,为正整数。
serve.bind "127.0.0.1" Watcher 绑定主机。
serve.port 8788 Watcher 端口,为正整数。
serve.path "/gmail-pubsub" Watcher 路径。启用 Tailscale 且没有显式 target 时,由于暴露的前缀会被剥离,它会变为 /。
tailscale.mode "off" "off"、"serve" 或 "funnel"。Setup 默认为 "funnel";没有已保存配置的运行时默认为 "off"。
tailscale.path 解析后的 serve 路径 暴露的 Tailscale 路径,在 Setup 中通常为 /gmail-pubsub。
tailscale.target 本地 watcher 可选的端口、host:port 或 URL target。显式 target 会保留已配置的 serve 路径。
model agent/model 默认值 Gmail 模型默认值;显式映射模型会覆盖它。不允许的 Gmail 默认值会被忽略,而无效的显式运行覆盖会导致准备失败。
thinking agent/model 默认值 "off"、"minimal"、"low"、"medium" 或 "high";显式映射 thinking 优先。
allowUnsafeExternalContent false 危险:为 Gmail agent 轮次禁用邮件安全包装。对于不受信任的收件箱,请保持关闭。

Gmail 路径映射使用请求正文允许大小 max(256 KiB, min(32 MiB, 100 × (3 × maxBytes + 8192)))。该倍数用于为转义内容和消息元数据预留空间;它不保证所有上游积压都能容纳。上游历史页大小按历史记录计数,而一条历史记录可能包含多条消息。Fan-out 仍然只处理前 200 项,并记录被丢弃的多余项。参见 批量限制和重试。

当 hooks.enabled: true 且设置了 hooks.gmail.account 时,如果其可执行文件和必需的传输配置可用,Gateway 会启动 gog gmail watch serve 并续订监视。设置 OPENCLAW_SKIP_GMAIL_WATCHER=1 可退出。不要在同一监听器上启动第二个前台 watcher。Setup 输出可能包含 token;参见 CLI 参考。

成功的 push 或 hook 响应只是传输/准入证据,并非邮件处理或投递完成的证明。请通过日志及其运行输出验证受限 reader。对于 reader 到 agent 的交接,仅暴露所需的工具,并使用 allow 约束默认开启的 tools.agentToAgent 策略;如果不需要交接,请设置 enabled: false;另请参阅 Prompt injection 和 每个 agent 的沙箱与工具。


本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw