OpenClaw 科普系列(13):Webhooks & 触发器——让外部系统唤醒 Agent

前几期我们聊了 Cron 定时任务，让 Agent 能够按时主动执行。但还有一种场景：外部系统发生事件时，如何通知 Agent 做出响应？比如收到新邮件、GitHub 有新提交、或者 IoT 设备触发警报。

这就是 Webhooks（网络钩子） 的作用——让外部系统能够主动触发 Agent。

什么是 Webhook？

Webhook 是一种"反向 API"：不是客户端轮询服务器获取数据，而是服务器在事件发生时主动推送数据到客户端。

在 OpenClaw 中，Gateway 暴露 HTTP 端点，外部系统通过 POST 请求触发：

• • Wake 端点：轻量级唤醒，进入主会话心跳
• • Agent 端点：完整 Agent 执行，可指定模型、渠道、投递方式

启用 Webhooks

在 ~/.openclaw/openclaw.json 中配置：

{
  hooks: {
    enabled: true,
    token: "your-secret-token",    // 必需，用于验证请求
    path: "/hooks",                  // 端点路径，默认 /hooks
    allowedAgentIds: ["hooks", "main"],  // 允许的 Agent ID
  },
}

安全要求：

• • hooks.token 是必需的，且应该足够复杂
• • 建议配合反向代理或 Tailscale 使用，不要直接暴露到公网
• • 使用专用 Token，不要复用 Gateway 认证 Token

认证方式

每个请求必须包含 Token，推荐方式：

# 方式1：Authorization 头（推荐）
Authorization: Bearer <token>

# 方式2：自定义头
x-openclaw-token: <token>

注意：Query string 传 token 会被拒绝（返回 400）。

两个核心端点

1. POST /hooks/wake —— 轻量级唤醒

最简单的触发方式，适合通知类事件：

curl -X POST http://127.0.0.1:18789/hooks/wake \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "text": "新邮件收到",
    "mode": "now"
  }'

参数说明：

• • text（必需）：事件描述，会进入主会话的系统事件
• • mode（可选）：now（立即触发心跳，默认）或 next-heartbeat（等待下次心跳）

效果：

• • 在主会话中排队一个系统事件
• • 根据 mode 决定是否立即触发心跳
• • Agent 在下次心跳时处理该事件

2. POST /hooks/agent —— 完整 Agent 执行

更强大的触发方式，支持完整参数控制：

curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "总结收件箱",
    "name": "Email",
    "agentId": "hooks",
    "wakeMode": "now",
    "deliver": true,
    "channel": "telegram",
    "to": "1468218609",
    "model": "openai/gpt-5.2-mini",
    "thinking": "low",
    "timeoutSeconds": 120
  }'

参数说明：

效果：

• • 在隔离会话中运行 Agent（类似 Cron isolated）
• • 始终向主会话发送摘要
• • 根据 deliver 决定是否投递到指定渠道

会话 Key 策略

出于安全考虑，/hooks/agent 的 sessionKey 覆盖默认是禁用的。

推荐配置（固定会话 Key）：

{
  hooks: {
    enabled: true,
    token: "${OPENCLAW_HOOKS_TOKEN}",
    defaultSessionKey: "hook:ingress",      // 固定默认 Key
    allowRequestSessionKey: false,          // 禁止请求覆盖
    allowedSessionKeyPrefixes: ["hook:"],   // 限制 Key 前缀
  },
}

兼容配置（允许覆盖）：

{
  hooks: {
    allowRequestSessionKey: true,
    allowedSessionKeyPrefixes: ["hook:"],   // 强烈建议限制前缀
  },
}

自定义 Hook 映射

通过 hooks.mappings 可以创建自定义端点，将任意 payload 转换为 wake 或 agent 动作：

{
  hooks: {
    presets: ["gmail"],  // 启用内置 Gmail 预设
    mappings: [
      {
        match: { path: "github" },
        action: "agent",
        wakeMode: "now",
        name: "GitHub",
        messageTemplate: "GitHub 事件：{{event}}\n仓库：{{repository.name}}\n提交者：{{pusher.name}}",
        model: "openai/gpt-5.2-mini",
        deliver: true,
        channel: "telegram",
        to: "1468218609",
      },
    ],
  },
}

然后发送请求到 /hooks/github：

curl -X POST http://127.0.0.1:18789/hooks/github \
  -H 'Authorization: Bearer SECRET' \
  -d '{
    "event": "push",
    "repository": { "name": "my-project" },
    "pusher": { "name": "charles" }
  }'

映射选项：

• • match.source：根据 payload 内容路由
• • match.path：根据 URL 路径路由
• • messageTemplate：使用模板语法（如 {{field}}）转换 payload
• • transform.module：加载 JS/TS 模块进行自定义转换

实际应用场景

场景1：GitHub Webhook

当代码仓库有新提交时通知 Agent：

{
  hooks: {
    mappings: [
      {
        match: { path: "github" },
        action: "agent",
        name: "GitHub",
        messageTemplate: "新提交到 {{repository.name}}\n作者：{{pusher.name}}\n消息：{{head_commit.message}}\n请分析变更并总结",
        deliver: true,
        channel: "telegram",
        to: "1468218609",
      },
    ],
  },
}

在 GitHub 仓库设置 Webhook URL 为 https://your-domain/hooks/github，Content type 选 application/json。

场景2：IoT 设备警报

智能家居设备触发时通知 Agent：

curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'Authorization: Bearer SECRET' \
  -d '{
    "message": "门磁传感器触发：前门打开",
    "name": "Security",
    "deliver": true,
    "channel": "telegram",
    "to": "1468218609"
  }'

场景3：服务器监控警报

Prometheus/Grafana 触发 Webhook：

{
  hooks: {
    mappings: [
      {
        match: { path: "alert" },
        action: "agent",
        name: "Monitor",
        messageTemplate: "服务器警报：{{alerts[0].labels.alertname}}\n状态：{{status}}\n实例：{{alerts[0].labels.instance}}\n请检查并建议处理方案",
        model: "opus",
        thinking: "medium",
        deliver: true,
      },
    ],
  },
}

Gmail Pub/Sub 集成

OpenClaw 内置 Gmail 邮件触发支持，新邮件到达时自动唤醒 Agent：

快速配置

openclaw webhooks gmail setup --account your@gmail.com

这会：

1. 1. 安装依赖（gcloud, gogcli, tailscale）
2. 2. 配置 Gmail Pub/Sub
3. 3. 启用 hooks.presets: ["gmail"]
4. 4. 设置 Tailscale Funnel 公网端点

手动配置

{
  hooks: {
    enabled: true,
    token: "OPENCLAW_HOOK_TOKEN",
    presets: ["gmail"],
    gmail: {
      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
      thinking: "off",
    },
  },
}

自定义映射（投递到指定渠道）：

{
  hooks: {
    presets: ["gmail"],
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        name: "Gmail",
        sessionKey: "hook:gmail:{{messages[0].id}}",
        messageTemplate: "新邮件来自 {{messages[0].from}}\n主题：{{messages[0].subject}}\n{{messages[0].snippet}}",
        model: "openai/gpt-5.2-mini",
        deliver: true,
        channel: "telegram",
        to: "1468218609",
      },
    ],
  },
}

启动监听

# 自动方式（Gateway 启动时自动运行）
# 需配置 hooks.gmail.account

# 手动方式
openclaw webhooks gmail run

Lobster 工作流触发

对于复杂的多步骤工作流，可以结合 Lobster 使用：

curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'Authorization: Bearer SECRET' \
  -d '{
    "message": "运行 Lobster 工作流：email-triage",
    "name": "Workflow",
    "deliver": true
  }'

Agent 收到后会调用 Lobster 工具执行预定义的工作流，包含审批节点和可恢复执行。

响应状态码

安全最佳实践

1. 1. 使用强 Token：随机生成，长度至少 32 字符
2. 2. 限制访问：通过防火墙或 Tailscale 限制端点访问
3. 3. 专用 Agent：为 Hook 配置专用 Agent，限制工具权限
4. 4. 沙箱执行：启用 sandbox，限制 Hook 执行环境
5. 5. 限制 Session Key：使用 allowedSessionKeyPrefixes 限制 Key 范围
6. 6. 监控日志：避免在日志中记录敏感 payload
7. 7. 外部内容安全：Hook payload 默认包装安全边界，谨慎使用 allowUnsafeExternalContent

与 Cron 的配合

Webhooks 和 Cron 是互补的：

组合示例：

• • Webhook 接收新邮件通知
• • Cron 每小时汇总未处理邮件
• • 两者结合实现完整的邮件工作流

总结

Webhooks 让 OpenClaw 从"被动等待"变成"主动响应"：

• • 轻量唤醒：/hooks/wake 适合简单通知
• • 完整执行：/hooks/agent 支持模型、渠道、投递控制
• • 自定义映射：通过 hooks.mappings 适配任意外部系统
• • 内置集成：Gmail Pub/Sub 开箱即用
• • 安全可控：Token 认证、Session Key 限制、沙箱执行

配合 Cron 使用，你的 Agent 就能实现真正的 7×24 小时自动化——既会按时工作，也能实时响应。

下一期，我们将探讨 Nodes 节点系统——如何在多台设备上分布式运行 Agent。