本页介绍 openclaw webhooks 命令，当前主要功能是 Gmail Pub/Sub 集成：webhooks gmail setup 一步配置 Gmail Watch、Pub/Sub Topic/Subscription 和 OpenClaw webhook 投递，webhooks gmail run 启动本地推送接收和 watch 自动续期循环。

openclaw webhooks

Webhook 工具与集成。当前内置 Gmail Pub/Sub 推送配置和运行时。

相关文档：

• Webhook 自动化：Webhooks
• Gmail Pub/Sub：Gmail Pub/Sub 集成

Gmail

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

webhooks gmail setup

配置 Gmail watch、Pub/Sub 和 OpenClaw webhook 投递路径。

必填：

• --account <email>：Gmail 账号地址

可选项：

参数	说明
--project <id>	GCP 项目 ID
--topic <name>	Pub/Sub topic 名称
--subscription <name>	Pub/Sub subscription 名称
--label <label>	Gmail 标签过滤
--hook-url <url>	OpenClaw webhook 接收 URL
--hook-token <token>	webhook 认证 token
--push-token <token>	Pub/Sub push token
--bind <host>	本地监听地址
--port <port>	监听端口
--path <path>	接收路径
--include-body	包含邮件正文
--max-bytes <n>	邮件正文最大字节数
--renew-minutes <n>	watch 续期间隔（分钟）
--tailscale <funnel|serve|off>	Tailscale 暴露方式
--tailscale-path <path>	Tailscale 路径
--tailscale-target <target>	Tailscale 目标
--push-endpoint <url>	自定义 Pub/Sub push endpoint
--json	JSON 输出

示例：

# 最简配置（交互式引导）
openclaw webhooks gmail setup --account you@example.com

# 指定 GCP 项目
openclaw webhooks gmail setup --account you@example.com --project my-gcp-project --json

# 配置自定义 webhook URL
openclaw webhooks gmail setup --account you@example.com \
  --hook-url https://gateway.example.com/hooks/gmail

webhooks gmail run

启动 Gmail watch serve + watch 自动续期循环（gog watch serve）。

选项与 setup 相同（所有参数均为运行时覆盖）：

• --account <email>
• --topic <topic>
• --subscription <name>
• --label <label>
• --hook-url <url>
• --hook-token <token>
• --push-token <token>
• --bind <host>
• --port <port>
• --path <path>
• --include-body
• --max-bytes <n>
• --renew-minutes <n>
• --tailscale <funnel|serve|off>
• --tailscale-path <path>
• --tailscale-target <target>

示例：

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

完整端对端配置流程请参考 Gmail Pub/Sub 文档。

常见问题

Q: webhooks gmail setup 需要哪些 GCP 权限？

A: 需要 Pub/Sub Admin（创建 Topic/Subscription）以及 Gmail API 的 https://www.googleapis.com/auth/gmail.modify 权限，用于创建 watch。

Q: Gmail watch 会过期吗，需要手动续期吗？

A: Gmail watch 默认 7 天过期。webhooks gmail run 会通过 --renew-minutes 设置的间隔自动续期，无需手动操作。

Q: 如何测试 webhook 接收是否正常？

A: 先运行 webhooks gmail setup 配置完成后，再运行 webhooks gmail run 启动本地接收，然后向配置的 Gmail 账号发一封测试邮件，查看 OpenClaw 日志确认是否收到推送。