Google Chat (Chat API)

Status: klaar voor DM’s + spaces via Google Chat API-webhooks (alleen HTTP).

Snelle installatie (beginner)

Maak een Google Cloud-project aan en schakel de Google Chat API in.
- Ga naar: Google Chat API Credentials
- Schakel de API in als deze nog niet is ingeschakeld.
Maak een Service Account aan:
- Druk op Create Credentials > Service Account.
- Geef het een willekeurige naam (bijv. openclaw-chat).
- Laat machtigingen leeg (druk op Continue).
- Laat principals met toegang leeg (druk op Done).
Maak de JSON-sleutel aan en download deze:
- Klik in de lijst met serviceaccounts op het account dat je zojuist hebt aangemaakt.
- Ga naar het tabblad Keys.
- Klik op Add Key > Create new key.
- Selecteer JSON en druk op Create.
Sla het gedownloade JSON-bestand op op je gatewayhost (bijv. ~/.openclaw/googlechat-service-account.json).
Maak een Google Chat-app aan in de Google Cloud Console Chat Configuration:
- Vul de Application info in:
  - App name: (bijv. OpenClaw)
  - Avatar URL: (bijv. https://openclaw.ai/logo.png)
  - Description: (bijv. Personal AI Assistant)
- Schakel Interactive features in.
- Onder Functionality, vink Join spaces and group conversations aan.
- Onder Connection settings, selecteer HTTP endpoint URL.
- Onder Triggers, selecteer Use a common HTTP endpoint URL for all triggers en stel het in op de publieke URL van je gateway gevolgd door /googlechat.
  - Tip: Voer openclaw status uit om de publieke URL van je gateway te vinden.
- Onder Visibility, vink Make this Chat app available to specific people and groups in <Your Domain> aan.
- Voer je e-mailadres in (bijv. [email protected]) in het tekstveld.
- Klik onderaan op Save.
Schakel de app-status in:
- Na het opslaan, ververs de pagina.
- Zoek het gedeelte App status (meestal bovenaan of onderaan na het opslaan).
- Wijzig de status naar Live - available to users.
- Klik opnieuw op Save.
Configureer OpenClaw met het serviceaccountpad + webhook-audience:
- Omgevingsvariabele: GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json
- Of config: channels.googlechat.serviceAccountFile: "/path/to/service-account.json".
Stel het webhook-audiencetype + waarde in (komt overeen met je Chat-appconfiguratie).
Start de gateway. Google Chat stuurt POST-verzoeken naar je webhook-pad.

Toevoegen aan Google Chat

Zodra de gateway draait en je e-mail is toegevoegd aan de zichtbaarheidslijst:

Ga naar Google Chat.
Klik op het + (plus)-icoon naast Direct Messages.
Typ in de zoekbalk (waar je normaal mensen toevoegt) de App name die je hebt geconfigureerd in de Google Cloud Console.
- Opmerking: De bot verschijnt niet in de “Marketplace”-bladenlijst omdat het een privé-app is. Je moet erop zoeken op naam.
Selecteer je bot uit de resultaten.
Klik op Add of Chat om een 1:1-gesprek te starten.
Stuur “Hello” om de assistent te activeren!

Publieke URL (alleen webhook)

Google Chat-webhooks vereisen een publiek HTTPS-eindpunt. Stel voor de beveiliging alleen het /googlechat-pad bloot aan het internet. Houd het OpenClaw-dashboard en andere gevoelige eindpunten op je privénetwerk.

Optie A: Tailscale Funnel (aanbevolen)

Gebruik Tailscale Serve voor het privédashboard en Funnel voor het publieke webhook-pad. Dit houdt / privé terwijl alleen /googlechat wordt blootgesteld.

Controleer op welk adres je gateway is gebonden:
```
ss -tlnp | grep 18789
```
Noteer het IP-adres (bijv. 127.0.0.1, 0.0.0.0 of je Tailscale-IP zoals 100.x.x.x).

Stel het dashboard alleen bloot aan het tailnet (poort 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

Stel alleen het webhook-pad publiek bloot:

# 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

Autoriseer de node voor Funnel-toegang: Bezoek als daarom gevraagd de autorisatie-URL die in de uitvoer wordt getoond om Funnel voor deze node in je tailnet-beleid in te schakelen.

Verifieer de configuratie:

tailscale serve status
tailscale funnel status

Je publieke webhook-URL wordt: https://<node-name>.<tailnet>.ts.net/googlechat

Je privédashboard blijft alleen voor het tailnet: https://<node-name>.<tailnet>.ts.net:8443/

Gebruik de publieke URL (zonder :8443) in de Google Chat-appconfiguratie.

Opmerking: Deze configuratie blijft behouden na herstarten. Om het later te verwijderen, voer je tailscale funnel reset en tailscale serve reset uit.

Optie B: Reverse Proxy (Caddy)

Als je een reverse proxy zoals Caddy gebruikt, proxy dan alleen het specifieke pad:

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

Met deze configuratie wordt elk verzoek naar your-domain.com/ genegeerd of retourneert het een 404, terwijl your-domain.com/googlechat veilig wordt doorgestuurd naar OpenClaw.

Optie C: Cloudflare Tunnel

Configureer de ingressregels van je tunnel om alleen het webhook-pad te routeren:

Pad: /googlechat -> http://localhost:18789/googlechat
Standaardregel: HTTP 404 (Not Found)

Hoe het werkt

Google Chat stuurt webhook-POST’s naar de gateway. Elk verzoek bevat een Authorization: Bearer <token>-header.
- OpenClaw verifieert bearer-authenticatie voordat volledige webhook-bodies worden gelezen/geparsed wanneer de header aanwezig is.
- Google Workspace Add-on-verzoeken die authorizationEventObject.systemIdToken in de body bevatten, worden ondersteund via een strenger pre-authenticatie body-budget.
OpenClaw verifieert het token tegen het geconfigureerde audienceType + audience:
- audienceType: "app-url" -> audience is je HTTPS webhook-URL.
- audienceType: "project-number" -> audience is het Cloud-projectnummer.
Berichten worden gerouteerd per space:
- DM’s gebruiken sessiesleutel agent:<agentId>:googlechat:direct:<spaceId>.
- Spaces gebruiken sessiesleutel agent:<agentId>:googlechat:group:<spaceId>.
DM-toegang staat standaard op koppeling. Onbekende afzenders ontvangen een koppelingscode; goedkeuren met:
- openclaw pairing approve googlechat <code>
Groepsspaces vereisen standaard een @-vermelding. Gebruik botUser als mention-detectie de gebruikersnaam van de app nodig heeft.

Doelen

Gebruik deze identifiers voor aflevering en allowlists:

Directe berichten: users/<userId> (aanbevolen).
Rauw e-mailadres [email protected] is veranderlijk en wordt alleen gebruikt voor directe allowlist-matching wanneer channels.googlechat.dangerouslyAllowNameMatching: true.
Verouderd: users/<email> wordt behandeld als een gebruikers-ID, niet als e-mail-allowlist.
Spaces: spaces/<spaceId>.

Configuratie-highlights

{
  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,
    },
  },
}

