Gmail PubSub

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 端点。其他隧道服务也可以工作，但需要自行手动配置。目前，Tailscale 是我们官方支持的。

示例 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: "来自 {{messages[0].from}} 的新邮件\n主题: {{messages[0].subject}}\n{{messages[0].snippet}}\n{{messages[0].body}}",
        model: "openai/gpt-5.2-mini",
        deliver: true,
        channel: "last",
        // to: "+15551234567"
      },
    ],
  },
}

如果你想要固定的频道，请设置 channel + to。否则 channel: "last" 将使用最后的投递路由 (回退到 WhatsApp)。

要强制 Gmail 运行使用更便宜的模型，请在映射中设置 model (provider/model 或别名)。如果你强制使用了 agents.defaults.models，请确保该模型在允许列表中。

要专门为 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 → 主要配置。
如果设置了 agents.defaults.models，Gmail 使用的模型必须在允许列表中。
默认情况下，Gmail hook 内容会被外部内容安全边界包裹。若要禁用（危险），请设置 hooks.gmail.allowUnsafeExternalContent: true。

若要进一步自定义负载处理，请添加 hooks.mappings 或在 hooks.transformsDir 下添加 JS/TS 转换模块 (见 Webhooks)。

向导 (推荐)

使用 OpenClaw 助手将一切连接在一起 (在 macOS 上通过 brew 安装依赖)：

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

默认行为：

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

路径说明：当启用 tailscale.mode 时，OpenClaw 会自动将 hooks.gmail.serve.path 设置为 /，并将公共路径保持在 hooks.gmail.tailscale.path (默认 /gmail-pubsub)，因为 Tailscale 在代理前会剥离设置的路径前缀。如果你需要后端接收带有前缀的路径，请将 hooks.gmail.tailscale.target (或 --tailscale-target) 设置为完整的 URL，如 http://127.0.0.1:8788/gmail-pubsub 并匹配 hooks.gmail.serve.path。

想要自定义端点？使用 --push-endpoint <url> 或 --tailscale off。

平台说明：在 macOS 上，向导通过 Homebrew 安装 gcloud, gogcli, 和 tailscale；在 Linux 上请先手动安装。

Gateway 自动启动 (推荐)：

当 hooks.enabled=true 且设置了 hooks.gmail.account 时，Gateway 会在启动时运行 gog gmail watch serve 并自动续订监听。
设置 OPENCLAW_SKIP_GMAIL_WATCHER=1 可取消此行为 (如果你想自己运行守护进程)。
请勿同时运行手动守护进程，否则会遇到 listen tcp 127.0.0.1:8788: bind: address already in use 错误。

手动运行守护进程 (启动 gog gmail watch serve + 自动续订)：

openclaw webhooks gmail run

一次性设置

选择拥有 gog 所用 OAuth 客户端的 GCP 项目。

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

注意：Gmail 监听要求 Pub/Sub 话题与 OAuth 客户端位于同一个项目中。

启用 API：

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

创建话题 (Topic)：

gcloud pubsub topics create gog-gmail-watch

允许 Gmail 推送进行发布：

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

保存输出中的 history_id (用于调试)。

运行推送处理器

本地示例 (使用共享令牌认证)：

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

说明：

--token 保护推送端点 (x-gog-token 或 ?token=)。
--hook-url 指向 OpenClaw 的 /hooks/gmail (已映射；隔离运行 + 摘要到主会话)。
--include-body 和 --max-bytes 控制发送到 OpenClaw 的正文摘要。

推荐：openclaw webhooks gmail run 封装了同样的流程并自动续订监听。

公开处理器 (高级，不支持)

如果你需要使用非 Tailscale 隧道，请手动连接并在推送订阅中使用公共 URL (不支持，无保护)：

cloudflared tunnel --url http://127.0.0.1:8788 --no-autoupdate

使用生成的 URL 作为推送端点：

gcloud pubsub subscriptions create gog-gmail-watch-push \
  --topic gog-gmail-watch \
  --push-endpoint "https://<public-url>/gmail-pubsub?token=<shared>"

生产环境：使用稳定的 HTTPS 端点并配置 Pub/Sub OIDC JWT，然后运行：

gog gmail watch serve --verify-oidc --oidc-email <svc@...>

测试

向受监听的收件箱发送一条消息：

gog gmail send \
  --account openclaw@gmail.com \
  --to openclaw@gmail.com \
  --subject "监听测试" \
  --body "ping"

检查监听状态和历史：

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

故障排除

Invalid topicName: 项目不匹配 (话题不在 OAuth 客户端所在的工程中)。
User not authorized: 话题上缺少 roles/pubsub.publisher 角色。
消息为空：Gmail 推送仅提供 historyId；需通过 gog gmail history 获取。

清理

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