openclaw webhooks

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

Subcommands

openclaw webhooks gmail setup --account <email> [...]openclaw webhooks gmail run   [--account <email>] [...]

webhooks gmail setup

openclaw webhooks gmail setup --account [email protected]openclaw webhooks gmail setup --account [email protected] --project my-gcp-project --jsonopenclaw webhooks gmail setup --account [email protected] --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.

Required

Pub/Sub options

OpenClaw delivery options

gog gmail watch serve options

Tailscale exposure

Output

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 [email protected]

Checks the selected Gog executable, starts the Gmail watch, and runs gog gmail watch serve plus periodic renewal in the foreground. Gog v0.48.0 and builds exposing both --token-env and --hook-token-env receive tokens through child-only environment sources. OpenClaw supplies the values from existing config; no manual environment exports are needed. A started message means launched, not registered or ready.

Older Gog continues using the existing token arguments, with one warning per watcher lifecycle. Other local users with process visibility can read both the Gmail push token and the shared OpenClaw hook token, which authorizes enabled hook routes. An inconclusive capability check also preserves the existing connection, with a distinct “could not verify” warning. These connections remain affected until Gog is upgraded. Once environment transport is selected, serve failures and automatic restarts never switch back to token arguments. Canceling startup stops it.

Interactive setup and run can offer a Homebrew upgrade when the executable actually selected on PATH belongs to a supported, unpinned Gog formula. Declining keeps the existing connection working. Custom wrappers, pinned formulae, and other installations receive manual upgrade guidance. OpenClaw rechecks the executable and both capabilities after an upgrade, including a failed package operation; it does not assume success or rollback. A formula that has not yet published a supporting build leaves the warning in place. If Gog is no longer executable, repair its installation before retrying.

openclaw doctor reports this for configured Gmail connections. Run openclaw doctor --repair to upgrade an eligible Homebrew installation explicitly. Gateway startup, diagnostic checks, and the Doctor pass inside openclaw update do not upgrade Gog. You can also upgrade with your installation manager; for Homebrew, run brew update and brew upgrade gogcli (or the installed tap-qualified formula). Restart the Gmail watcher afterward, or restart the Gateway for a Gateway-managed watcher. Restart other already-running Gog watchers separately.

Transient serve exits restart after 5 seconds. Bind conflicts retry after 5, 10, and 20 seconds. Ctrl-C or SIGTERM cancels pending startup, restarts, and renewal work and shuts down the process tree.

Prefer config-held tokens: existing --hook-token and --push-token overrides remain accepted, but secrets manually placed on the parent CLI command line remain visible there. Environment handoff does not protect against the process owner or root. One-time setup separately passes a token-bearing Pub/Sub push endpoint to gcloud; this serve-launch change does not remove that setup exposure.

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.

Verify forwarding

openclaw config validateopenclaw 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
• Configuration reference — where each webhook setting is documented