OpenClaw `openclaw webhooks` 实战：Gmail Pub/Sub 事件接入的完整指南-CSDN博客

OpenClaw `openclaw webhooks` 实战：Gmail Pub/Sub 事件接入的完整指南

【免费下载链接】openclaw The AI that really does things. Any OS. Any Platform. The lobster way. 🦞 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw

openclaw webhooks 是 OpenClaw 中负责 Gmail Pub/Sub 事件接入的 CLI 命令族：它通过 gog（gogcli）完成 Gmail 监听注册、Pub/Sub 主题/订阅创建，并把入站邮件事件转发到 Gateway 的 webhook 端点。读完本文，你可以独立完成一次性的接入配置（gmail setup）、在前台运行事件监听器（gmail run）进行调试，并理解每个标志的默认值、继承规则与底层进程生命周期行为。

命令定位与职责边界

openclaw webhooks 只做一件事：通过 gog（gogcli）建立并运行 Gmail Pub/Sub 传输链路。它不负责以下功能，遇到这些需求请转向对应文档：

内部 HOOK.md 钩子的注册与管理，见内置钩子；
任意 Gateway webhook 映射（cron 任务上的 webhook 目标），见 Webhook automation；
TaskFlow Webhooks 插件，见 TaskFlow Webhooks 插件。

子命令总览

openclaw webhooks gmail setup --account <email> [...]
openclaw webhooks gmail run   [--account <email>] [...]

子命令	说明
`gmail setup`	一次性向导：Gmail watch、Pub/Sub 主题/订阅、OpenClaw hook 投递的完整配置。
`gmail run`	前台运行 `gog gmail watch serve` 以及 watch 自动续期循环。

两个子命令在 CLI 层都注册在 Commander 根程序上（入口见 webhooks-cli.ts），解析逻辑分别由 parseGmailSetupOptions / parseGmailRunOptions 完成，再交给 gmail-ops.ts 中的 runGmailSetup / runGmailService 执行。

注意：Gateway 在启动时也会自动拉起 gog gmail watch serve——前提是 hooks.enabled=true 且 hooks.gmail.account 已配置（gmail setup 会写入这两项）。gmail run 提供的是一个前台 watcher，用于调试或在 Gateway watcher 被禁用的场景。不要对同一个监听端同时运行两个 watcher。自动启动的细节与 OPENCLAW_SKIP_GMAIL_WATCHER 退出开关见 Gmail Pub/Sub 集成。

从源码结构看，Gateway 的启动判定链非常直接：hooks 未启用时返回 hooks-disabled，未配置 hooks.gmail.account 时返回 no-gmail-account，设置了 OPENCLAW_SKIP_GMAIL_WATCHER 真值环境时返回 disabled-by-environment，否则调度 watcher（见 server-startup-outcomes.ts）。

`webhooks gmail setup` 详解

openclaw webhooks gmail setup --account you@example.com
openclaw webhooks gmail setup --account you@example.com --project my-gcp-project --json
openclaw webhooks gmail setup --account you@example.com --hook-url https://gateway.example.com/hooks/gmail

setup 是一个会真实变更资源的操作，完整流程为：

认证 gcloud（无有效凭据时触发交互式 gcloud auth login，见 gmail-setup-utils.ts）；
启用所需 API：gmail.googleapis.com 与 pubsub.googleapis.com；
创建或更新 Pub/Sub 主题/订阅与 push 端点，并为 Gmail 系统服务账号 serviceAccount:gmail-api-push@system.gserviceaccount.com 绑定 roles/pubsub.publisher（见 gmail-ops.ts）；
启动 Gmail watch（gog gmail watch start）；
写入本地配置：hooks.enabled: true、hooks.gmail.* 各项以及 gmail 预设（见 gmail-ops.ts）。

依赖处理上，缺失的 gcloud、gog 与 Tailscale 在 macOS 上可通过 Homebrew 自动安装；其他平台需要预先安装（非 darwin 平台直接抛出 ${bin} not installed; install it and retry，见 gmail-setup-utils.ts）。Gmail 账号必须已在 gog 中完成授权。

