Google Chat (Chat API)

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

Configuration rapide (debutant)

Creez un projet Google Cloud et activez l’API Google Chat.
- Rendez-vous sur : Google Chat API Credentials
- Activez l’API si elle ne l’est pas deja.
Creez un compte de service :
- Cliquez sur Creer des identifiants > Compte de service.
- Nommez-le comme vous le souhaitez (ex : openclaw-chat).
- Laissez les permissions vides (cliquez sur Continuer).
- Laissez les principals avec acces vides (cliquez sur Terminer).
Creez et telechargez la cle JSON :
- Dans la liste des comptes de service, cliquez sur celui que vous venez de creer.
- Allez dans l’onglet Cles.
- Cliquez sur Ajouter une cle > Creer une nouvelle cle.
- Selectionnez JSON et cliquez sur Creer.
Stockez le fichier JSON telecharge sur votre hote gateway (ex : ~/.openclaw/googlechat-service-account.json).
Creez une application Google Chat dans la configuration Chat de Google Cloud Console :
- Remplissez les informations de l’application :
  - Nom de l’app : (ex : OpenClaw)
  - URL de l’avatar : (ex : https://openclaw.ai/logo.png)
  - Description : (ex : Assistant IA personnel)
- Activez les fonctionnalites interactives.
- Sous Fonctionnalite, cochez Rejoindre les espaces et conversations de groupe.
- Sous Parametres de connexion, selectionnez URL de point de terminaison HTTP.
- Sous Declencheurs, selectionnez Utiliser une URL de point de terminaison HTTP commune pour tous les declencheurs et definissez-la sur l’URL publique de votre gateway suivie de /googlechat.
  - Astuce : Executez openclaw status pour trouver l’URL publique de votre gateway.
- Sous Visibilite, cochez Rendre cette application Chat disponible pour des personnes et groupes specifiques dans <Votre Domaine>.
- Entrez votre adresse email (ex : user@example.com) dans le champ.
- Cliquez sur Enregistrer en bas.
Activez le statut de l’application :
- Apres l’enregistrement, rafraichissez la page.
- Cherchez la section Statut de l’app (generalement en haut ou en bas apres l’enregistrement).
- Changez le statut en En ligne - disponible pour les utilisateurs.
- Cliquez de nouveau sur 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".
Definissez le type d’audience + la valeur du webhook (correspond a la configuration de votre application Chat).
Demarrez la gateway. Google Chat enverra des POST a votre chemin de webhook.

Ajouter a Google Chat

Une fois la gateway en cours d’execution et votre email ajoute a la liste de visibilite :

Rendez-vous sur Google Chat.
Cliquez sur l’icone + (plus) a cote de Messages directs.
Dans la barre de recherche (ou vous ajoutez habituellement des personnes), tapez le nom de l’app que vous avez configure dans la Google Cloud Console.
- Remarque : Le bot n’apparaitra pas dans la liste de navigation du “Marketplace” car c’est une application privee. Vous devez le chercher par nom.
Selectionnez votre bot dans les resultats.
Cliquez sur Ajouter ou Chat pour demarrer une conversation 1:1.
Envoyez “Bonjour” pour declencher l’assistant !

URL publique (webhook uniquement)

Les webhooks Google Chat necessitent un point de terminaison HTTPS public. Pour la securite, n’exposez que le chemin /googlechat sur Internet. Gardez le tableau de bord OpenClaw et les autres points de terminaison sensibles sur votre reseau prive.

Option A : Tailscale Funnel (recommande)

Utilisez Tailscale Serve pour le tableau de bord prive et Funnel pour le chemin de webhook public. Cela garde / prive tout en exposant uniquement /googlechat.

Verifiez a quelle adresse votre gateway est liee :
```
ss -tlnp | grep 18789
```
Notez l’adresse IP (ex : 127.0.0.1, 0.0.0.0, ou votre IP Tailscale comme 100.x.x.x).

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

# Si lie a localhost (127.0.0.1 ou 0.0.0.0) :
tailscale serve --bg --https 8443 http://127.0.0.1:18789

# Si lie uniquement a l'IP Tailscale (ex : 100.106.161.80) :
tailscale serve --bg --https 8443 http://100.106.161.80:18789

Exposez uniquement le chemin de webhook publiquement :

# Si lie a localhost (127.0.0.1 ou 0.0.0.0) :
tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat

# Si lie uniquement a l'IP Tailscale (ex : 100.106.161.80) :
tailscale funnel --bg --set-path /googlechat http://100.106.161.80:18789/googlechat

Autorisez le noeud pour l’acces Funnel : Si vous etes invite, visitez l’URL d’autorisation affichee pour activer Funnel pour ce noeud dans votre politique tailnet.

Verifiez la configuration :

tailscale serve status
tailscale funnel status

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

Votre tableau de bord prive reste accessible uniquement via le 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 entre les redemarrages. Pour la supprimer plus tard, executez tailscale funnel reset et tailscale serve reset.

Option B : Proxy inverse (Caddy)

Si vous utilisez un proxy inverse comme Caddy, ne proxyfiez que le chemin specifique :

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

Avec cette configuration, toute requete vers your-domain.com/ sera ignoree ou retournera un 404, tandis que your-domain.com/googlechat est achemine en toute securite vers OpenClaw.

Option C : Tunnel Cloudflare

Configurez les regles d’entree de votre tunnel pour ne router que le chemin de webhook :

Chemin : /googlechat -> http://localhost:18789/googlechat
Regle par defaut : HTTP 404 (Non trouve)

Fonctionnement

Google Chat envoie des POST webhook a la gateway. Chaque requete inclut un en-tete Authorization: Bearer <token>.
- OpenClaw verifie l’authentification par bearer avant de lire/analyser le corps complet du webhook quand l’en-tete est present.
- Les requetes Google Workspace Add-on qui transportent authorizationEventObject.systemIdToken dans le corps sont prises en charge via un budget pre-auth plus strict.
OpenClaw verifie le jeton par rapport a l’audienceType + audience configures :
- audienceType: "app-url" -> l’audience est votre URL webhook HTTPS.
- audienceType: "project-number" -> l’audience est le numero de projet Cloud.
Les messages sont routes par espace :
- Les DMs utilisent la cle de session agent:<agentId>:googlechat:direct:<spaceId>.
- Les espaces utilisent la cle de session agent:<agentId>:googlechat:group:<spaceId>.
L’acces DM est en mode appairage par defaut. Les expediteurs inconnus recoivent un code d’appairage ; approuvez avec :
- openclaw pairing approve googlechat <code>
Les espaces de groupe necessitent une @mention par defaut. Utilisez botUser si la detection de mention necessite le nom d’utilisateur de l’application.

Cibles

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

Messages directs : users/<userId> (recommande).
L’email brut name@example.com est mutable et n’est utilise que pour la correspondance directe de liste d’autorisation quand channels.googlechat.dangerouslyAllowNameMatching: true.
Obsolete : users/<email> est traite comme un ID utilisateur, pas une liste d’autorisation par email.
Espaces : spaces/<spaceId>.

Points cles de 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,
    },
  },
}

