> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Chat

Stato: Plugin scaricabile per DM + spazi tramite Webhook dell'API Google Chat (solo HTTP).

## Installazione

Installa Google Chat prima di configurare il canale:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw plugins install @openclaw/googlechat
```

Checkout locale (quando eseguito da un repository git):

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw plugins install ./path/to/local/googlechat-plugin
```

## Configurazione rapida (principianti)

1. Crea un progetto Google Cloud e abilita la **Google Chat API**.
   * Vai a: [Credenziali Google Chat API](https://console.cloud.google.com/apis/api/chat.googleapis.com/credentials)
   * Abilita l'API se non è già abilitata.
2. Crea un **Service Account**:
   * Premi **Create Credentials** > **Service Account**.
   * Assegnagli il nome che preferisci (ad es. `openclaw-chat`).
   * Lascia vuote le autorizzazioni (premi **Continue**).
   * Lascia vuoti i principali con accesso (premi **Done**).
3. Crea e scarica la **chiave JSON**:
   * Nell'elenco dei service account, fai clic su quello appena creato.
   * Vai alla scheda **Keys**.
   * Fai clic su **Add Key** > **Create new key**.
   * Seleziona **JSON** e premi **Create**.
4. Archivia il file JSON scaricato sull'host del Gateway (ad es. `~/.openclaw/googlechat-service-account.json`).
5. Crea un'app Google Chat nella [Configurazione Chat di Google Cloud Console](https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat):
   * Compila le **informazioni sull'applicazione**:
     * **Nome app**: (ad es. `OpenClaw`)
     * **URL avatar**: (ad es. `https://openclaw.ai/logo.png`)
     * **Descrizione**: (ad es. `Assistente AI personale`)
   * Abilita le **funzionalità interattive**.
   * In **Funzionalità**, seleziona **Partecipa a spazi e conversazioni di gruppo**.
   * In **Impostazioni di connessione**, seleziona **URL endpoint HTTP**.
   * In **Trigger**, seleziona **Usa un URL endpoint HTTP comune per tutti i trigger** e impostalo sull'URL pubblico del tuo Gateway seguito da `/googlechat`.
     * *Suggerimento: esegui `openclaw status` per trovare l'URL pubblico del tuo Gateway.*
   * In **Visibilità**, seleziona **Rendi questa app Chat disponibile a persone e gruppi specifici in `<Your Domain>`**.
   * Inserisci il tuo indirizzo email (ad es. `user@example.com`) nella casella di testo.
   * Fai clic su **Save** in basso.
6. **Abilita lo stato dell'app**:
   * Dopo il salvataggio, **aggiorna la pagina**.
   * Cerca la sezione **Stato app** (di solito vicino alla parte superiore o inferiore dopo il salvataggio).
   * Cambia lo stato in **Live - available to users**.
   * Fai di nuovo clic su **Save**.
7. 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"`.
8. Imposta il tipo e il valore dell'audience del Webhook (corrispondono alla configurazione della tua app Chat).
9. Avvia il Gateway. Google Chat invierà POST al tuo percorso Webhook.

## Aggiungere a Google Chat

Quando il Gateway è in esecuzione e la tua email è stata aggiunta all'elenco di visibilità:

1. Vai a [Google Chat](https://chat.google.com/).
2. Fai clic sull'icona **+** (più) accanto a **Direct Messages**.
3. Nella barra di ricerca (dove di solito aggiungi persone), digita il **nome dell'app** configurato in Google Cloud Console.
   * **Nota**: il bot *non* comparirà nell'elenco di navigazione "Marketplace" perché è un'app privata. Devi cercarlo per nome.
4. Seleziona il tuo bot dai risultati.
5. Fai clic su **Add** o **Chat** per avviare una conversazione 1:1.
6. Invia "Ciao" per attivare l'assistente.

## URL pubblico (solo Webhook)

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

### Opzione A: Tailscale Funnel (consigliata)

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

1. **Controlla a quale indirizzo è associato il Gateway:**

   ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
   ss -tlnp | grep 18789
   ```

   Prendi nota dell'indirizzo IP (ad es. `127.0.0.1`, `0.0.0.0` o il tuo IP Tailscale come `100.x.x.x`).

2. **Esponi la dashboard solo alla tailnet (porta 8443):**

   ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
   # 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
   ```

3. **Esponi pubblicamente solo il percorso Webhook:**

   ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
   # 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
   ```

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

5. **Verifica la configurazione:**

   ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
   tailscale serve status
   tailscale funnel status
   ```

Il tuo URL Webhook pubblico sarà:
`https://<node-name>.<tailnet>.ts.net/googlechat`

La tua dashboard privata rimane 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 dopo i riavvii. Per rimuoverla in seguito, esegui `tailscale funnel reset` e `tailscale serve reset`.

### Opzione B: proxy inverso (Caddy)

Se usi un proxy inverso come Caddy, instrada tramite proxy solo il percorso specifico:

```caddy theme={"theme":{"light":"min-light","dark":"min-dark"}}
your-domain.com {
    reverse_proxy /googlechat* localhost:18789
}
```

Con questa configurazione, qualsiasi richiesta a `your-domain.com/` verrà ignorata o restituirà 404, mentre `your-domain.com/googlechat` viene instradata in modo sicuro a OpenClaw.

### Opzione C: Cloudflare Tunnel

Configura le regole di ingresso del tunnel in modo da instradare solo il percorso Webhook:

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

## Come funziona

1. Google Chat invia POST Webhook al Gateway. Ogni richiesta include un'intestazione `Authorization: Bearer <token>`.
   * OpenClaw verifica l'autenticazione bearer prima di leggere/analizzare i corpi completi dei Webhook quando l'intestazione è presente.
   * Le richieste Google Workspace Add-on che contengono `authorizationEventObject.systemIdToken` nel corpo sono supportate tramite un budget del corpo pre-auth più rigoroso.
2. OpenClaw verifica il token rispetto a `audienceType` + `audience` configurati:
   * `audienceType: "app-url"` → l'audience è il tuo URL Webhook HTTPS.
   * `audienceType: "project-number"` → l'audience è il numero del progetto Cloud.
3. I messaggi vengono 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>`.
4. L'accesso ai DM usa il pairing per impostazione predefinita. I mittenti sconosciuti ricevono un codice di pairing; approva con:
   * `openclaw pairing approve googlechat <code>`
5. Gli spazi di gruppo richiedono una @-menzione per impostazione predefinita. Usa `botUser` se il rilevamento delle menzioni richiede il nome utente dell'app.
6. Quando una richiesta di approvazione exec o Plugin parte da Google Chat e viene configurato un approvatore stabile `users/<id>`, OpenClaw pubblica una scheda di approvazione nativa di Google Chat nello spazio o nel thread di origine. I pulsanti della scheda usano token di callback opachi e il prompt manuale `/approve <id> <decision>` viene mostrato solo quando la consegna dell'approvazione nativa non è disponibile.

## Destinazioni

Usa questi identificatori per consegna e allowlist:

* Messaggi diretti: `users/<userId>` (consigliato).
* L'email grezza `name@example.com` è mutabile e viene usata solo per la corrispondenza diretta con l'allowlist quando `channels.googlechat.dangerouslyAllowNameMatching: true`.
* Deprecato: `users/<email>` viene trattato come ID utente, non come allowlist email.
* Spazi: `spaces/<spaceId>`.

## Punti salienti della configurazione

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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,
    },
  },
}
```

Note:

* Le credenziali del service account possono anche essere passate inline con `serviceAccount` (stringa JSON).
* È supportato anche `serviceAccountRef` (env/file SecretRef), inclusi i riferimenti per account in `channels.googlechat.accounts.<id>.serviceAccountRef`.
* Il percorso Webhook predefinito è `/googlechat` se `webhookPath` non è impostato.
* `dangerouslyAllowNameMatching` riabilita la corrispondenza dei principal email mutabili per le allowlist (modalità di compatibilità break-glass).
* Le reazioni sono disponibili tramite lo strumento `reactions` e `channels action` quando `actions.reactions` è abilitato.
* Le schede di approvazione native usano clic sui pulsanti `cardsV2` di Google Chat, non eventi di reazione. Gli approvatori provengono da `dm.allowFrom` o `defaultTo` e devono essere valori numerici stabili `users/<id>`.
* Le azioni messaggio espongono `send` per il testo e `upload-file` per invii espliciti di allegati. `upload-file` accetta `media` / `filePath` / `path` più `message`, `filename` e destinazione thread opzionali.
* `typingIndicator` supporta `message` (predefinito), `none` e `reaction` (la reazione richiede OAuth utente).
* Gli allegati vengono scaricati tramite la Chat API e archiviati nella pipeline multimediale (dimensione limitata da `mediaMaxMb`).
* I messaggi Google Chat creati da bot vengono ignorati per impostazione predefinita. Se imposti intenzionalmente `allowBots: true`, i messaggi creati da bot accettati usano la [protezione dai loop dei bot](/it/channels/bot-loop-protection) condivisa. Configura `channels.defaults.botLoopProtection`, poi sovrascrivi con `channels.googlechat.botLoopProtection` o `channels.googlechat.groups.<space>.botLoopProtection` quando uno spazio richiede un budget diverso.

Dettagli riferimento segreti: [Gestione dei segreti](/it/gateway/secrets).

## Risoluzione dei 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 il gestore Webhook non è registrato. Cause comuni:

1. **Canale non configurato**: la sezione `channels.googlechat` manca dalla tua configurazione. Verifica con:

   ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
   openclaw config get channels.googlechat
   ```

   Se restituisce "Config path not found", aggiungi la configurazione (vedi [Punti salienti della configurazione](#config-highlights)).

2. **Plugin non abilitato**: controlla lo stato del Plugin:

   ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
   openclaw plugins list | grep googlechat
   ```

   Se mostra "disabled", aggiungi `plugins.entries.googlechat.enabled: true` alla tua configurazione.

3. **Gateway non riavviato**: dopo aver aggiunto la configurazione, riavvia il Gateway:

   ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
   openclaw gateway restart
   ```

Verifica che il canale sia in esecuzione:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw channels status
# Should show: 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 agli eventi.
* Se il gating delle menzioni blocca le risposte, imposta `botUser` sul nome risorsa utente dell'app e verifica `requireMention`.
* Usa `openclaw logs --follow` mentre invii un messaggio di prova per vedere se le richieste raggiungono il Gateway.

Documentazione correlata:

* [Configurazione del Gateway](/it/gateway/configuration)
* [Sicurezza](/it/gateway/security)
* [Reazioni](/it/tools/reactions)

## Correlati

* [Panoramica dei canali](/it/channels) — tutti i canali supportati
* [Associazione](/it/channels/pairing) — autenticazione DM e flusso di associazione
* [Gruppi](/it/channels/groups) — comportamento delle chat di gruppo e controllo tramite menzioni
* [Instradamento dei canali](/it/channels/channel-routing) — instradamento delle sessioni per i messaggi
* [Sicurezza](/it/gateway/security) — modello di accesso e irrobustimento