这不是只读检查。 setup 会变更云资源、暴露面设置与本地配置；重复运行会用 CLI 默认值覆盖已保存的 Gmail 设置。成功后会打印 Next: openclaw webhooks gmail run——仅在 Gateway 托管的 watcher 尚未运行时才需要手动执行。

警告：该命令只打通 Gmail 传输链路，并不会创建受限 reader agent 或模板预设所要求的 session-key 策略。没有自定义 Gmail 映射设置 agentId 时，入站邮件会以默认 agent 身份运行，并继承该 agent 的有效工作区、沙箱与工具策略。接入不受信任的收件箱前，请先完成配置受限 Gmail reader。

必填参数

标志	说明
`--account <email>`	要监听的 Gmail 账号。

Pub/Sub 选项

标志	默认值	说明
`--project <id>`	(无)	GCP 项目 ID（OAuth 客户端的所属项目）。回退顺序：主题自身所在项目 ID，再到从 `gog` 凭据解析出的项目。
`--topic <name>`	`gog-gmail-watch`	Pub/Sub 主题名。
`--subscription <name>`	`gog-gmail-watch-push`	Pub/Sub 订阅名。
`--label <label>`	`INBOX`	要监听的 Gmail 标签。
`--push-endpoint <url>`	(无)	显式指定 Pub/Sub push 端点。提供后会跳过 Tailscale 端点设置；对外部托管的暴露面请配合 `--tailscale off` 使用。URL 按原样使用，包含所需的 push token。

OpenClaw 投递选项

标志	默认值	说明
`--hook-url <url>`	`hooks.gmail.hookUrl`，然后是本地 Gateway URL	OpenClaw webhook 地址；自动生成的回退值由 `hooks.path` 与 Gateway 端口拼出（默认 `http://127.0.0.1:<port>/hooks/gmail`，见 buildDefaultHookUrl）。
`--hook-token <token>`	`hooks.token`，或生成新 token	OpenClaw webhook token。
`--push-token <token>`	`hooks.gmail.pushToken`，或生成新 token	单独用于 Pub/Sub 到 `gog gmail watch serve` 之间的鉴权 token。

两个 token 在未提供时由 generateHookToken() 生成，实现是 24 字节 randomBytes 的十六进制串（见 gmail.ts）。

`gog gmail watch serve` 选项

标志	默认值	说明
`--bind <host>`	`127.0.0.1`	`gog gmail watch serve` 绑定主机。
`--port <port>`	`8788`	`gog gmail watch serve` 端口。
`--path <path>`	`/gmail-pubsub`	`gog gmail watch serve` 路径。启用 Tailscale 且未显式指定 target 时强制为 `/`，因为 Tailscale 会先剥离路径再代理。
`--include-body`	`true`	包含邮件正文片段。没有 CLI 开关可以关闭它；请在配置中设置 `hooks.gmail.includeBody: false`。
`--max-bytes <n>`	`20000`	每个正文片段的最大字节数。
`--renew-minutes <n>`	`720`（12 小时）	每 N 分钟续期一次 Gmail watch。

默认常量定义在 gmail.ts：DEFAULT_GMAIL_LABEL、DEFAULT_GMAIL_TOPIC、DEFAULT_GMAIL_SUBSCRIPTION、DEFAULT_GMAIL_SERVE_BIND、DEFAULT_GMAIL_SERVE_PORT、DEFAULT_GMAIL_SERVE_PATH、DEFAULT_GMAIL_MAX_BYTES、DEFAULT_GMAIL_RENEW_MINUTES，与上表一一对应。

--path 的 Tailscale 强制行为在源码中有明确注释：Tailscale funnel/serve 在代理前会剥离设置的 path 前缀，若要在外部以 /<path> 接收请求，gog 必须监听 /（见 gmail.ts 与 gmail.ts）。

Tailscale 暴露

标志	默认值	说明
`--tailscale <mode>`	`funnel`	通过 tailscale 暴露 push 端点：`funnel`、`serve` 或 `off`。
`--tailscale-path <path>`	`hooks.gmail.tailscale.path`，然后是 serve path	tailscale serve/funnel 使用的路径。
`--tailscale-target <target>`	`hooks.gmail.tailscale.target`，然后是本地 watcher	Tailscale serve/funnel 目标（端口、`host:port` 或 URL）。

