跳转至

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 watch、Pub/Sub 主题/订阅,以及 OpenClaw 钩子投递。
gmail run 在前台运行 gog gmail watch serve 以及 watch 自动续期循环。

Note

一旦 hooks.enabled=true 且已设置 hooks.gmail.account(由 gmail setup 设置),Gateway 也会在启动时自动启动 gog gmail watch serve。gmail run 提供一个前台 watcher,用于调试或在 Gateway watcher 被禁用时使用。请不要针对同一个 listener 同时运行两者。有关自动启动的详细信息以及 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 watch,并写入 hooks.gmail,设置 hooks.enabled: true 和 Gmail 预设。缺少的 gcloud、gog 和 Tailscale 依赖项可以在 macOS 上通过 Homebrew 自动安装。其他平台需要先手动安装这些依赖项。Gmail 账户必须已在 gog 中获得授权。

setup 会更改云资源、暴露设置和本地配置。它不是只读检查。重新运行它可能会将 CLI 默认值应用到已保存的 Gmail 设置上。它会输出 Next: openclaw webhooks gmail run。仅当 Gateway 托管的 watcher 尚未运行时,才使用该命令。

Warning

此命令连接 Gmail 传输,但不会创建模板化预设所要求的受限 reader agent 或会话密钥策略。如果没有设置 agentId 的自定义 Gmail 映射,入站电子邮件将以默认 agent 身份运行,并使用该 agent 的有效 workspace、sandbox 和工具策略。在对不受信任的收件箱运行 setup 之前,请先完成 配置受限 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 推送端点。跳过 Tailscale 端点设置;对于外部管理的暴露方式,请使用 --tailscale off。URL 将按提供的原样使用,包括任何必需的 push token。

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,或生成的令牌 用于向 gog gmail watch serve 验证 Pub/Sub 身份的独立令牌。

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 (12h) 每 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,并且以任一格式打印的推送端点都可能包含其令牌。分享前请对输出进行脱敏处理。

命令失败时会显示 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 秒后继续重启。绑定冲突会在 5、10 和 20 秒后重试;如果三次重试均未能绑定,则会记录错误并停止重启,但 watch 续订仍会继续。每个监听器只运行一个 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 令牌和推送令牌必须提供或配置。run 不会生成缺失的令牌、创建 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 的运行输出。成功的推送或 HTTP 接收响应并不代表邮件处理或频道投递已完成。在连接不受信任的收件箱之前,请先执行 reader 边界检查。

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