Google Chat (Chat API)

Stato: pronto per DM + spazi tramite webhook dell’API Google Chat (solo HTTP).

Setup rapido (principianti)

Crea un progetto Google Cloud e abilita l’API Google Chat.
- Vai su: Google Chat API Credentials
- Abilita l’API se non e gia abilitata.
Crea un Service Account:
- Premi Create Credentials > Service Account.
- Dagli il nome che vuoi (es. openclaw-chat).
- Lascia i permessi vuoti (premi Continue).
- Lascia i principal con accesso vuoti (premi Done).
Crea e scarica la chiave JSON:
- Nell’elenco dei service account, clicca su quello appena creato.
- Vai alla scheda Keys.
- Clicca Add Key > Create new key.
- Seleziona JSON e premi Create.
Salva il file JSON scaricato sull’host del gateway (es. ~/.openclaw/googlechat-service-account.json).
Crea un’app Google Chat nella Google Cloud Console Chat Configuration:
- Compila le Informazioni applicazione:
  - App name: (es. OpenClaw)
  - Avatar URL: (es. https://openclaw.ai/logo.png)
  - Description: (es. Personal AI Assistant)
- Abilita le Funzionalita interattive.
- Sotto Funzionalita, seleziona Join spaces and group conversations.
- Sotto Impostazioni di connessione, seleziona HTTP endpoint URL.
- Sotto Trigger, seleziona Use a common HTTP endpoint URL for all triggers e impostalo sull’URL pubblico del tuo gateway seguito da /googlechat.
  - Suggerimento: Esegui openclaw status per trovare l’URL pubblico del tuo gateway.
- Sotto Visibilita, seleziona Make this Chat app available to specific people and groups in <Il Tuo Dominio>.
- Inserisci il tuo indirizzo email (es. [email protected]) nella casella di testo.
- Clicca Save in basso.
Abilita lo stato dell’app:
- Dopo aver salvato, aggiorna la pagina.
- Cerca la sezione App status (di solito in alto o in basso dopo il salvataggio).
- Cambia lo stato in Live - available to users.
- Clicca Save di nuovo.
Configura OpenClaw con il percorso del service account + audience del webhook:
- Env: GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json
- Oppure config: channels.googlechat.serviceAccountFile: "/path/to/service-account.json".
Imposta il tipo di audience del webhook + valore (deve corrispondere alla configurazione della tua app Chat).
Avvia il gateway. Google Chat inviera POST al tuo percorso webhook.

Aggiungere a Google Chat

Una volta che il gateway e in esecuzione e la tua email e aggiunta alla lista di visibilita:

Vai su Google Chat.
Clicca l’icona + (piu) accanto a Messaggi diretti.
Nella barra di ricerca (dove di solito aggiungi persone), digita il nome dell’app che hai configurato nella Google Cloud Console.
- Nota: Il bot non apparira nella lista “Marketplace” perche e un’app privata. Devi cercarlo per nome.
Seleziona il tuo bot dai risultati.
Clicca Add o Chat per iniziare una conversazione 1:1.
Invia “Ciao” per attivare l’assistente!

URL pubblico (solo webhook)

I webhook di Google Chat richiedono un endpoint HTTPS pubblico. Per sicurezza, esponi solo il percorso /googlechat a internet. Mantieni la dashboard OpenClaw e altri endpoint sensibili sulla tua rete privata.

Opzione A: Tailscale Funnel (consigliato)

Usa Tailscale Serve per la dashboard privata e Funnel per il percorso webhook pubblico. Questo mantiene / privato esponendo solo /googlechat.

Verifica a quale indirizzo e associato il tuo gateway:
```
ss -tlnp | grep 18789
```
Nota l’indirizzo IP (es. 127.0.0.1, 0.0.0.0 o il tuo IP Tailscale come 100.x.x.x).

Esponi la dashboard solo alla tailnet (porta 8443):

# Se associato a localhost (127.0.0.1 o 0.0.0.0):
tailscale serve --bg --https 8443 http://127.0.0.1:18789

# Se associato solo all'IP Tailscale (es. 100.106.161.80):
tailscale serve --bg --https 8443 http://100.106.161.80:18789

Esponi solo il percorso webhook pubblicamente:

# Se associato a localhost (127.0.0.1 o 0.0.0.0):
tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat

# Se associato solo all'IP Tailscale (es. 100.106.161.80):
tailscale funnel --bg --set-path /googlechat http://100.106.161.80:18789/googlechat

Autorizza il nodo per l’accesso Funnel: Se richiesto, visita l’URL di autorizzazione mostrato nell’output per abilitare Funnel per questo nodo nella tua policy tailnet.

Verifica la configurazione:

tailscale serve status
tailscale funnel status

Il tuo URL webhook pubblico sara: https://<node-name>.<tailnet>.ts.net/googlechat

La tua dashboard privata resta accessibile solo dalla tailnet: https://<node-name>.<tailnet>.ts.net:8443/

Usa l’URL pubblico (senza :8443) nella configurazione dell’app Google Chat.

Nota: Questa configurazione persiste tra i riavvii. Per rimuoverla in seguito, esegui tailscale funnel reset e tailscale serve reset.

Opzione B: Reverse Proxy (Caddy)

Se usi un reverse proxy come Caddy, fai il proxy solo del percorso specifico:

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

Con questa configurazione, qualsiasi richiesta a your-domain.com/ sara ignorata o restituira 404, mentre your-domain.com/googlechat viene instradata correttamente a OpenClaw.

Opzione C: Cloudflare Tunnel

Configura le regole di ingresso del tuo tunnel per instradare solo il percorso webhook:

Path: /googlechat -> http://localhost:18789/googlechat
Regola predefinita: HTTP 404 (Not Found)

Come funziona

Google Chat invia POST webhook al gateway. Ogni richiesta include un header Authorization: Bearer <token>.
- OpenClaw verifica l’autenticazione bearer prima di leggere/analizzare i body completi del webhook quando l’header e presente.
- Le richieste Google Workspace Add-on che portano authorizationEventObject.systemIdToken nel body sono supportate tramite un budget body pre-autenticazione piu restrittivo.
OpenClaw verifica il token rispetto all’audienceType + audience configurati:
- audienceType: "app-url" -> audience e il tuo URL webhook HTTPS.
- audienceType: "project-number" -> audience e il numero del progetto Cloud.
I messaggi sono instradati per spazio:
- I DM usano la chiave di sessione agent:<agentId>:googlechat:direct:<spaceId>.
- Gli spazi usano la chiave di sessione agent:<agentId>:googlechat:group:<spaceId>.
L’accesso DM e in pairing per impostazione predefinita. I mittenti sconosciuti ricevono un codice di pairing; approvalo con:
- openclaw pairing approve googlechat <code>
Gli spazi di gruppo richiedono @menzione per impostazione predefinita. Usa botUser se il rilevamento menzione necessita del nome utente dell’app.

Target

Usa questi identificativi per la consegna e le allowlist:

Messaggi diretti: users/<userId> (consigliato).
L’email grezza [email protected] e mutabile e usata solo per il matching diretto dell’allowlist quando channels.googlechat.dangerouslyAllowNameMatching: true.
Deprecato: users/<email> e trattato come user id, non come allowlist email.
Spazi: spaces/<spaceId>.

Punti salienti della configurazione

{
  channels: {
    googlechat: {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      // oppure serviceAccountRef: { source: "file", provider: "filemain", id: "/channels/googlechat/serviceAccount" }
      audienceType: "app-url",
      audience: "https://gateway.example.com/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890", // opzionale; aiuta il rilevamento menzione
      dm: {
        policy: "pairing",
        allowFrom: ["users/1234567890"],
      },
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA": {
          allow: true,
          requireMention: true,
          users: ["users/1234567890"],
          systemPrompt: "Solo risposte brevi.",
        },
      },
      actions: { reactions: true },
      typingIndicator: "message",
      mediaMaxMb: 20,
    },
  },
}

