Gmail Pub/Sub -> WednesdayAI
Goal: Gmail watch -> Pub/Sub push ->gog gmail watch serve -> WednesdayAI webhook.
Prereqs
gcloudinstalled and logged in (install guide).gog(gogcli) installed and authorized for the Gmail account (gogcli.sh).- WednesdayAI hooks enabled (see Webhooks).
tailscalelogged in (tailscale.com). Supported setup uses Tailscale Funnel for the public HTTPS endpoint. Other tunnel services can work, but are DIY/unsupported and require manual wiring. Right now, Tailscale is what we support.
deliver + optional channel/to:
channel + to. Otherwise channel: "last"
uses the last delivery route (falls back to WhatsApp).
To force a cheaper model for Gmail runs, set model in the mapping
(provider/model or alias). If you enforce agents.defaults.models, include it there.
To set a default model and thinking level specifically for Gmail hooks, add
hooks.gmail.model / hooks.gmail.thinking in your config:
- Per-hook
model/thinkingin the mapping still overrides these defaults. - Fallback order:
hooks.gmail.model→agents.defaults.model.fallbacks→ primary (auth/rate-limit/timeouts). - If
agents.defaults.modelsis set, the Gmail model must be in the allowlist. - Gmail hook content is wrapped with external-content safety boundaries by default.
To disable (dangerous), set
hooks.gmail.allowUnsafeExternalContent: true.
hooks.gmail config block
itself IS the inbox enablement. No inbox.sources.gmail key is required or read.
To customize payload handling further, add hooks.mappings or a JS/TS transform module
under ~/.openclaw/hooks/transforms (see Webhooks).
Wizard (recommended)
Use the WednesdayAI helper to wire everything together (installs deps on macOS via brew):- Uses Tailscale Funnel for the public push endpoint.
- Writes
hooks.gmailconfig forwednesdayai webhooks gmail run. - Enables the Gmail hook preset (
hooks.presets: ["gmail"]).
tailscale.mode is enabled, WednesdayAI automatically sets
hooks.gmail.serve.path to / and keeps the public path at
hooks.gmail.tailscale.path (default /gmail-pubsub) because Tailscale
strips the set-path prefix before proxying.
If you need the backend to receive the prefixed path, set
hooks.gmail.tailscale.target (or --tailscale-target) to a full URL like
http://127.0.0.1:8788/gmail-pubsub and match hooks.gmail.serve.path.
Want a custom endpoint? Use --push-endpoint <url> or --tailscale off.
Platform note: on macOS the wizard installs gcloud, gogcli, and tailscale
via Homebrew; on Linux install them manually first.
Gateway auto-start (recommended):
- When
hooks.enabled=trueandhooks.gmail.accountis set, the Gateway startsgog gmail watch serveon boot and auto-renews the watch. - Set
OPENCLAW_SKIP_GMAIL_WATCHER=1to opt out (useful if you run the daemon yourself). - Do not run the manual daemon at the same time, or you will hit
listen tcp 127.0.0.1:8788: bind: address already in use.
gog gmail watch serve + auto-renew):
One-time setup
- Select the GCP project that owns the OAuth client used by
gog.
- Enable APIs:
- Create a topic:
- Allow Gmail push to publish:
Start the watch
history_id from the output (for debugging).
Run the push handler
Local example (shared token auth):--tokenprotects the push endpoint (x-gog-tokenor?token=).--hook-urlpoints to WednesdayAI/hooks/gmail(mapped; isolated run + summary to main).--include-bodyand--max-bytescontrol the body snippet sent to WednesdayAI.
--history-types messageAdded,messageDeleted, and the Gmail hook ingests
deletedMessageIds from the push payload. If you run gog gmail watch serve yourself you
must add that flag too — a gog version carrying --history-types is required (upgrade via
Homebrew: brew upgrade gogcli). Without it the default history-types set is
messageAdded only, and deletions are never pushed.
Message evidence: the hook payload carries no headers, so the inbox fetches each newly
pushed message once with gog gmail get <id> --format full before storing it. The row is
stored and classified with the allowlisted structural headers and MIME part content types
the inbox prefilter reads. A later push for a stored message (a redelivery or a label
change) is not fetched again; its labels update the row.
If the fetch fails, the message is stored from the push payload and the next reconcile
pass adds the evidence; a message Gmail no longer has is marked deleted. If you run
gog gmail watch serve on another host, install and authorize gog on the gateway host
as well.
Recommended: wednesdayai webhooks gmail run wraps the same flow and auto-renews the watch.
Expose the handler (advanced, unsupported)
If you need a non-Tailscale tunnel, wire it manually and use the public URL in the push subscription (unsupported, no guardrails):Test
Send a message to the watched inbox:gog gmail history is messageAdded-only upstream (the command hardcodes its
history types and exposes no flag), so reconcile history replay cannot observe deletions.
The watch payload above is the only deletion channel; the periodic resync sweep is the
backstop for anything it missed.
Backfill history
wednesdayai inbox backfill --source gmail [--account <address>] [--since <iso>] [--all]
pulls Gmail history into the inbox store — manual, resumable, per-page checkpointed (see
Inbox API). Gmail specifics:
- Query —
in:anywhere(full history) orin:anywhere after:YYYY/MM/DD(ranged). Gmail’safter:operator is day-granular, and Gmail interprets date bounds at midnight PST, while the fetcher builds the bound as a UTC calendar date and forwards it without timezone conversion. The server-side window can therefore open up to 8 hours after the UTC day start: for--since 2024-01-02T00:00:00Z, a message at04:00Zon Jan 2 can be excluded server-side, and the client-side timestamp filter cannot recover it — it only drops items older than the exact epoch, never adds them back. Near-boundary coverage around the since day is therefore approximate; the full-history walk (no--since) is unaffected. - Pages — up to 500 thread results per page (
--max 500on the same gog snapshot search the full resync uses), with every returned thread expanded into all of its messages — a page containing multi-message threads can therefore hold substantially more than 500 messages. The resume token is gog’s opaquenextPageToken(thread-level). Thread expansion returns every message of a matching thread, including ones older than the exact since boundary — the timestamp filter drops those. - Accounts — the enabled-account list merges
hooks.gmail.account(only when it is a plain email address, not a gog selector such asauto) with the account cursors already tracked for the source; deduped and sorted. - Deletions — backfill never drains the reconcile deletion guard; deletion pushes on the watch payload above and pending tombstone intents apply exactly as during live ingestion.
inbox.sources gate: the enabled-account list is derived from the
hooks.gmail config plus tracked account cursors (a previously active account remains
backfillable even with no hooks.gmail block), and an empty list reports the source as
not enabled.
Troubleshooting
Invalid topicName: project mismatch (topic not in the OAuth client project).User not authorized: missingroles/pubsub.publisheron the topic.- Empty messages: Gmail push only provides
historyId; fetch viagog gmail history.