Passer au contenu principal

​
Gmail Pub/Sub -> OpenClaw

Objectif : surveillance Gmail -> push Pub/Sub -> gog gmail watch serve -> webhook OpenClaw.

​
Prérequis

  • gcloud installé et connecté (guide d’installation).
  • gog (gogcli) installé et autorisé pour le compte Gmail (gogcli.sh).
  • Webhooks OpenClaw activés (voir Webhooks).
  • tailscale connecté (tailscale.com). La configuration prise en charge utilise Tailscale Funnel pour le point de terminaison HTTPS public. D’autres services de tunnel peuvent fonctionner, mais sont DIY/non pris en charge et nécessitent un câblage manuel. Actuellement, Tailscale est ce que nous prenons en charge.
Exemple de configuration de hook (activer le mapping prédéfini Gmail) : 
{
  hooks: {
    enabled: true,
    token: "OPENCLAW_HOOK_TOKEN",
    path: "/hooks",
    presets: ["gmail"],
  },
}
Pour livrer le résumé Gmail vers une surface de discussion, remplacez le prédéfini par un mapping qui définit deliver + channel/to en option : 
{
  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"
      },
    ],
  },
}
Si vous souhaitez un canal fixe, définissez channel + to. Sinon channel: "last" utilise la dernière route de livraison (retombe sur WhatsApp). Pour forcer un modèle moins coûteux pour les exécutions Gmail, définissez model dans le mapping (provider/model ou alias). Si vous imposez agents.defaults.models, incluez-le ici. Pour définir un modèle par défaut et un niveau de réflexion spécifiquement pour les hooks Gmail, ajoutez hooks.gmail.model / hooks.gmail.thinking dans votre configuration : 
{
  hooks: {
    gmail: {
      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
      thinking: "off",
    },
  },
}
Remarques :
  • Les model/thinking par hook dans le mapping remplacent toujours ces valeurs par défaut.
  • Ordre de repli : hooks.gmail.model → agents.defaults.model.fallbacks → primaire (auth/limitation de débit/délais).
  • Si agents.defaults.models est défini, le modèle Gmail doit être dans la liste d’autorisation.
  • Le contenu du hook Gmail est enveloppé par défaut avec des limites de sécurité de contenu externe. Pour désactiver (dangereux), définissez hooks.gmail.allowUnsafeExternalContent: true.
Pour personnaliser davantage la gestion du payload, ajoutez hooks.mappings ou un module de transformation JS/TS sous hooks.transformsDir (voir Webhooks).

​
Assistant (recommandé)

Utilisez l’assistant OpenClaw pour tout câbler (installe les dépendances sur macOS via brew) : 
openclaw webhooks gmail setup \
  --account [email protected]
Valeurs par défaut :
  • Utilise Tailscale Funnel pour le point de terminaison de push public.
  • Écrit la configuration hooks.gmail pour openclaw webhooks gmail run.
  • Active le préréglage de hook Gmail (hooks.presets: ["gmail"]).
Note de chemin : lorsque tailscale.mode est activé, OpenClaw définit automatiquement hooks.gmail.serve.path sur / et conserve le chemin public à hooks.gmail.tailscale.path (par défaut /gmail-pubsub) car Tailscale supprime le préfixe de chemin défini avant le proxy. Si vous avez besoin que le backend reçoive le chemin préfixé, définissez hooks.gmail.tailscale.target (ou --tailscale-target) vers une URL complète comme http://127.0.0.1:8788/gmail-pubsub et faites correspondre hooks.gmail.serve.path. Besoin d’un point de terminaison personnalisé ? Utilisez --push-endpoint <url> ou --tailscale off. Note de plateforme : sur macOS, l’assistant installe gcloud, gogcli et tailscale via Homebrew ; sur Linux, installez-les manuellement au préalable. Démarrage automatique du Gateway (passerelle) (recommandé) :
  • Lorsque hooks.enabled=true et hooks.gmail.account est défini, le Gateway démarre gog gmail watch serve au démarrage et renouvelle automatiquement la surveillance.
  • Définissez OPENCLAW_SKIP_GMAIL_WATCHER=1 pour vous désinscrire (utile si vous exécutez le daemon vous‑même).
  • N’exécutez pas le daemon manuel en même temps, sinon vous rencontrerez listen tcp 127.0.0.1:8788: bind: address already in use.
Daemon manuel (démarre gog gmail watch serve + renouvellement automatique) : 
openclaw webhooks gmail run

​
Configuration unique

  1. Sélectionnez le projet GCP qui possède le client OAuth utilisé par gog.
gcloud auth login
gcloud config set project <project-id>
Remarque : la surveillance Gmail exige que le topic Pub/Sub réside dans le même projet que le client OAuth.
  1. Activer les API :
gcloud services enable gmail.googleapis.com pubsub.googleapis.com
  1. Créer un topic :
gcloud pubsub topics create gog-gmail-watch
  1. Autoriser Gmail push à publier :
gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \
  --member=serviceAccount:[email protected] \
  --role=roles/pubsub.publisher

​
Démarrer la surveillance

gog gmail watch start \
  --account [email protected] \
  --label INBOX \
  --topic projects/<project-id>/topics/gog-gmail-watch
Enregistrez le history_id depuis la sortie (pour le débogage).

​
Exécuter le gestionnaire de push

Exemple local (authentification par jeton partagé) : 
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
Remarques :
  • --token protège le point de terminaison push (x-gog-token ou ?token=).
  • --hook-url pointe vers OpenClaw /hooks/gmail (mappé ; exécution isolée + résumé vers le principal).
  • --include-body et --max-bytes contrôlent l’extrait du corps envoyé à OpenClaw.
Recommandé : openclaw webhooks gmail run encapsule le même flux et renouvelle automatiquement la surveillance.

​
Exposer le gestionnaire (avancé, non pris en charge)

Si vous avez besoin d’un tunnel autre que Tailscale, câblez-le manuellement et utilisez l’URL publique dans la souscription push (non pris en charge, sans garde-fous) : 
cloudflared tunnel --url http://127.0.0.1:8788 --no-autoupdate
Utilisez l’URL générée comme point de terminaison push : 
gcloud pubsub subscriptions create gog-gmail-watch-push \
  --topic gog-gmail-watch \
  --push-endpoint "https://<public-url>/gmail-pubsub?token=<shared>"
Production : utilisez un point de terminaison HTTPS stable et configurez Pub/Sub OIDC JWT, puis exécutez : 
gog gmail watch serve --verify-oidc --oidc-email <svc@...>

​
Test

Envoyez un message à la boîte de réception surveillée : 
gog gmail send \
  --account [email protected] \
  --to [email protected] \
  --subject "watch test" \
  --body "ping"
Vérifiez l’état de la surveillance et l’historique : 
gog gmail watch status --account [email protected]
gog gmail history --account [email protected] --since <historyId>

​
Problemes courants

  • Invalid topicName : incohérence de projet (le topic n’est pas dans le projet du client OAuth).
  • User not authorized : roles/pubsub.publisher manquant sur le topic.
  • Messages vides : le push Gmail ne fournit que historyId ; récupérez via gog gmail history.

​
Nettoyage

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