webhooks-gmail

name	webhooks-gmail
description	Webhook 端点管理与 Gmail Pub/Sub 集成：列出、测试 Webhook 端点，配置和运行 Gmail 推送订阅。当需要管理 Webhook 端点或配置 Gmail 自动化集成时使用此技能。
tools	gateway
metadata	{"category":"operations","emoji":"📬","tree_id":"system/gateway","tree_group":"system","min_tier":"task_write","intent_priority":15,"intent_keywords":{"zh":["webhook管理","Gmail集成","Gmail推送","Pub/Sub","webhook端点","Gmail自动化","Gmail订阅","邮件推送","测试webhook"],"en":["webhook management","gmail integration","gmail pubsub","webhook endpoint","gmail automation","test webhook"]},"scene_hint":"管理Webhook端点和Gmail Pub/Sub用此→通用Webhook规则用hooks-automation→邮件发送/回复工作流用email-automation"}

Webhook 与 Gmail 集成技能

适用场景

用户需要管理 Webhook 端点或配置 Gmail Pub/Sub 集成时触发。

与 hooks-automation 的区别

技能	覆盖范围
hooks-automation	/hooks/agent 触发逻辑、hooks.mappings 映射规则
本技能	Webhook 端点列表/测试 + Gmail Pub/Sub 集成配置

两者互补：hooks-automation 定义"事件来了做什么"，本技能管理"端点本身"和"Gmail 特化集成"。

一、列出 Webhook 端点

crabclaw webhooks list

返回当前配置的所有 Webhook 端点：

• 端点 URL
• 绑定的事件类型
• 认证方式
• 最后触发时间

二、测试 Webhook 端点

crabclaw webhooks test [--url <webhook-url>]

发送测试请求到指定 Webhook 端点，验证：

• 网络连通性
• 认证有效性
• 响应格式正确性

三、Gmail Pub/Sub 集成

3.1 配置 Gmail 推送

crabclaw webhooks gmail-setup <gmail-account>

交互式配置流程：

1. 验证 Gmail 账号权限
2. 创建 Google Cloud Pub/Sub Topic
3. 配置 Gmail Watch（推送通知）
4. 设置本地 Webhook 接收端点
5. 测试推送连通性

3.2 运行 Gmail 监听

crabclaw webhooks gmail-run

启动 Gmail Pub/Sub 监听进程，持续接收 Gmail 推送通知并转化为事件。

通常与 hooks.mappings 配合使用：

{
  "hooks": {
    "mappings": [
      {
        "match": {"source": "gmail"},
        "action": "agent",
        "messageTemplate": "收到来自 {{from}} 的邮件：{{subject}}"
      }
    ]
  }
}

3.3 Gmail 集成与 email 频道的关系

方式	触发类型	适用场景
Gmail Pub/Sub (本技能)	实时推送	需要即时响应新邮件
Email 频道 (IMAP 轮询)	定时拉取	常规邮件自动化
hooks-automation	事件触发 Agent	复杂工作流

四、前置依赖

Gmail Pub/Sub 前置条件

1. 有效的 Google Cloud 项目（含 Pub/Sub API）
2. Gmail API 授权（OAuth 或 Service Account）
3. Gateway 运行且可达（接收推送通知）
4. 公网可达地址或反向代理（Google 需要推送到公网 URL）

五、CLI 命令对照

CLI 命令	说明
crabclaw webhooks list	列出 Webhook 端点
crabclaw webhooks test	测试 Webhook 端点
crabclaw webhooks test --url <url>	测试指定端点
crabclaw webhooks gmail-setup <account>	配置 Gmail 推送
crabclaw webhooks gmail-run	启动 Gmail 监听