Google Chat

Google Chat (Chat API)

Statut : prêt pour les DMs + espaces via les webhooks de l’API Google Chat API (HTTP uniquement).

Configuration rapide (débutant)

Créez un projet Google Cloud et activez l’API Google Chat API.
- Accéder à : Identifiants de l’API Google Chat
- Activez l’API API si elle n’est pas déjà activée.
Créez un compte de service :
- Cliquez sur Créer des identifiants > Compte de service.
- Nommez-le comme vous le souhaitez (par exemple, openclaw-chat).
- Laissez les autorisations vides (cliquez sur Continuer).
- Laissez la section Principaux ayant accès vide (cliquez 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.
- Accédez à 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éer une application Google Chat Chat dans la Configuration de Chat de la Google Cloud Console :
- 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.
  - Conseil : 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 <Votre domaine>.
- Entrez votre adresse e-mail (par exemple [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 (correspond à 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éder à Google Chat.
Cliquez sur l’icône + (plus) à côté de Direct Messages (Messages directs).
Dans la barre de recherche (où vous ajoutez habituellement des personnes), saisissez le App name (Nom de l’application) que vous avez configuré dans la Google Cloud Console.
- Remarque : 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 démarrer une conversation 1:1.
Envoyez “Hello” (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 : Tailscale Funnel (Recommandé)

Utilisez Tailscale Serve pour le tableau de bord privé et Funnel pour le chemin du webhook public. Cela garde / 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 exemple, 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 restreint 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 ultérieurement, exécutez tailscale funnel reset et tailscale serve reset.

Option B : Proxy inverse (Caddy)

Si vous utilisez un proxy inverse comme Caddy, ne proxyfier 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é en toute sécurité vers OpenClaw.

Option C : Tunnel Cloudflare

Configurez les règles d’ingress de votre tunnel pour n’acheminer que 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 comprend un en-tête Authorization: Bearer <token>.
- OpenClaw vérifie l’authentification du porteur avant de lire/analyser les corps complets des webhooks lorsque l’en-tête est présent.
- Les requêtes de Google Workspace Add-on qui transportent 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 + audience configuré :
- 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 acheminé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 par 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 nécessite le nom d’utilisateur de l’application.

Cibles

Utilisez ces identifiants pour la livraison et les listes d’autorisation :

Messages directs : users/<userId> (recommandé).
L’e-mail brut [email protected] est modifiable et utilisé uniquement pour la correspondance directe de liste d’autorisation lorsque channels.googlechat.dangerouslyAllowNameMatching: true.
Obsolète : users/<email> est traité comme un identifiant utilisateur, et non comme une liste d’autorisation 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
      dm: {
        policy: "pairing",
        allowFrom: ["users/1234567890"],
      },
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA": {
          allow: true,
          requireMention: true,
          users: ["users/1234567890"],
          systemPrompt: "Short answers only.",
        },
      },
      actions: { reactions: true },
      typingIndicator: "message",
      mediaMaxMb: 20,
    },
  },
}

Notes :

Les identifiants de 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 par e-mail modifiable pour les listes d’autorisation (mode de compatibilité break-glass).
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 en option, et le ciblage de fils de discussion.
typingIndicator prend en charge none, message (par défaut) et reaction (la réaction nécessite le OAuth de l’utilisateur).
Les pièces jointes sont téléchargées via l’API de Chat et stockées dans le pipeline de médias (taille limitée par mediaMaxMb).

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

Dépannage

405 Method Not Allowed

Si Google Cloud Logs Explorer 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
```
Si cela 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ée : 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

Consultez openclaw channels status --probe pour détecter les erreurs d’authentification ou une configuration d’audience manquante.
Si aucun message n’arrive, vérifiez 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 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 canaux — tous les canaux pris en charge
Appairage — authentification et flux d’appairage DM
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 renforcement