Webhook

网关可以暴露一个小的 HTTP webhook 端点用于外部触发。

启用

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    // 可选：限制显式 `agentId` 路由到此允许列表。
    // 省略或包含 "*" 以允许任何代理。
    // 设置 [] 以拒绝所有显式 `agentId` 路由。
    allowedAgentIds: ["hooks", "main"],
  },
}

注意：

  • hooks.enabled=true 时需要 hooks.token。
  • hooks.path 默认为 /hooks。

认证

每个请求必须包含 hook 令牌。优先使用 headers：

  • Authorization: Bearer <token>（推荐）
  • x-openclaw-token: <token>
  • 查询字符串令牌被拒绝（?token=... 返回 400）。

端点

POST /hooks/wake

负载：

{ "text": "System line", "mode": "now" }
  • text 必需（字符串）：事件的描述（例如”收到新邮件”）。
  • mode 可选（now | next-heartbeat）：是否触发立即心跳（默认 now）或等待下一次定期检查。

效果：

  • 将系统事件加入主会话队列
  • 如果 mode=now，触发立即心跳

POST /hooks/agent

负载：

{
  "message": "Run this",
  "name": "Email",
  "agentId": "hooks",
  "sessionKey": "hook:email:msg-123",
  "wakeMode": "now",
  "deliver": true,
  "channel": "last",
  "to": "+15551234567",
  "model": "openai/gpt-5.2-mini",
  "thinking": "low",
  "timeoutSeconds": 120
}
  • message 必需（字符串）：供代理处理的提示或消息。
  • name 可选（字符串）：hook 的可读名称（例如”GitHub”），用作会话摘要中的前缀。
  • agentId 可选（字符串）：将此 hook 路由到特定代理。未知 ID 回退到默认代理。设置后，hook 使用已解析代理的工作区和配置。
  • sessionKey 可选（字符串）：用于标识代理会话的键。默认情况下，除非 hooks.allowRequestSessionKey=true，否则此字段被拒绝。
  • wakeMode 可选（now | next-heartbeat）：是否触发立即心跳（默认 now）或等待下一次定期检查。
  • deliver 可选（布尔值）：如果为 true，代理的响应将发送到消息频道。默认为 true。仅心跳确认的响应会自动跳过。
  • channel 可选（字符串）：消息投递的频道。选项包括：last、whatsapp、telegram、discord、slack、mattermost（插件）、signal、imessage、msteams。默认为 last。
  • to 可选（字符串）：频道的收件人标识符（例如 WhatsApp/Signal 的电话号码、Telegram 的聊天 ID、Discord/Slack/Mattermost（插件）的频道 ID、MS Teams 的会话 ID）。默认为主会话中的最后收件人。
  • model 可选（字符串）：模型覆盖（例如 anthropic/claude-3-5-sonnet 或别名）。如果在受限列表中，必须在允许的模型列表中。
  • thinking 可选（字符串）：思考级别覆盖（例如 low、medium、high）。
  • timeoutSeconds 可选（数字）：代理运行的最大持续时间（秒）。

效果：

  • 运行独立代理回合（自己的会话密钥）
  • 始终将摘要发布到主会话
  • 如果 wakeMode=now，触发立即心跳

会话密钥策略（破坏性更改）

/hooks/agent 负载的 sessionKey 覆盖默认禁用。

  • 推荐：设置固定的 hooks.defaultSessionKey 并保持请求覆盖关闭。
  • 可选：仅在需要时允许请求覆盖，并限制前缀。

推荐配置：

{
  hooks: {
    enabled: true,
    token: "${OPENCLAW_HOOKS_TOKEN}",
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: false,
    allowedSessionKeyPrefixes: ["hook:"],
  },
}

兼容配置（传统行为）：

{
  hooks: {
    enabled: true,
    token: "${OPENCLAW_HOOKS_TOKEN}",
    allowRequestSessionKey: true,
    allowedSessionKeyPrefixes: ["hook:"], // 强烈推荐
  },
}

POST /hooks/<name>（映射）

自定义 hook 名称通过 hooks.mappings 解析（见配置）。映射可以将任意负载转换为 wake 或 agent 操作，带有可选模板或代码转换。

映射选项（摘要）：

  • hooks.presets: ["gmail"] 启用内置 Gmail 映射。
  • hooks.mappings 允许您在配置中定义 match、action 和模板。
  • hooks.transformsDir + transform.module 加载 JS/TS 模块用于自定义逻辑。
    • hooks.transformsDir（如果设置）必须保持在 OpenClaw 配置目录下的转换根目录下（通常为 ~/.openclaw/hooks/transforms）。
    • transform.module 必须在有效的转换目录内解析（遍历/逃逸路径被拒绝）。
  • 使用 match.source 保持通用摄入端点（负载驱动路由）。
  • TS 转换需要 TS 加载器（例如 bun 或 tsx）或运行时预编译的 .js。
  • 在映射上设置 deliver: true + channel/to 以将回复路由到聊天界面（channel 默认为 last 并回退到 WhatsApp）。
  • agentId 将 hook 路由到特定代理；未知 ID 回退到默认代理。
  • hooks.allowedAgentIds 限制显式 agentId 路由。省略它（或包含 *）以允许任何代理。设置 [] 以拒绝显式 agentId 路由。
  • hooks.defaultSessionKey 在没有显式密钥时设置 hook 代理运行的默认会话。
  • hooks.allowRequestSessionKey 控制 /hooks/agent 负载是否可以设置 sessionKey（默认：false）。
  • hooks.allowedSessionKeyPrefixes 可选地限制来自请求负载和映射的显式 sessionKey 值。
  • allowUnsafeExternalContent: true 为该 hook 禁用外部内容安全包装（危险；仅用于受信任的内部来源）。
  • openclaw webhooks gmail setup 写入 hooks.gmail 配置用于 openclaw webhooks gmail run。 有关完整的 Gmail watch 流程，请参阅 Gmail Pub/Sub。

响应

  • /hooks/wake 返回 200
  • /hooks/agent 返回 202（异步运行已开始）
  • 认证失败返回 401
  • 同一客户端重复认证失败后返回 429（检查 Retry-After）
  • 无效负载返回 400
  • 负载过大返回 413

示例

curl -X POST http://127.0.0.1:18789/hooks/wake \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"text":"New email received","mode":"now"}'
curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'x-openclaw-token: SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Summarize inbox","name":"Email","wakeMode":"next-heartbeat"}'

使用不同的模型

在代理负载（或映射）中添加 model 以覆盖该运行的模型：

curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'x-openclaw-token: SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.2-mini"}'

如果您强制执行 agents.defaults.models，请确保覆盖模型包含在其中。

curl -X POST http://127.0.0.1:18789/hooks/gmail \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"source":"gmail","messages":[{"from":"Ada","subject":"Hello","snippet":"Hi"}]}'

安全

  • 将 hook 端点放在环回、尾网或受信任的反向代理后面。
  • 使用专用的 hook 令牌；不要重复使用网关认证令牌。
  • 重复认证失败按客户端地址进行速率限制，以减缓暴力破解尝试。
  • 如果使用多代理路由，请设置 hooks.allowedAgentIds 以限制显式 agentId 选择。
  • 除非需要调用者选择的会话，否则保持 hooks.allowRequestSessionKey=false。
  • 如果启用请求 sessionKey，请限制 hooks.allowedSessionKeyPrefixes（例如 ["hook:"]）。
  • 避免在 webhook 日志中包含敏感的原始负载。
  • Hook 负载被视为不受信任，默认使用安全边界包装。 如果必须为特定 hook 禁用此功能，请在该 hook 的映射中设置 allowUnsafeExternalContent: true（危险）。