Google ChatGoogle Chat

État : plugin téléchargeable pour les DMs et les espaces via les webhooks de l’API Google Chat (HTTP uniquement).

Installer

Installez Google Chat avant de configurer le channel :

openclaw plugins install @openclaw/googlechat

Extraction locale (lors de l’exécution depuis un dépôt git) :

openclaw plugins install ./path/to/local/googlechat-plugin

Configuration rapide (débutant)

Créez un projet Google Cloud et activez l’API Google Chat.
- Accédez à : [Identifiants de l’API Google Chat](Google ChatAPIhttps://console.cloud.google.com/apis/api/chat.googleapis.com/credentials)
- Activez l’API si elle ne l’est pas déjà.
Créez un compte de service :
- Appuyez sur Créer des identifiants > Compte de service.
- Nommez-le comme vous le souhaitez (par exemple, openclaw-chat).
- Laissez les autorisations vides (appuyez sur Continuer).
- Laissez les principaux ayant accès vides (appuyez sur Terminé).
Créez et téléchargez la clé JSON :
- Dans la liste des comptes de service, cliquez sur celui que vous venez de créer.
- Allez dans l’onglet Clés.
- Cliquez sur Ajouter une clé > Créer une nouvelle clé.
- Sélectionnez JSON et appuyez sur Créer.
Stockez le fichier JSON téléchargé sur votre hôte de passerelle (par exemple, ~/.openclaw/googlechat-service-account.json).
Créez une application Google Chat dans la [Configuration Chat de la console Google Cloud](Google Chathttps://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat) :
- Remplissez les Informations sur l’application :
  - Nom de l’application : (par exemple OpenClaw)
  - URL de l’avatar : (par exemple https://openclaw.ai/logo.png)
  - Description : (par exemple Personal AI Assistant)
- Activez les Fonctionnalités interactives.
- Sous Fonctionnalité, cochez Rejoindre les espaces et les conversations de groupe.
- Sous Paramètres de connexion, sélectionnez URL du point de terminaison HTTP.
- Sous Déclencheurs, sélectionnez Utiliser une URL de point de terminaison HTTP commune pour tous les déclencheurs et définissez-la sur l’URL publique de votre passerelle suivie de /googlechat.
  - Astuce : Exécutez openclaw status pour trouver l’URL publique de votre passerelle.
- Sous Visibilité, cochez Rendre cette application Chat disponible pour des personnes et des groupes spécifiques dans <Your Domain>.
- Entrez votre adresse e-mail (par ex. [email protected]) dans la zone de texte.
- Cliquez sur Save (Enregistrer) en bas.
Activer le statut de l’application :
- Après avoir enregistré, actualisez la page.
- Recherchez la section App status (Statut de l’application) (généralement en haut ou en bas après l’enregistrement).
- Changez le statut pour Live - available to users (En ligne - disponible pour les utilisateurs).
- Cliquez à nouveau sur Save (Enregistrer).
Configurez OpenClaw avec le chemin du compte de service + l’audience du webhook :
- Env : GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json
- Ou config : channels.googlechat.serviceAccountFile: "/path/to/service-account.json".
Définissez le type + la valeur de l’audience du webhook (doit correspondre à la configuration de votre application Chat).
Démarrez la passerelle. Google Chat enverra une requête POST au chemin de votre webhook.

Ajouter à Google Chat

Une fois la passerelle démarrée et votre e-mail ajouté à la liste de visibilité :

Accédez à [Google Chat](Google Chathttps://chat.google.com/).
Cliquez sur l’icône + (plus) à côté de Direct Messages (Messages directs).
Dans la barre de recherche (où vous ajoutez habituellement des personnes), tapez le nom de l’application que vous avez configuré dans la Google Cloud Console.
- Note : Le bot n’apparaîtra pas dans la liste de navigation du « Marketplace » car il s’agit d’une application privée. Vous devez le rechercher par son nom.
Sélectionnez votre bot dans les résultats.
Cliquez sur Add (Ajouter) ou Chat (Discuter) pour commencer une conversation 1:1.
Envoyez « Bonjour » pour activer l’assistant !

URL publique (Webhook uniquement)

Les webhooks Google Chat nécessitent un point de terminaison HTTPS public. Pour la sécurité, n’exposez que le chemin /googlechat à Internet. Gardez le tableau de bord OpenClaw et les autres points de terminaison sensibles sur votre réseau privé.

Option A : Funnel Tailscale (Recommandé)

Utilisez Tailscale Serve pour le tableau de bord privé et Funnel pour le chemin du webhook public. Cela permet de garder / privé tout en n’exposant que /googlechat.

Vérifiez à quelle adresse votre passerelle est liée :
Fenêtre de terminal
```
ss -tlnp | grep 18789
```
Notez l’adresse IP (par ex., 127.0.0.1, 0.0.0.0, ou votre IP Tailscale comme 100.x.x.x).

Exposer le tableau de bord uniquement au tailnet (port 8443) :

# If bound to localhost (127.0.0.1 or 0.0.0.0):
tailscale serve --bg --https 8443 http://127.0.0.1:18789

# If bound to Tailscale IP only (e.g., 100.106.161.80):
tailscale serve --bg --https 8443 http://100.106.161.80:18789

N’exposer publiquement que le chemin du webhook :

# If bound to localhost (127.0.0.1 or 0.0.0.0):
tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat

# If bound to Tailscale IP only (e.g., 100.106.161.80):
tailscale funnel --bg --set-path /googlechat http://100.106.161.80:18789/googlechat

Autoriser le nœud pour l’accès Funnel : Si vous y êtes invité, visitez l’URL d’autorisation affichée dans la sortie pour activer Funnel pour ce nœud dans votre stratégie tailnet.

Vérifier la configuration :

tailscale serve status
tailscale funnel status

Votre URL publique de webhook sera : https://<node-name>.<tailnet>.ts.net/googlechat

Votre tableau de bord privé reste exclusif au tailnet : https://<node-name>.<tailnet>.ts.net:8443/

Utilisez l’URL publique (sans :8443) dans la configuration de l’application Google Chat.

Remarque : Cette configuration persiste après les redémarrages. Pour la supprimer plus tard, exécutez tailscale funnel reset et tailscale serve reset.

Option B : Proxy inverse (Caddy)

Si vous utilisez un proxy inverse comme Caddy, ne proxifiez que le chemin spécifique :

your-domain.com {
    reverse_proxy /googlechat* localhost:18789
}

Avec cette configuration, toute requête vers your-domain.com/ sera ignorée ou renverra 404, tandis que your-domain.com/googlechat est acheminée en toute sécurité vers OpenClaw.

Option C : Cloudflare Tunnel

Configurez les règles d’ingress de votre tunnel pour router uniquement le chemin du webhook :

Chemin : /googlechat -> http://localhost:18789/googlechat
Règle par défaut : HTTP 404 (Non trouvé)

Fonctionnement

Google Chat envoie des POST de webhook vers la passerelle. Chaque requête inclut un en-tête Authorization: Bearer <token>.
- OpenClaw vérifie l’authentification par porteur avant de lire/analyser les corps complets des webhooks lorsque l’en-tête est présent.
- Les requêtes Google Workspace Add-on qui contiennent authorizationEventObject.systemIdToken dans le corps sont prises en charge via un budget de corps de pré-authentification plus strict.
OpenClaw vérifie le jeton par rapport au audienceType configuré + audience :
- audienceType: "app-url" → l’audience est votre URL de webhook HTTPS.
- audienceType: "project-number" → l’audience est le numéro de projet Cloud.
Les messages sont routés par espace :
- Les DMs utilisent la clé de session agent:<agentId>:googlechat:direct:<spaceId>.
- Les espaces utilisent la clé de session agent:<agentId>:googlechat:group:<spaceId>.
L’accès DM est par appariement par défaut. Les expéditeurs inconnus reçoivent un code d’appariement ; approuvez avec :
- openclaw pairing approve googlechat <code>
Les espaces de groupe nécessitent une @-mention par défaut. Utilisez botUser si la détection de mention a besoin du nom d’utilisateur de l’application.

Cibles

Utilisez ces identifiants pour la livraison et les listes autorisées :

Messages directs : users/<userId> (recommandé).
L’e-mail brut [email protected] est modifiable et utilisé uniquement pour la correspondance directe de la liste blanche lorsque channels.googlechat.dangerouslyAllowNameMatching: true.
Déconseillé : users/<email> est traité comme un identifiant utilisateur, et non comme une liste blanche d’e-mails.
Espaces : spaces/<spaceId>.

Points forts de la configuration

{
  channels: {
    googlechat: {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      // or serviceAccountRef: { source: "file", provider: "filemain", id: "/channels/googlechat/serviceAccount" }
      audienceType: "app-url",
      audience: "https://gateway.example.com/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890", // optional; helps mention detection
      allowBots: false,
      dm: {
        policy: "pairing",
        allowFrom: ["users/1234567890"],
      },
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA": {
          enabled: true,
          requireMention: true,
          users: ["users/1234567890"],
          systemPrompt: "Short answers only.",
        },
      },
      actions: { reactions: true },
      typingIndicator: "message",
      mediaMaxMb: 20,
    },
  },
}

Notes :

Les identifiants du compte de service peuvent également être transmis en ligne avec serviceAccount (chaîne JSON).
serviceAccountRef est également pris en charge (SecretRef env/fichier), y compris les références par compte sous channels.googlechat.accounts.<id>.serviceAccountRef.
Le chemin du webhook par défaut est /googlechat si webhookPath n’est pas défini.
dangerouslyAllowNameMatching réactive la correspondance de principal d’e-mail modifiable pour les listes blanches (mode de compatibilité de secours).
Les réactions sont disponibles via l’outil reactions et channels action lorsque actions.reactions est activé.
Les actions de message exposent send pour le texte et upload-file pour l’envoi explicite de pièces jointes. upload-file accepte media / filePath / path ainsi que message, filename optionnels, et le ciblage de fils de discussion.
typingIndicator prend en charge none, message (par défaut), et reaction (la réaction nécessite un OAuth utilisateur).
Les pièces jointes sont téléchargées via le Chat API et stockées dans le pipeline multimédia (taille limitée par mediaMaxMb).
Les messages Google Chat créés par des bots sont ignorés par défaut. Si vous définissez intentionnellement Google ChatallowBots: true, les messages acceptés créés par des bots utilisent la protection commune contre les boucles de bots. Configurez channels.defaults.botLoopProtection, puis remplacez avec channels.googlechat.botLoopProtection ou channels.googlechat.groups.<space>.botLoopProtection lorsqu’un espace a besoin d’un budget différent.

Détails de référence des secrets : Gestion des secrets.

Dépannage

405 Method Not Allowed

Si l’explorateur de journaux Google Cloud affiche des erreurs telles que :

status code: 405, reason phrase: HTTP error response: HTTP/1.1 405 Method Not Allowed

Cela signifie que le gestionnaire de webhook n’est pas enregistré. Causes courantes :

Channel non configuré : La section channels.googlechat est manquante dans votre configuration. Vérifiez avec :
Fenêtre de terminal
```
openclaw config get channels.googlechat
```
S’il renvoie “Config path not found”, ajoutez la configuration (voir Points forts de la configuration).
Plugin non activé : Vérifiez l’état du plugin :
Fenêtre de terminal
```
openclaw plugins list | grep googlechat
```
S’il affiche “disabled”, ajoutez plugins.entries.googlechat.enabled: true à votre configuration.
Gateway non redémarré : Après avoir ajouté la configuration, redémarrez la passerelle :
Fenêtre de terminal
```
openclaw gateway restart
```

Vérifiez que le channel fonctionne :

openclaw channels status
# Should show: Google Chat default: enabled, configured, ...

Autres problèmes

Vérifiez openclaw channels status --probe pour les erreurs d’authentification ou la configuration manquante de l’audience.
Si aucun message n’arrive, confirmez l’URL du webhook de l’application Chat + les abonnements aux événements.
Si le blocage par mention empêche les réponses, définissez botUser sur le nom de la ressource utilisateur de l’application et vérifiez requireMention.
Utilisez openclaw logs --follow lors de l’envoi d’un message de test pour voir si les requêtes atteignent la passerelle.

Documentation connexe :

Connexes

Vue d’ensemble des channels — tous les channels pris en charge
Appairage — authentification DM et flux d’appairage
Groupes — comportement de la conversation de groupe et filtrage des mentions
Routage de canal — routage de session pour les messages
Sécurité — modèle d’accès et durcissement