--tailscale 只接受 funnel、serve、off 三个值，其他值会直接报错（见 webhooks-cli.ts）。

输出选项

标志	说明
`--json`	以机器可读摘要代替文本输出。

注意输出敏感性：--json 输出包含 hookToken 与 pushToken，且两种格式打印出的 push endpoint 都可能内含 token；分享前必须脱敏。命令失败时展示的 stdout/stderr 有界尾部诊断（已去除终端颜色与进度重绘）同样可能包含敏感命令输出，分享前同样要脱敏。退出码与记录的终止原因用于区分超时、信号与输出截断；单独的退出码 124 并不代表超时；省略标记（…）表示输出被截断。

参数格式约束：--port、--max-bytes、--renew-minutes 必须是正整数，不接受单位后缀（解析器为 parseStrictPositiveInteger）；--include-body 没有反向 CLI 标志，需设置 hooks.gmail.includeBody: false 并让 run 继承该配置。

`webhooks gmail run` 详解

openclaw webhooks gmail run --account you@example.com

run 启动 Gmail watch 并前台运行 gog gmail watch serve 加周期性 watch 续期。其进程管理语义（与 Gateway 托管 watcher 共享同一套生命周期代码，见 gmail-watcher.ts）：

serve 进程非预期退出后，5 秒后自动重启；
绑定冲突（address already in use）会停止重启，并提示另一个 watcher 可能正在运行——可设置 OPENCLAW_SKIP_GMAIL_WATCHER=1 或先停掉另一个进程（见 gmail-watcher.ts）；
每个监听端只运行一个 watcher，重试前先停掉另一个；
Ctrl-C 或 SIGTERM 会取消待执行的重启与续期任务，并关闭 serve 进程树（SIGTERM 优雅退出，3 秒后升级 SIGKILL，另有 8 秒兜底超时，见 gmail-watcher.ts）。若日志中反复出现退出，请结合日志排查。

run 接受与 setup 相同的 Pub/Sub、OpenClaw 投递、gog gmail watch serve 与 Tailscale 标志，但有以下差异：

run 上 --account 是可选的，回退到 hooks.gmail.account；
run 不接受 --project、--push-endpoint 或 --json；
未显式指定的标志继承对应的 hooks.gmail.* 配置项；--hook-token 继承 hooks.token；
账号、完整 topic 路径、hook token、push token 必须已提供或已配置——run 不会生成缺失的 token、不会预置 Pub/Sub 资源、也不会改写配置；
无已保存配置时其余字段使用 setup 默认值，唯一例外是 --tailscale，run 的默认值是 off 而非 funnel（见 resolveGmailHookRuntimeConfig）。

类别	标志
Pub/Sub	`--account`、`--topic`、`--subscription`、`--label`
OpenClaw 投递	`--hook-url`、`--hook-token`、`--push-token`
`gog gmail watch serve`	`--bind`、`--port`、`--path`、`--include-body`、`--max-bytes`、`--renew-minutes`
Tailscale	`--tailscale`、`--tailscale-path`、`--tailscale-target`

注意：对 run 而言，--topic 的值是完整的 Pub/Sub 主题路径（projects/.../topics/...），而不是短主题名。

run 的运行时解析逻辑（resolveGmailHookRuntimeConfig）会按“CLI 覆盖 > hooks.gmail.* 配置 > 默认值”的顺序合并，并在缺少 hooks.token、账号、topic 或 push token 时返回明确的错误信息（见 gmail.ts）。

验证转发链路

openclaw config validate
openclaw logs --follow

从另一个账号向被监听收件箱发送一封测试邮件。watcher 会排除 SPAM、TRASH、DRAFT、SENT 消息（这是 OpenClaw 显式覆盖 gog 较窄的 SPAM,TRASH 默认值，见 gmail.ts 中 GMAIL_WATCH_EXCLUDED_LABELS）。随后依次检查 watcher 的转发错误、Gateway hook 的完成/错误日志，以及 reader 的运行输出。

一次成功的 push 或 HTTP 准入响应，并不证明邮件处理或通道投递已完成。 接入不受信任的收件箱前，请走完 reader 边界检查。

OpenClaw `openclaw webhooks` 实战：Gmail Pub/Sub 事件接入的完整指南