`openclaw webhooks`¶

openclaw webhooks 通过 gog（gogcli）设置并运行 Gmail Pub/Sub 传输。它不会注册内部 HOOK.md 钩子，也不管理任意的 Gateway 钩子映射。

子命令¶

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

子命令	描述
`gmail setup`	一次性向导：Gmail 监视、Pub/Sub 主题/订阅，以及 OpenClaw 钩子投递。
`gmail run`	在前台运行 `gog gmail watch serve`，并同时运行监视自动续期循环。

Note

Gateway 也会在启动时自动启动 gog gmail watch serve，前提是 hooks.enabled=true 且设置了 hooks.gmail.account（由 gmail setup 设置）。gmail run 在前台提供监视器，用于调试或当 Gateway 监视器被禁用时。不要对同一监听器同时运行两者。有关自动启动详情及 OPENCLAW_SKIP_GMAIL_WATCHER 退出机制，请参阅 Gmail Pub/Sub 集成。

`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

对 gcloud 进行身份验证，启用所需 API，创建或更新 Pub/Sub 主题/订阅及推送端点，启动 Gmail 监视，并写入 hooks.gmail，其中包含 hooks.enabled: true 和 Gmail 预设。缺少的 gcloud、gog 和 Tailscale 依赖可以在 macOS 上通过 Homebrew 自动安装。其他平台需要先安装它们。Gmail 账户必须已在 gog 中获得授权。

setup 会更改云资源、暴露设置和本地配置。它不是只读检查。重新运行它可能会用 CLI 默认值覆盖已保存的 Gmail 设置。它会打印 Next: openclaw webhooks gmail run。仅当 Gateway 管理的监视器尚未运行时，才使用该命令。

Warning

此命令连接 Gmail 传输，但不会创建模板化预设所要求的受限读取代理或会话密钥策略。如果没有设置 agentId 的自定义 Gmail 映射，入站邮件将以默认代理身份运行，并应用该代理的有效工作区、沙箱和工具策略。在对不受信任的收件箱运行 setup 之前，请先完成配置受限 Gmail 读取代理。

必需参数¶

标志	描述
`--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 推送端点。跳过 Tailscale 端点设置；对于外部管理的暴露，使用 `--tailscale off`。URL 将按提供的原样使用，包括任何必需的推送令牌。

OpenClaw 投递选项¶

标志	默认值	描述
`--hook-url <url>`	`hooks.gmail.hookUrl`，然后是本地 Gateway URL	OpenClaw webhook URL；生成的回退值使用 `hooks.path` 和 Gateway 端口。
`--hook-token <token>`	`hooks.token`，或生成的令牌	OpenClaw webhook 令牌。
`--push-token <token>`	`hooks.gmail.pushToken`，或生成的令牌	用于 Pub/Sub 向 `gog gmail watch serve` 进行身份验证的独立令牌。

`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 且未显式指定目标时，强制为 `/`，因为 Tailscale 会在代理前剥离路径。
`--include-body`	`true`	包含邮件正文片段。没有用于关闭此功能的 CLI 标志；请改为在配置中设置 `hooks.gmail.includeBody: false`。
`--max-bytes <n>`	`20000`	每个正文片段的最大字节数。
`--renew-minutes <n>`	`720`（12 小时）	每 N 分钟续订一次 Gmail watch。

Tailscale 暴露¶

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

输出¶

标志	说明
`--json`	打印机器可读的摘要，而不是文本。

Warning

setup 输出包含敏感信息：--json 会包含 hookToken 和 pushToken，并且以任一格式打印的推送端点都可能包含其 token。共享前请对输出进行脱敏。

命令失败时会显示来自 stdout 和 stderr 的有界尾部内容，并移除终端颜色和进度重绘。退出代码和记录的终止原因可区分超时、信号和输出限制。仅退出代码 124 并不一定表示超时。省略标记（…）表示输出被截断。这些诊断信息仍可能包含敏感的命令输出：共享前请对其进行脱敏。

--port、--max-bytes 和 --renew-minutes 需要不带单位后缀的正整数。--include-body 没有对应的否定 CLI 标志：请设置 hooks.gmail.includeBody: false，并让 run 继承该设置。

`webhooks gmail run`¶

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

启动 Gmail watch，并在前台运行 gog gmail watch serve 以及周期性 watch 续订。serve 进程意外退出后，会在 5 秒后继续重启。绑定冲突会停止重启。每个监听器只运行一个 watcher，并在重试前停止另一个 watcher。Ctrl-C 或 SIGTERM 会取消待处理的重启和续订工作，并关闭 serve 进程树。请在日志中调查反复退出的原因。

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。
必须提供或配置账户、完整主题路径、hook token 和 push token。run 不会生成缺失的 token、配置 Pub/Sub 资源或重写配置。
当没有已保存设置时，其他字段使用 setup 默认值，但 --tailscale 除外，其默认值为 off 而不是 funnel。

类别	标志
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`

Note

对于 run，--topic 的值是完整的 Pub/Sub 主题路径（projects/.../topics/...），而不仅仅是简短的主题名称。

验证转发¶

openclaw config validate
openclaw logs --follow

从另一个账户向被监视的收件箱发送测试邮件。watcher 会排除 SPAM、TRASH、DRAFT 和 SENT 消息。检查 watcher 转发错误，然后检查 Gateway hook 完成/错误日志以及 reader 的 run 输出。成功的推送或 HTTP 准入响应并不能证明邮件处理或通道投递已完成。在连接不受信任的收件箱之前，请遵循 reader 边界检查。

CLI 参考
Webhook 自动化
Gmail Pub/Sub 集成
配置参考 — 每个 webhook 设置的文档位置

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw

openclaw webhooks¶