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.
Command failures show bounded tails from both stdout and stderr, with terminal colors and progress redraws removed. Exit codes and recorded termination reasons distinguish timeouts, signals, and output limits. Exit code 124 alone does not mean a timeout. An omission marker (…) indicates truncated output. These diagnostics can still contain sensitive command output: redact them before sharing.
--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
91b8f103cb