Webhooks

openclaw webhooks

openclaw webhooks sets up and runs the Gmail Pub/Sub transport through gog (gogcli). It does not register internal HOOK.md hooks, manage arbitrary Gateway hook mappings, or manage the TaskFlow Webhooks plugin.

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 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 for the auto-start details and OPENCLAW_SKIP_GMAIL_WATCHER opt-out.

webhooks gmail setup

openclaw webhooks gmail setup --account [e-mail]
openclaw webhooks gmail setup --account [e-mail] --project my-gcp-project --json
openclaw webhooks gmail setup --account [e-mail] --hook-url https://gateway.example.com/hooks/gmail

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 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 options

Flag	Default	Description
--bind <host>	127.0.0.1	gog gmail watch serve bind host.
--port <port>	8788	gog gmail watch serve port.
--path <path>	/gmail-pubsub	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 [e-mail]

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.

Category	Flags
Pub/Sub	--account, --topic, --subscription, --label
OpenClaw delivery	--hook-url, --hook-token, --push-token
gog gmail watch serve	--bind, --port, --path, --include-body, --max-bytes, --renew-minutes
Tailscale	--tailscale, --tailscale-path, --tailscale-target

For run, the --topic value is the full Pub/Sub topic path (projects/.../topics/...), not just the short topic name.

Verify forwarding

openclaw config validate
openclaw logs --follow

Send a test from another account to the watched inbox. The watcher excludes SPAM, TRASH, DRAFT, and SENT messages. Check watcher forwarding errors, then the Gateway hook completion/error logs and the reader’s run output. A successful push or HTTP admission response does not prove email processing or channel delivery completed. Follow the reader boundary check before connecting an untrusted inbox.

Related

• CLI reference
• Webhook automation
• Gmail Pub/Sub integration