Note:

Le credenziali del service account possono anche essere passate inline con serviceAccount (stringa JSON).
serviceAccountRef e supportato (SecretRef env/file), inclusi ref per account sotto channels.googlechat.accounts.<id>.serviceAccountRef.
Il percorso webhook predefinito e /googlechat se webhookPath non e impostato.
dangerouslyAllowNameMatching riabilita il matching mutabile per email principale per le allowlist (modalita di compatibilita break-glass).
Le reazioni sono disponibili tramite lo strumento reactions e channels action quando actions.reactions e abilitato.
typingIndicator supporta none, message (predefinito) e reaction (reaction richiede OAuth utente).
Gli allegati vengono scaricati tramite l’API Chat e salvati nella pipeline media (dimensione limitata da mediaMaxMb).

Dettagli riferimento segreti: Gestione segreti.

Risoluzione problemi

405 Method Not Allowed

Se Google Cloud Logs Explorer mostra errori come:

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

Significa che l’handler del webhook non e registrato. Cause comuni:

Canale non configurato: la sezione channels.googlechat manca dal config. Verifica con:
```
openclaw config get channels.googlechat
```
Se restituisce “Config path not found”, aggiungi la configurazione (vedi Punti salienti della configurazione).
Plugin non abilitato: controlla lo stato del plugin:
```
openclaw plugins list | grep googlechat
```
Se mostra “disabled”, aggiungi plugins.entries.googlechat.enabled: true al tuo config.
Gateway non riavviato: dopo aver aggiunto il config, riavvia il gateway:
```
openclaw gateway restart
```

Verifica che il canale sia in esecuzione:

openclaw channels status
# Dovrebbe mostrare: Google Chat default: enabled, configured, ...

Altri problemi

Controlla openclaw channels status --probe per errori di autenticazione o configurazione audience mancante.
Se non arrivano messaggi, conferma l’URL webhook dell’app Chat + le sottoscrizioni eventi.
Se il gating menzione blocca le risposte, imposta botUser sul nome risorsa utente dell’app e verifica requireMention.
Usa openclaw logs --follow mentre invii un messaggio di test per vedere se le richieste raggiungono il gateway.

Documentazione correlata: