OpenClaw Webhooks CLI: Gmail Pub/Sub Setup and Runner
Reference for the openclaw webhooks command, covering Gmail Pub/Sub setup and the gmail run foreground watcher. For developers configuring Gmail integration or debugging the watcher.
Read this when
- You want to wire Gmail Pub/Sub events into OpenClaw
- You need the full flag list and default values
openclaw webhooks
This section covers webhook helpers and integrations. At present, it focuses on Gmail Pub/Sub workflows that rely on the bundled gog watcher.
Subcommands
openclaw webhooks gmail setup --account <email> [...]
openclaw webhooks gmail run [--account <email>] [...]
| Subcommand | Description |
|---|---|
gmail setup | A single-run wizard that sets up Gmail watch, Pub/Sub topic and subscription, and OpenClaw hook delivery. |
gmail run | Executes gog watch serve in the foreground along with the watch auto-renew loop. |
Note
The Gateway additionally launches
gog gmail watch serveautomatically at boot oncehooks.enabled=trueandhooks.gmail.accountare configured (done bygmail setup).gmail runprovides the same functionality in the foreground, which helps with debugging or when the Gateway watcher is turned off. For details on auto-start behavior and theOPENCLAW_SKIP_GMAIL_WATCHERopt-out, refer to Gmail Pub/Sub integration.
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
If gcloud and gog are absent, they get installed. Authentication for gcloud is performed, the Pub/Sub topic and subscription are created, the Gmail watch is initiated, and hooks.gmail config is written with hooks.enabled=true. Next: openclaw webhooks gmail run is printed.
Warning
While this command establishes the Gmail transport, it does not set up a restricted reader agent or the session-key policy that the templated preset expects. Unless a custom Gmail mapping defines
agentId, inbound email is handled by the default agent using that agent's workspace, sandbox, and tool policies. Finish Configure a restricted Gmail reader before running setup against an untrusted inbox.
Required
| Flag | Description |
|---|---|
--account <email> | The Gmail account under watch. |
Pub/Sub options
| Flag | Default | Description |
|---|---|---|
--project <id> | (none) | GCP project id (owner of the OAuth client). If not set, it falls back to the topic's project id, then to the project derived from gog credentials. |
--topic <name> | gog-gmail-watch | Name for the Pub/Sub topic. |
--subscription <name> | gog-gmail-watch-push | Name for the Pub/Sub subscription. |
--label <label> | INBOX | Gmail label to monitor. |
--push-endpoint <url> | (none) | Explicit Pub/Sub push endpoint. Takes precedence over Tailscale. |
OpenClaw delivery options
| Flag | Default | Description |
|---|---|---|
--hook-url <url> | Derived 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 sent to gog watch serve. |
gog watch serve options
| Flag | Default | Description |
|---|---|---|
--bind <host> | 127.0.0.1 | The host that gog watch serve binds to. |
--port <port> | 8788 | The port used by gog watch serve. |
--path <path> | /gmail-pubsub | The path for gog watch serve. When Tailscale is enabled without an explicit target, this is forced to / because Tailscale removes the path before proxying. |
--include-body | true | Whether to include email body snippets. No CLI flag disables this; instead, set hooks.gmail.includeBody: false in the config. |
--max-bytes <n> | 20000 | The maximum number of bytes per body snippet. |
--renew-minutes <n> | 720 (12h) | How often, in minutes, the Gmail watch is renewed. |
Tailscale exposure
| Flag | Default | Description |
|---|---|---|
--tailscale <mode> | funnel | Expose the push endpoint through tailscale: funnel, serve, or off. |
--tailscale-path <path> | (none) | The path used for tailscale serve/funnel. |
--tailscale-target <t> | (none) | The tailscale serve/funnel target, which can be a port, host:port, or a URL. |
Output
| Flag | Description |
|---|---|
--json | Output a machine-readable summary rather than text. |
webhooks gmail run
openclaw webhooks gmail run --account you@example.com
This runs gog watch serve together with the watch auto-renew loop in the foreground. If gog watch serve exits unexpectedly, it is restarted after a 2-second delay.
run takes the same Pub/Sub, OpenClaw delivery, gog watch serve, and Tailscale flags as setup, with these differences:
- On
run,--accountis optional and defaults tohooks.gmail.account. runrejects--project,--push-endpoint, and--json.- Each flag first falls back to the corresponding
hooks.gmail.*config value, whichsetupwrites, and then to the same built-in default thatsetupuses. The single exception is--tailscale, which defaults tooffonrun(rather thanfunnel) when neither the flag norhooks.gmail.tailscale.modeis provided.
| 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
When working with
run, the--topicfield holds the entire Pub/Sub topic path (projects/.../topics/...), rather than only the abbreviated topic name.