配置 — 钩子
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