Remarques :

Les identifiants du compte de service peuvent aussi etre passes en ligne avec serviceAccount (chaine JSON).
serviceAccountRef est egalement pris en charge (SecretRef env/fichier), y compris les refs par compte sous channels.googlechat.accounts.<id>.serviceAccountRef.
Le chemin de webhook par defaut est /googlechat si webhookPath n’est pas defini.
dangerouslyAllowNameMatching reactive la correspondance mutable par principal email pour les listes d’autorisation (mode de compatibilite d’urgence).
Les reactions sont disponibles via l’outil reactions et channels action quand actions.reactions est active.
typingIndicator supporte none, message (par defaut) et reaction (la reaction necessite l’OAuth utilisateur).
Les pieces jointes sont telechargees via l’API Chat et stockees dans le pipeline media (taille limitee par mediaMaxMb).

Details de reference des secrets : Gestion des secrets.

Depannage

405 Method Not Allowed

Si le Google Cloud Logs Explorer affiche des erreurs comme :

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 enregistre. Causes courantes :

Canal non configure : la section channels.googlechat est absente de votre configuration. Verifiez avec :
```
openclaw config get channels.googlechat
```
Si cela retourne “Config path not found”, ajoutez la configuration (voir Points cles de configuration).
Plugin non active : verifiez le statut du plugin :
```
openclaw plugins list | grep googlechat
```
Si cela affiche “disabled”, ajoutez plugins.entries.googlechat.enabled: true a votre configuration.
Gateway non redemarree : apres l’ajout de la configuration, redemarrez la gateway :
```
openclaw gateway restart
```

Verifiez que le canal est en cours d’execution :

openclaw channels status
# Devrait afficher : Google Chat default: enabled, configured, ...

Autres problemes

Verifiez openclaw channels status --probe pour les erreurs d’authentification ou la configuration d’audience manquante.
Si aucun message n’arrive, confirmez l’URL du webhook de l’application Chat + les abonnements aux evenements.
Si le filtrage par mention bloque les reponses, definissez botUser sur le nom de ressource utilisateur de l’application et verifiez requireMention.
Utilisez openclaw logs --follow en envoyant un message de test pour voir si les requetes atteignent la gateway.

Documentations liees :