One-time wizard: Gmail watch, Pub/Sub topic/subscription, and OpenClaw hook delivery.
gmail run
Run gog gmail watch serve plus the watch auto-renew loop in the foreground.
The Gateway also auto-starts `gog gmail watch serve` on boot once `hooks.enabled=true` and `hooks.gmail.account` is set (set by `gmail setup`). `gmail run` provides a foreground watcher for debugging or when the Gateway watcher is disabled. Do not run both against the same listener. See [Gmail Pub/Sub integration](/automation/cron-jobs#gmail-pubsub-integration) for the auto-start details and `OPENCLAW_SKIP_GMAIL_WATCHER` opt-out.
Authenticates gcloud, enables the required APIs, creates or updates the Pub/Sub topic/subscription and push endpoint, starts the Gmail watch, and writes hooks.gmail with hooks.enabled: true and the Gmail preset. Missing gcloud, gog, and Tailscale dependencies can be installed automatically on macOS with Homebrew; other platforms need them installed first. The Gmail account must already be authorized in gog.
Setup changes cloud resources, exposure settings, and local config; it is not a read-only check. Re-running it can apply the CLI defaults over saved Gmail settings. It prints Next: openclaw webhooks gmail run; use that only if the Gateway-managed watcher is not already running.
This command connects Gmail transport but does not create a restricted reader agent or the session-key policy required by the templated preset. Without a custom Gmail mapping that sets `agentId`, inbound email runs as the default agent with that agent's effective workspace, sandbox, and tool policy. Complete [Configure a restricted Gmail reader](/automation/cron-jobs#configure-a-restricted-gmail-reader-recommended) before running setup for an untrusted inbox.
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. Skips Tailscale endpoint setup; use --tailscale off for externally managed exposure. The URL is used as supplied, including any required push token.
OpenClaw delivery options
Flag
Default
Description
--hook-url <url>
hooks.gmail.hookUrl, then local Gateway URL
OpenClaw webhook URL; generated fallback uses hooks.path and the Gateway port.
--hook-token <token>
hooks.token, or a generated token
OpenClaw webhook token.
--push-token <token>
hooks.gmail.pushToken, or a generated token
Separate token authenticating Pub/Sub to gog gmail watch serve.
gog gmail 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>
hooks.gmail.tailscale.path, then serve path
Path for tailscale serve/funnel.
--tailscale-target <target>
hooks.gmail.tailscale.target, then local watcher
Tailscale serve/funnel target (port, host:port, or URL).
Output
Flag
Description
--json
Print a machine-readable summary instead of text.
Setup output is sensitive: --json includes hookToken and pushToken, and the push endpoint printed in either format can contain its token. Redact output before sharing it.
--port, --max-bytes, and --renew-minutes require positive integers, without unit suffixes. --include-body has no negative CLI flag: set hooks.gmail.includeBody: false and let run inherit it.
webhooks gmail run
openclaw webhooks gmail run --account you@example.com
Starts the Gmail watch and runs gog gmail watch serve plus periodic watch renewal in the foreground. Unexpected serve-process exits continue to restart after 5 seconds. A bind conflict stops restarts; run only one watcher per listener and stop the other watcher before retrying. Ctrl-C or SIGTERM cancels pending restarts and renewal work and shuts down the serve process tree. Investigate repeated exits in the logs.
run accepts the same Pub/Sub, OpenClaw delivery, gog gmail watch serve, and Tailscale flags as setup, except:
--account is optional on run; it falls back to hooks.gmail.account.
run does not accept --project, --push-endpoint, or --json.
Unspecified flags inherit the matching hooks.gmail.* setting; --hook-token inherits hooks.token.
Account, full topic path, hook token, and push token must be supplied or configured. run does not generate missing tokens, provision Pub/Sub resources, or rewrite config.
Other fields use the setup defaults when no saved setting exists, except --tailscale, which defaults to off rather than funnel.
Peter Steinberger
1cbcf141ed