Google Chat (Chat API)

Status: Bereit für DMs + Spaces via Google Chat API Webhooks (nur HTTP).

Schnelleinrichtung (Einsteiger)

Erstelle ein Google Cloud-Projekt und aktiviere die Google Chat API.
- Gehe zu: Google Chat API Credentials
- Aktiviere die API, falls noch nicht aktiviert.
Erstelle ein Service Account:
- Klicke auf Create Credentials > Service Account.
- Benenne es beliebig (z. B. openclaw-chat).
- Berechtigungen leer lassen (klicke Continue).
- Principals mit Zugriff leer lassen (klicke Done).
Erstelle und lade den JSON Key herunter:
- Klicke in der Liste der Service Accounts auf den gerade erstellten.
- Gehe zum Tab Keys.
- Klicke Add Key > Create new key.
- Wähle JSON und klicke Create.
Speichere die heruntergeladene JSON-Datei auf deinem Gateway-Host (z. B. ~/.openclaw/googlechat-service-account.json).
Erstelle eine Google Chat App in der Google Cloud Console Chat Configuration:
- Fülle die Application info aus:
  - App name: (z. B. OpenClaw)
  - Avatar URL: (z. B. https://openclaw.ai/logo.png)
  - Description: (z. B. Personal AI Assistant)
- Aktiviere Interactive features.
- Unter Functionality aktiviere Join spaces and group conversations.
- Unter Connection settings wähle HTTP endpoint URL.
- Unter Triggers wähle Use a common HTTP endpoint URL for all triggers und setze sie auf die öffentliche URL deines Gateways gefolgt von /googlechat.
  - Tipp: Führe openclaw status aus, um die öffentliche URL deines Gateways zu finden.
- Unter Visibility aktiviere Make this Chat app available to specific people and groups in <Your Domain>.
- Gib deine E-Mail-Adresse ein (z. B. [email protected]).
- Klicke unten auf Save.
App-Status aktivieren:
- Nach dem Speichern aktualisiere die Seite.
- Suche den Abschnitt App status (normalerweise oben oder unten nach dem Speichern).
- Ändere den Status auf Live - available to users.
- Klicke erneut auf Save.
Konfiguriere OpenClaw mit dem Service-Account-Pfad + Webhook-Audience:
- Umgebungsvariable: GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json
- Oder Konfiguration: channels.googlechat.serviceAccountFile: "/path/to/service-account.json".
Setze den Webhook-Audience-Typ + -Wert (passend zu deiner Chat-App-Konfiguration).
Starte das Gateway. Google Chat sendet POSTs an deinen Webhook-Pfad.

Zu Google Chat hinzufügen

Sobald das Gateway läuft und deine E-Mail-Adresse zur Sichtbarkeitsliste hinzugefügt ist:

Gehe zu Google Chat.
Klicke auf das + (Plus)-Symbol neben Direct Messages.
Tippe in der Suchleiste (wo du normalerweise Personen hinzufügst) den App-Namen ein, den du in der Google Cloud Console konfiguriert hast.
- Hinweis: Der Bot erscheint nicht in der Marketplace-Suchliste, da es eine private App ist. Du musst nach dem Namen suchen.
Wähle deinen Bot aus den Ergebnissen.
Klicke Add oder Chat, um eine 1:1-Unterhaltung zu starten.
Sende „Hello”, um den Assistenten auszulösen!

Öffentliche URL (nur Webhook)

Google Chat Webhooks erfordern einen öffentlichen HTTPS-Endpunkt. Aus Sicherheitsgründen exponiere nur den /googlechat-Pfad ins Internet. Halte das OpenClaw-Dashboard und andere sensible Endpunkte in deinem privaten Netzwerk.

Option A: Tailscale Funnel (empfohlen)

Verwende Tailscale Serve für das private Dashboard und Funnel für den öffentlichen Webhook-Pfad. So bleibt / privat, während nur /googlechat exponiert wird.

Prüfe, an welche Adresse dein Gateway gebunden ist:
```
ss -tlnp | grep 18789
```
Notiere die IP-Adresse (z. B. 127.0.0.1, 0.0.0.0 oder deine Tailscale-IP wie 100.x.x.x).

Dashboard nur für das Tailnet exponieren (Port 8443):

# Bei Binding an localhost (127.0.0.1 oder 0.0.0.0):
tailscale serve --bg --https 8443 http://127.0.0.1:18789

# Bei Binding nur an Tailscale-IP (z. B. 100.106.161.80):
tailscale serve --bg --https 8443 http://100.106.161.80:18789

Nur den Webhook-Pfad öffentlich exponieren:

# Bei Binding an localhost (127.0.0.1 oder 0.0.0.0):
tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat

# Bei Binding nur an Tailscale-IP (z. B. 100.106.161.80):
tailscale funnel --bg --set-path /googlechat http://100.106.161.80:18789/googlechat

Node für Funnel-Zugriff autorisieren: Wenn aufgefordert, besuche die im Output angezeigte Autorisierungs-URL, um Funnel für diesen Node in deiner Tailnet-Policy zu aktivieren.

Konfiguration prüfen:

tailscale serve status
tailscale funnel status

Deine öffentliche Webhook-URL wird sein: https://<node-name>.<tailnet>.ts.net/googlechat

Dein privates Dashboard bleibt nur im Tailnet: https://<node-name>.<tailnet>.ts.net:8443/

Verwende die öffentliche URL (ohne :8443) in der Google Chat App-Konfiguration.

Hinweis: Diese Konfiguration bleibt über Neustarts bestehen. Zum späteren Entfernen führe tailscale funnel reset und tailscale serve reset aus.

Option B: Reverse Proxy (Caddy)

Wenn du einen Reverse Proxy wie Caddy verwendest, proxy nur den spezifischen Pfad:

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

Mit dieser Konfiguration wird jede Anfrage an your-domain.com/ ignoriert oder als 404 zurückgegeben, während your-domain.com/googlechat sicher an OpenClaw weitergeleitet wird.

Option C: Cloudflare Tunnel

Konfiguriere die Ingress-Regeln deines Tunnels, um nur den Webhook-Pfad weiterzuleiten:

Pfad: /googlechat -> http://localhost:18789/googlechat
Standardregel: HTTP 404 (Not Found)

Funktionsweise

Google Chat sendet Webhook-POSTs an das Gateway. Jede Anfrage enthält einen Authorization: Bearer <token>-Header.
- OpenClaw prüft die Bearer-Auth, bevor vollständige Webhook-Bodies gelesen/geparst werden, wenn der Header vorhanden ist.
- Google Workspace Add-on-Anfragen, die authorizationEventObject.systemIdToken im Body enthalten, werden über ein strengeres Pre-Auth-Body-Budget unterstützt.
OpenClaw verifiziert den Token gegen den konfigurierten audienceType + audience:
- audienceType: "app-url" -> Audience ist deine HTTPS-Webhook-URL.
- audienceType: "project-number" -> Audience ist die Cloud-Projektnummer.
Nachrichten werden nach Space geroutet:
- DMs verwenden den Session-Schlüssel agent:<agentId>:googlechat:direct:<spaceId>.
- Spaces verwenden den Session-Schlüssel agent:<agentId>:googlechat:group:<spaceId>.
DM-Zugang ist standardmäßig Pairing. Unbekannte Absender erhalten einen Pairing-Code; genehmige mit:
- openclaw pairing approve googlechat <code>
Gruppen-Spaces erfordern standardmäßig @Mention. Verwende botUser, wenn die Mention-Erkennung den App-Benutzernamen benötigt.

Ziele

Verwende diese Bezeichner für Zustellung und Allowlists:

Direktnachrichten: users/<userId> (empfohlen).
Roh-E-Mail [email protected] ist veränderlich und wird nur für direktes Allowlist-Matching verwendet, wenn channels.googlechat.dangerouslyAllowNameMatching: true.
Veraltet: users/<email> wird als Benutzer-ID behandelt, nicht als E-Mail-Allowlist.
Spaces: spaces/<spaceId>.

Konfigurationsübersicht

{
  channels: {
    googlechat: {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      // oder serviceAccountRef: { source: "file", provider: "filemain", id: "/channels/googlechat/serviceAccount" }
      audienceType: "app-url",
      audience: "https://gateway.example.com/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890", // optional; hilft bei der Mention-Erkennung
      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,
    },
  },
}

Hinweise:

Service-Account-Zugangsdaten können auch inline mit serviceAccount (JSON-String) übergeben werden.
serviceAccountRef wird ebenfalls unterstützt (Umgebungsvariable/Datei SecretRef), einschließlich Pro-Konto-Refs unter channels.googlechat.accounts.<id>.serviceAccountRef.
Standard-Webhook-Pfad ist /googlechat, wenn webhookPath nicht gesetzt ist.
dangerouslyAllowNameMatching aktiviert erneut das veränderliche E-Mail-Principal-Matching für Allowlists (Notfall-Kompatibilitätsmodus).
Reaktionen sind über das reactions-Tool und channels action verfügbar, wenn actions.reactions aktiviert ist.
typingIndicator unterstützt none, message (Standard) und reaction (Reaktion erfordert User OAuth).
Anhänge werden über die Chat API heruntergeladen und in der Medien-Pipeline gespeichert (Größe begrenzt durch mediaMaxMb).

Details zur Secrets-Referenz: Secrets Management.

Fehlerbehebung

405 Method Not Allowed

Wenn der Google Cloud Logs Explorer Fehler wie diese zeigt:

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

bedeutet das, dass der Webhook-Handler nicht registriert ist. Häufige Ursachen:

Kanal nicht konfiguriert: Der Abschnitt channels.googlechat fehlt in deiner Konfiguration. Prüfe mit:
```
openclaw config get channels.googlechat
```
Wenn „Config path not found” zurückgegeben wird, füge die Konfiguration hinzu (siehe Konfigurationsübersicht).
Plugin nicht aktiviert: Plugin-Status prüfen:
```
openclaw plugins list | grep googlechat
```
Wenn „disabled” angezeigt wird, füge plugins.entries.googlechat.enabled: true zu deiner Konfiguration hinzu.
Gateway nicht neu gestartet: Starte nach dem Hinzufügen der Konfiguration das Gateway neu:
```
openclaw gateway restart
```

Prüfe, ob der Kanal läuft:

openclaw channels status
# Sollte zeigen: Google Chat default: enabled, configured, ...

Andere Probleme

Prüfe openclaw channels status --probe auf Authentifizierungsfehler oder fehlende Audience-Konfiguration.
Wenn keine Nachrichten ankommen, bestätige die Webhook-URL + Event-Abonnements der Chat-App.
Wenn Mention-Gating Antworten blockiert, setze botUser auf den App-Benutzer-Ressourcennamen und prüfe requireMention.
Verwende openclaw logs --follow beim Senden einer Testnachricht, um zu sehen, ob Anfragen beim Gateway ankommen.

Verwandte Dokumentation: