OpenClaw Webhook 与 Hooks 配置：接收外部事件触发 AI 任务

2026-03-24 · 4 分钟进阶玩法

Hooks 是什么？

Hooks 是 OpenClaw 的 Webhook 接收系统。当外部服务（如 Gmail、GitHub、表单服务）发送 HTTP 请求到 OpenClaw 时，Hooks 会将事件转化为 AI 任务，触发助手自动处理。

启用 Hooks

{
  hooks: {
    enabled: true,
    path: "/hooks",
    token: "shared-secret"   // Webhook 验证令牌
  }
}

启用后，外部服务可以向 http://your-gateway:18789/hooks/<mapping-path> 发送请求。

配置 Webhook 映射

每个 Webhook 映射定义了：收到什么请求 → 触发什么动作 → 怎么处理。

Gmail 邮件处理示例

{
  hooks: {
    enabled: true,
    path: "/hooks",
    token: "shared-secret",
    presets: ["gmail"],
    mappings: [
      {
        id: "gmail-hook",
        match: { path: "gmail" },
        action: "agent",
        wakeMode: "now",
        name: "Gmail",
        sessionKey: "hook:gmail:",
        messageTemplate: "From: \nSubject: ",
        textTemplate: "",
        deliver: true,
        channel: "last",
        to: "+15555550123",
        thinking: "low",
        timeoutSeconds: 300,
        transform: {
          module: "gmail.js",
          export: "transformGmail"
        }
      }
    ]
  }
}

映射参数说明

match.path：匹配的 URL 路径（拼接在 hooks.path 后面）
action：触发的动作，agent 表示让 AI 助手处理
wakeMode：now 立即唤醒，还是排队等待
sessionKey：会话标识，支持模板变量
messageTemplate / textTemplate：将 Webhook 数据格式化为消息内容
deliver：是否将处理结果发送到频道
channel / to：结果发送目标
thinking：思考深度（off、low、high）
timeoutSeconds：处理超时时间
transform：自定义数据转换脚本

Gmail 集成配置

OpenClaw 内置了 Gmail 预设：

{
  hooks: {
    presets: ["gmail"],
    gmail: {
      account: "your@gmail.com",
      label: "INBOX",
      hookUrl: "http://127.0.0.1:18789/hooks/gmail",
      includeBody: true,
      maxBytes: 20000,
      renewEveryMinutes: 720
    }
  }
}

自定义转换脚本

在 transformsDir 目录中放置转换脚本，对 Webhook 数据进行预处理：

{
  hooks: {
    transformsDir: "~/.openclaw/hooks/transforms"
  }
}

注意事项

token 用于验证 Webhook 请求的合法性，务必设置
如果网关在内网运行，需要通过 Tailscale Funnel 或反向代理暴露 Hooks 端点
timeoutSeconds 建议设置合理的超时，避免长时间占用资源