Gmail Pub/Sub -> OpenClaw

目标：Gmail watch -> Pub/Sub 推送 -> gog gmail watch serve -> OpenClaw webhook。

前置条件

• 已安装并登录 gcloud（安装指南）。
• 已安装 gog (gogcli) 并为 Gmail 账户授权（gogcli.sh）。
• 已启用 OpenClaw hooks（参见 Webhooks）。
• 已登录 tailscale（tailscale.com）。

支持的设置使用 Tailscale Funnel 作为公共 HTTPS 端点。其他隧道服务也可以使用，但需要自行配置/不受支持。

快速配置

示例 hook 配置（启用 Gmail 预设映射）：

{
  "hooks": {
    "enabled": true,
    "token": "OPENCLAW_HOOK_TOKEN",
    "path": "/hooks",
    "presets": ["gmail"]
  }
}

要将 Gmail 摘要投递到聊天界面，请用设置了 deliver 以及可选的 channel/to 的映射覆盖预设：

{
  "hooks": {
    "enabled": true,
    "token": "OPENCLAW_HOOK_TOKEN",
    "presets": ["gmail"],
    "mappings": [
      {
        "match": { "path": "gmail" },
        "action": "agent",
        "wakeMode": "now",
        "name": "Gmail",
        "sessionKey": "hook:gmail:{{messages[0].id}}",
        "messageTemplate": "New email from {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}\n{{messages[0].body}}",
        "model": "openai/gpt-5.2-mini",
        "deliver": true,
        "channel": "last"
      }
    ]
  }
}

如果你想使用固定渠道，请设置 channel + to。否则 channel: "last" 会使用上次的投递路由。

模型配置

要专门为 Gmail hooks 设置默认模型和思考级别，请在配置中添加 hooks.gmail.model / hooks.gmail.thinking：

{
  "hooks": {
    "gmail": {
      "model": "openrouter/meta-llama/llama-3.3-70b-instruct:free",
      "thinking": "off"
    }
  }
}

注意事项：

• 映射中的每个 hook 的 model/thinking 会覆盖这些默认值。
• 回退顺序：hooks.gmail.model → agents.defaults.model.fallbacks → 主模型。
• Gmail hook 内容默认使用外部内容安全边界包装。要禁用（危险），请设置 hooks.gmail.allowUnsafeExternalContent: true。

向导（推荐）

使用 OpenClaw 助手将所有内容接入在一起：

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

默认设置：

• 使用 Tailscale Funnel 作为公共推送端点。
• 为 openclaw webhooks gmail run 写入 hooks.gmail 配置。
• 启用 Gmail hook 预设（hooks.presets: ["gmail"]）。

Gateway 网关自动启动（推荐）

• 当 hooks.enabled=true 且设置了 hooks.gmail.account 时，Gateway 网关会在启动时运行 gog gmail watch serve 并自动续期 watch。
• 设置 OPENCLAW_SKIP_GMAIL_WATCHER=1 可退出。

手动守护进程：

openclaw webhooks gmail run

一次性设置

1. 选择拥有 gog 使用的 OAuth 客户端的 GCP 项目。

gcloud auth login
gcloud config set project <project-id>

2. 启用 API：

gcloud services enable gmail.googleapis.com pubsub.googleapis.com

3. 创建主题：

gcloud pubsub topics create gog-gmail-watch

4. 允许 Gmail push 发布：

gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \
  --member=serviceAccount:gmail-api-push@system.gserviceaccount.com \
  --role=roles/pubsub.publisher

启动 watch

gog gmail watch start \
  --account openclaw@gmail.com \
  --label INBOX \
  --topic projects/<project-id>/topics/gog-gmail-watch

运行推送处理程序

本地示例：

gog gmail watch serve \
  --account openclaw@gmail.com \
  --bind 127.0.0.1 \
  --port 8788 \
  --path /gmail-pubsub \
  --token <shared> \
  --hook-url http://127.0.0.1:18789/hooks/gmail \
  --hook-token OPENCLAW_HOOK_TOKEN \
  --include-body \
  --max-bytes 20000

推荐：openclaw webhooks gmail run 封装了相同的流程并自动续期 watch。

故障排除

• Invalid topicName：项目不匹配（主题不在 OAuth 客户端项目中）。
• User not authorized：主题缺少 roles/pubsub.publisher。
• 空消息：Gmail push 仅提供 historyId；通过 gog gmail history 获取。

测试

向被监视的收件箱发送一条消息：

gog gmail send \
  --account openclaw@gmail.com \
  --to openclaw@gmail.com \
  --subject "watch test" \
  --body "ping"

检查 watch 状态和历史记录：

gog gmail watch status --account openclaw@gmail.com
gog gmail history --account openclaw@gmail.com --since <historyId>

清理

gog gmail watch stop --account openclaw@gmail.com
gcloud pubsub subscriptions delete gog-gmail-watch-push
gcloud pubsub topics delete gog-gmail-watch