docs/cli/webhooks.md
openclaw webhooksWebhook helpers and integrations. Today this surface is scoped to Gmail Pub/Sub flows built on the bundled gog watcher.
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 watch serve plus the watch auto-renew loop in the foreground. |
webhooks gmail setupopenclaw webhooks gmail setup --account [email protected]
openclaw webhooks gmail setup --account [email protected] --project my-gcp-project --json
openclaw webhooks gmail setup --account [email protected] --hook-url https://gateway.example.com/hooks/gmail
Installs gcloud and gog if missing, authenticates gcloud, creates the Pub/Sub topic and subscription, starts the Gmail watch, and writes hooks.gmail config with hooks.enabled=true. Prints Next: openclaw webhooks gmail run.
| Flag | Description |
|---|---|
--account <email> | Gmail account to watch. |
| 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. Overrides Tailscale. |
| Flag | Default | Description |
|---|---|---|
--hook-url <url> | Built 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 forwarded to gog watch serve. |
gog watch serve options| Flag | Default | Description |
|---|---|---|
--bind <host> | 127.0.0.1 | gog watch serve bind host. |
--port <port> | 8788 | gog watch serve port. |
--path <path> | /gmail-pubsub | gog 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. |
| Flag | Default | Description |
|---|---|---|
--tailscale <mode> | funnel | Expose push endpoint via tailscale: funnel, serve, or off. |
--tailscale-path <path> | (none) | Path for tailscale serve/funnel. |
--tailscale-target <t> | (none) | Tailscale serve/funnel target (port, host:port, or URL). |
| Flag | Description |
|---|---|
--json | Print a machine-readable summary instead of text. |
webhooks gmail runopenclaw webhooks gmail run --account [email protected]
Runs gog watch serve plus the watch auto-renew loop in the foreground, restarting gog watch serve after a 2s delay if it exits unexpectedly.
run accepts the same Pub/Sub, OpenClaw delivery, gog 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.hooks.gmail.* config value (written by setup), then to the same built-in default setup uses, with one exception: --tailscale defaults to off on run (not funnel) when neither the flag nor hooks.gmail.tailscale.mode is set.| 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 |