openclaw webhooks CLI reference for Gmail Pub/Sub setup and runner
Reference for the openclaw webhooks CLI commands, covering Gmail Pub/Sub integration setup and foreground runner. Useful for developers configuring Gmail watch, Pub/Sub topics, and webhook delivery.
Read this when
- You want to wire Gmail Pub/Sub events into OpenClaw
- You need the full flag list and default values
openclaw webhooks
Webhook helpers and integrations. Currently this surface is limited to Gmail Pub/Sub flows built on the bundled gog watcher.
Subcommands
openclaw webhooks gmail setup --account <email> [...]
openclaw webhooks gmail run [--account <email>] [...]
| Subcommand | Description |
|---|---|
gmail setup | One-time wizard: Gmail watch, Pub/Sub topic/subscription, and OpenClaw hook delivery. |
gmail run | Run gog watch serve plus the watch auto-renew loop in the foreground. |
Note
The Gateway also auto-starts
gog gmail watch serveon boot oncehooks.enabled=trueandhooks.gmail.accountis set (set bygmail setup).gmail runis the same logic in the foreground, useful for debugging or when the Gateway watcher is disabled. See Gmail Pub/Sub integration for the auto-start details andOPENCLAW_SKIP_GMAIL_WATCHERopt-out.
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
Installs gcloud and gog if missing, authenticates gcloud, creates the Pub/Sub topic and subscription, starts the Gmail watch, and writes hooks.gmail config with hooks.enabled=true. Prints Next: openclaw webhooks gmail run.
Required
| Flag | Description |
|---|---|
--account <email> | Gmail account to watch. |
Pub/Sub options
| Flag | Default | Description |
|---|---|---|
--project <id> | (none) | GCP project id (the OAuth client owner). Falls back to the topic's own project id, then to the project resolved from gog credentials. |
--topic <name> | gog-gmail-watch | Pub/Sub topic name. |
--subscription <name> | gog-gmail-watch-push | Pub/Sub subscription name. |
--label <label> | INBOX | Gmail label to watch. |
--push-endpoint <url> | (none) | Explicit Pub/Sub push endpoint. Overrides Tailscale. |
OpenClaw delivery options
| Flag | Default | Description |
|---|---|---|
--hook-url <url> | Built from hooks.path and the Gateway port | OpenClaw webhook URL. |
--hook-token <token> | hooks.token, or a generated token | OpenClaw webhook token. |
--push-token <token> | Generated token | Push token forwarded to gog watch serve. |
gog watch serve options
| Flag | Default | Description |
|---|---|---|
--bind <host> | 127.0.0.1 | gog watch serve bind host. |
--port <port> | 8788 | gog watch serve port. |
--path <path> | /gmail-pubsub | gog watch serve path. Forced to / when Tailscale is enabled without an explicit target, since Tailscale strips the path before proxying. |
--include-body | true | Include email body snippets. There is no CLI flag to turn this off; set hooks.gmail.includeBody: false in config instead. |
--max-bytes <n> | 20000 | Max bytes per body snippet. |
--renew-minutes <n> | 720 (12h) | Renew Gmail watch every N minutes. |
Tailscale exposure
| Flag | Default | Description |
|---|---|---|
--tailscale <mode> | funnel | Expose push endpoint via tailscale: funnel, serve, or off. |
--tailscale-path <path> | (none) | Path for tailscale serve/funnel. |
--tailscale-target <t> | (none) | Tailscale serve/funnel target (port, host:port, or URL). |
Output
| Flag | Description |
|---|---|
--json | Print a machine-readable summary instead of text. |
webhooks gmail run
openclaw webhooks gmail run --account you@example.com
Runs gog watch serve plus the watch auto-renew loop in the foreground, restarting gog watch serve after a 2s delay if it exits unexpectedly.
run accepts the same Pub/Sub, OpenClaw delivery, gog watch serve, and Tailscale flags as setup, except:
--accountis optional onrun; it falls back tohooks.gmail.account.rundoes not accept--project,--push-endpoint, or--json.- Every flag falls back to the matching
hooks.gmail.*config value (written bysetup), then to the same built-in defaultsetupuses, with one exception:--tailscaledefaults tooffonrun(notfunnel) when neither the flag norhooks.gmail.tailscale.modeis set.
| Category | Flags |
|---|---|
| Pub/Sub | --account, --topic, --subscription, --label |
| OpenClaw delivery | --hook-url, --hook-token, --push-token |
gog watch serve | --bind, --port, --path, --include-body, --max-bytes, --renew-minutes |
| Tailscale | --tailscale, --tailscale-path, --tailscale-target |
Note
For
run, the--topicvalue is the full Pub/Sub topic path (projects/.../topics/...), not just the short topic name.