Gmail Pub/Sub -> OpenClaw

Ziel: Gmail watch -> Pub/Sub Push -> gog gmail watch serve -> OpenClaw Webhook.

Voraussetzungen

  • gcloud installiert und eingeloggt (Installationsanleitung)
  • gog (gogcli) installiert und für den Gmail-Account autorisiert (gogcli.sh)
  • OpenClaw Hooks aktiviert (siehe Webhooks)
  • tailscale eingeloggt (tailscale.com). Das unterstützte Setup nutzt Tailscale Funnel für den öffentlichen HTTPS-Endpunkt. Andere Tunnel-Dienste funktionieren zwar, sind aber DIY/nicht unterstützt und erfordern manuelle Konfiguration. Aktuell unterstützen wir nur Tailscale.

Beispiel Hook-Konfiguration (Gmail Preset Mapping aktivieren):

{
  hooks: {
    enabled: true,
    token: "OPENCLAW_HOOK_TOKEN",
    path: "/hooks",
    presets: ["gmail"],
  },
}

Um die Gmail-Zusammenfassung an eine Chat-Oberfläche zu senden, überschreibe das Preset mit einem Mapping, das deliver + optional channel/to setzt:

{
  hooks: {
    enabled: true,
    token: "OPENCLAW_HOOK_TOKEN",
    presets: ["gmail"],
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        wakeMode: "now",
        name: "Gmail",
        sessionKey: "hook:gmail:{{messages[0].id}}",
        messageTemplate: "New email from {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}\n{{messages[0].body}}",
        model: "openai/gpt-5.2-mini",
        deliver: true,
        channel: "last",
        // to: "+15551234567"
      },
    ],
  },
}

Wenn du einen festen Channel willst, setze channel + to. Ansonsten nutzt channel: "last" die letzte Zustellroute (fällt auf WhatsApp zurück).

Um ein günstigeres Modell für Gmail-Läufe zu erzwingen, setze model im Mapping (provider/model oder Alias). Wenn du agents.defaults.models erzwingst, füge es dort hinzu.

Um ein Standard-Modell und Thinking-Level speziell für Gmail Hooks zu setzen, füge hooks.gmail.model / hooks.gmail.thinking in deiner Config hinzu:

{
  hooks: {
    gmail: {
      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
      thinking: "off",
    },
  },
}

Hinweise:

  • Pro-Hook model/thinking im Mapping überschreibt diese Defaults weiterhin.
  • Fallback-Reihenfolge: hooks.gmail.model → agents.defaults.model.fallbacks → primary (auth/rate-limit/timeouts).
  • Wenn agents.defaults.models gesetzt ist, muss das Gmail-Modell in der Allowlist sein.
  • Gmail Hook-Inhalte werden standardmäßig mit external-content Safety-Boundaries umschlossen. Um das zu deaktivieren (gefährlich), setze hooks.gmail.allowUnsafeExternalContent: true.

Um die Payload-Verarbeitung weiter anzupassen, füge hooks.mappings oder ein JS/TS Transform-Modul unter hooks.transformsDir hinzu (siehe Webhooks).

Wizard (empfohlen)

Nutze den OpenClaw-Helper, um alles zusammenzubauen (installiert Dependencies auf macOS via brew):

openclaw webhooks gmail setup \
  --account [email protected]

Defaults:

  • Nutzt Tailscale Funnel für den öffentlichen Push-Endpunkt
  • Schreibt hooks.gmail Config für openclaw webhooks gmail run
  • Aktiviert das Gmail Hook Preset (hooks.presets: ["gmail"])

Pfad-Hinweis: Wenn tailscale.mode aktiviert ist, setzt OpenClaw automatisch hooks.gmail.serve.path auf / und behält den öffentlichen Pfad bei hooks.gmail.tailscale.path (Standard /gmail-pubsub), weil Tailscale das set-path Präfix vor dem Proxying entfernt. Wenn das Backend den Pfad mit Präfix empfangen soll, setze hooks.gmail.tailscale.target (oder --tailscale-target) auf eine vollständige URL wie http://127.0.0.1:8788/gmail-pubsub und passe hooks.gmail.serve.path an.

Du willst einen eigenen Endpunkt? Nutze --push-endpoint <url> oder --tailscale off.

Plattform-Hinweis: Auf macOS installiert der Wizard gcloud, gogcli und tailscale via Homebrew; auf Linux musst du sie vorher manuell installieren.

Gateway Auto-Start (empfohlen):

  • Wenn hooks.enabled=true und hooks.gmail.account gesetzt ist, startet der Gateway gog gmail watch serve beim Booten und erneuert den Watch automatisch.
  • Setze OPENCLAW_SKIP_GMAIL_WATCHER=1 zum Opt-out (nützlich, wenn du den Daemon selbst startest).
  • Starte den manuellen Daemon nicht gleichzeitig, sonst bekommst du listen tcp 127.0.0.1:8788: bind: address already in use.

Manueller Daemon (startet gog gmail watch serve + Auto-Renewal):

openclaw webhooks gmail run

Einmalige Einrichtung

  1. Wähle das GCP-Projekt aus, das den OAuth-Client besitzt, der von gog genutzt wird.
gcloud auth login
gcloud config set project <project-id>

Hinweis: Gmail watch erfordert, dass das Pub/Sub Topic im selben Projekt wie der OAuth-Client liegt.

  1. APIs aktivieren:
gcloud services enable gmail.googleapis.com pubsub.googleapis.com
  1. Topic erstellen:
gcloud pubsub topics create gog-gmail-watch
  1. Gmail Push zum Publizieren berechtigen:
gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \
  --member=serviceAccount:[email protected] \
  --role=roles/pubsub.publisher

Watch starten

gog gmail watch start \
  --account [email protected] \
  --label INBOX \
  --topic projects/<project-id>/topics/gog-gmail-watch

Speichere die history_id aus der Ausgabe (zum Debuggen).

Push Handler starten

Lokales Beispiel (Shared Token Auth):

gog gmail watch serve \
  --account [email protected] \
  --bind 127.0.0.1 \
  --port 8788 \
  --path /gmail-pubsub \
  --token <shared> \
  --hook-url http://127.0.0.1:18789/hooks/gmail \
  --hook-token OPENCLAW_HOOK_TOKEN \
  --include-body \
  --max-bytes 20000

Hinweise:

  • --token schützt den Push-Endpunkt (x-gog-token oder ?token=)
  • --hook-url zeigt auf OpenClaw /hooks/gmail (gemappt; isolierter Run + Summary zur Main)
  • --include-body und --max-bytes steuern den Body-Snippet, der an OpenClaw gesendet wird

Empfohlen: openclaw webhooks gmail run umschließt denselben Flow und erneuert den Watch automatisch.

Handler exponieren (fortgeschritten, nicht unterstützt)

Wenn du einen Nicht-Tailscale-Tunnel brauchst, verdrahte ihn manuell und nutze die öffentliche URL in der Push- Subscription (nicht unterstützt, keine Guardrails):

cloudflared tunnel --url http://127.0.0.1:8788 --no-autoupdate

Nutze die generierte URL als Push-Endpunkt:

gcloud pubsub subscriptions create gog-gmail-watch-push \
  --topic gog-gmail-watch \
  --push-endpoint "https://<public-url>/gmail-pubsub?token=<shared>"

Produktion: Nutze einen stabilen HTTPS-Endpunkt und konfiguriere Pub/Sub OIDC JWT, dann führe aus:

gog gmail watch serve --verify-oidc --oidc-email <svc@...>

Test

Sende eine Nachricht an den überwachten Posteingang:

gog gmail send \
  --account [email protected] \
  --to [email protected] \
  --subject "watch test" \
  --body "ping"

Watch-Status und History prüfen:

gog gmail watch status --account [email protected]
gog gmail history --account [email protected] --since <historyId>

Troubleshooting

  • Invalid topicName: Projekt-Mismatch (Topic nicht im OAuth-Client-Projekt)
  • User not authorized: Fehlende roles/pubsub.publisher Rolle auf dem Topic
  • Leere Nachrichten: Gmail Push liefert nur historyId; abrufen via gog gmail history

Aufräumen

gog gmail watch stop --account [email protected]
gcloud pubsub subscriptions delete gog-gmail-watch-push
gcloud pubsub topics delete gog-gmail-watch