Opmerkingen:

Serviceaccount-credentials kunnen ook inline worden doorgegeven met serviceAccount (JSON-string).
serviceAccountRef wordt ook ondersteund (env/file SecretRef), inclusief per-account refs onder channels.googlechat.accounts.<id>.serviceAccountRef.
Standaard webhook-pad is /googlechat als webhookPath niet is ingesteld.
dangerouslyAllowNameMatching schakelt veranderlijke e-mail-principal-matching voor allowlists opnieuw in (noodcompatibiliteitsmodus).
Reacties zijn beschikbaar via de reactions-tool en channels action wanneer actions.reactions is ingeschakeld.
typingIndicator ondersteunt none, message (standaard) en reaction (reaction vereist gebruiker-OAuth).
Bijlagen worden gedownload via de Chat API en opgeslagen in de mediapipeline (grootte begrensd door mediaMaxMb).

Details over secretsreferenties: Secretsbeheer.

Probleemoplossing

405 Method Not Allowed

Als Google Cloud Logs Explorer fouten toont zoals:

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

Dit betekent dat de webhook-handler niet is geregistreerd. Veelvoorkomende oorzaken:

Kanaal niet geconfigureerd: Het gedeelte channels.googlechat ontbreekt in je config. Verifieer met:
```
openclaw config get channels.googlechat
```
Als het “Config path not found” retourneert, voeg dan de configuratie toe (zie Configuratie-highlights).
Plugin niet ingeschakeld: Controleer de pluginstatus:
```
openclaw plugins list | grep googlechat
```
Als het “disabled” toont, voeg dan plugins.entries.googlechat.enabled: true toe aan je config.
Gateway niet herstart: Herstart de gateway na het toevoegen van config:
```
openclaw gateway restart
```

Verifieer dat het kanaal draait:

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

Overige problemen

Controleer openclaw channels status --probe op authenticatiefouten of ontbrekende audience-config.
Als er geen berichten binnenkomen, bevestig dan de webhook-URL + eventabonnementen van de Chat-app.
Als mention-gating antwoorden blokkeert, stel dan botUser in op de gebruikersbronsnaam van de app en verifieer requireMention.
Gebruik openclaw logs --follow terwijl je een testbericht stuurt om te zien of verzoeken de gateway bereiken.

Gerelateerde documentatie: