Gmail PubSub - Gmail 邮件事件订阅

Gmail PubSub 集成允许 OpenClaw 通过 Google Cloud Pub/Sub（谷歌云发布/订阅服务）实时接收 Gmail 邮件变更通知，无需轮询即可在邮件到达的第一时间触发 Agent（智能体）处理。

工作原理

┌───────┐  新邮件  ┌──────────────┐  推送消息  ┌─────────┐  Webhook  ┌──────────┐
│ Gmail │ ──────> │ Google Cloud │ ────────> │ OpenClaw│ ────────> │  Agent   │
│       │         │   Pub/Sub    │           │ Gateway │           │  处理邮件 │
└───────┘         └──────────────┘           └─────────┘          └──────────┘

实时性

相比 Polls（轮询）方式每隔数分钟检查一次，PubSub 推送模式可在邮件到达后 秒级 通知 OpenClaw，显著提升响应速度。

前置条件

1. Google Cloud Platform (GCP) 账号及项目
2. 启用 Gmail API 和 Pub/Sub API
3. OAuth 2.0 Client（OAuth 2.0 客户端）凭据
4. OpenClaw Gateway 拥有公网可访问的 HTTPS 端点

配置步骤

Step 1: 创建 GCP 项目并启用 API

# 安装 gcloud CLI
# 创建项目
gcloud projects create openclaw-mail --name "OpenClaw Mail"
gcloud config set project openclaw-mail

# 启用所需 API
gcloud services enable gmail.googleapis.com
gcloud services enable pubsub.googleapis.com

Step 2: 创建 Pub/Sub Topic 和 Subscription

# 创建 Topic
gcloud pubsub topics create gmail-notifications

# 授权 Gmail 向该 Topic 发布消息
gcloud pubsub topics add-iam-policy-binding gmail-notifications \
  --member="serviceAccount:gmail-api-push@system.gserviceaccount.com" \
  --role="roles/pubsub.publisher"

# 创建 Push Subscription，指向 OpenClaw 的 Webhook 端点
gcloud pubsub subscriptions create gmail-sub \
  --topic=gmail-notifications \
  --push-endpoint="https://your-gateway.com/hooks/gmail-pubsub" \
  --ack-deadline=60

Step 3: 配置 OAuth 凭据

在 GCP Console 中创建 OAuth 2.0 凭据，下载 credentials.json。

# 将凭据放到 OpenClaw 配置目录
cp credentials.json ~/.openclaw/gmail/credentials.json

Step 4: 设置 Gmail Watch

通过 Gmail API 注册 Watch（邮件监控）：

# 使用 OpenClaw CLI 设置
openclaw gmail watch \
  --credentials ~/.openclaw/gmail/credentials.json \
  --topic "projects/openclaw-mail/topics/gmail-notifications" \
  --labels "INBOX"

Watch 过期

Gmail Watch 每 7 天 自动过期。OpenClaw 会在后台自动续期，但请确保 OAuth Token 持续有效。

Step 5: 在 OpenClaw 中配置集成

{
  "integrations": {
    "gmail-pubsub": {
      "enabled": true,
      "credentials": "~/.openclaw/gmail/credentials.json",
      "topic": "projects/openclaw-mail/topics/gmail-notifications",
      "watchLabels": ["INBOX"],
      "autoRenew": true,
      "handler": {
        "session": "isolated",
        "message": "收到新邮件，请处理：\n发件人: {from}\n主题: {subject}\n摘要: {snippet}",
        "delivery": "announce"
      },
      "filters": {
        "excludeSenders": ["noreply@", "no-reply@"],
        "includeLabels": ["INBOX"],
        "hasAttachment": false
      }
    }
  }
}

邮件处理工作流

收到通知后，Agent 可执行以下操作：

自动分类与标记

{
  "handler": {
    "message": "分析邮件内容，自动分类为：工作/个人/推广/重要，并打标签"
  }
}

自动提取附件

{
  "handler": {
    "message": "检查邮件附件，如果是发票/合同，提取关键信息保存到数据库"
  }
}

自动回复

{
  "handler": {
    "message": "如果是客户询价邮件，根据产品目录生成报价回复草稿"
  }
}

典型应用场景

场景	说明
发票自动处理	识别发票附件，OCR 提取信息，录入财务系统
客户邮件自动回复	分析来意，自动生成回复草稿
简历自动筛选	提取简历附件，匹配岗位要求，打分排序
订单确认通知	解析订单确认邮件，更新内部系统状态
告警邮件处理	识别服务告警邮件，自动触发运维操作

调试与监控

# 查看 Gmail 集成状态
openclaw gmail status

# 查看最近收到的通知
openclaw gmail notifications --limit 10

# 手动触发 Watch 续期
openclaw gmail renew

# 测试推送通道
openclaw gmail test-push

错误处理

错误	原因	解决方案
UNAUTHENTICATED	OAuth Token 过期	重新运行 openclaw gmail auth
NOT_FOUND	Topic 不存在	检查 GCP 项目和 Topic 名称
PERMISSION_DENIED	权限不足	检查 IAM Policy Binding
DEADLINE_EXCEEDED	消息确认超时	增大 ack-deadline

🇨🇳 中国用户须知

• Gmail 在中国大陆无法直接访问，需要通过代理或 VPN 连接。如果 Gateway 部署在国内，推荐以下替代方案：
  • 腾讯企业邮箱：支持 IMAP，可使用 Polls 方式替代
  • 阿里企业邮箱：支持 IMAP 和 Webhook 回调
  • Microsoft 365 / Outlook：支持 Graph API + Webhooks，国内可访问
• 如果必须使用 Gmail，建议将 Gateway 部署在海外服务器（如 AWS 东京、GCP 香港），通过内网 Webhook 回调国内服务
• GCP 相关命令执行也需要可访问 Google 服务的网络环境