Google Chat (Chat API)

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

Schnellstart (für Einsteiger)

Erstelle ein Google Cloud-Projekt und aktiviere die Google Chat API.
- Gehe zu: Google Chat API Credentials
- Aktiviere die API, falls sie noch nicht aktiviert ist.
Erstelle einen Service Account:
- Klicke auf Create Credentials > Service Account.
- Gib einen beliebigen Namen ein (z. B. openclaw-chat).
- Lass die Berechtigungen leer (klicke auf Continue).
- Lass die Principals leer (klicke auf Done).
Erstelle und lade den JSON Key herunter:
- Klicke in der Liste der Service Accounts auf den gerade erstellten Account.
- Gehe zum Tab Keys.
- Klicke auf Add Key > Create new key.
- Wähle JSON und klicke auf 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 die URL 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.
Aktiviere den App-Status:
- 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 und der Webhook-Audience:
- Env: GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json
- Oder Config: channels.googlechat.serviceAccountFile: "/path/to/service-account.json".
Setze den Webhook-Audience-Typ und -Wert (muss mit deiner Chat-App-Konfiguration übereinstimmen).
Starte das Gateway. Google Chat sendet dann POST-Requests an deinen Webhook-Pfad.

Zu Google Chat hinzufügen

Sobald das Gateway läuft und deine E-Mail zur Visibility-Liste hinzugefügt wurde:

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

Öffentliche URL (nur Webhook)

Google Chat Webhooks benötigen einen öffentlichen HTTPS-Endpunkt. Aus Sicherheitsgründen solltest du nur den /googlechat-Pfad ins Internet freigeben. Das OpenClaw-Dashboard und andere sensible Endpunkte bleiben in deinem privaten Netzwerk.

Option A: Tailscale Funnel (empfohlen)

Nutze Tailscale Serve für das private Dashboard und Funnel für den öffentlichen Webhook-Pfad. So bleibt / privat, während nur /googlechat öffentlich erreichbar ist.

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).

Stelle das Dashboard nur im Tailnet bereit (Port 8443):

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

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

Stelle nur den Webhook-Pfad öffentlich bereit:

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

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

Autorisiere den Node für Funnel-Zugriff: Falls du dazu aufgefordert wirst, besuche die angezeigte Autorisierungs-URL, um Funnel für diesen Node in deiner Tailnet-Policy zu aktivieren.

Überprüfe die Konfiguration:

tailscale serve status
tailscale funnel status

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

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

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

Hinweis: Diese Konfiguration bleibt nach Neustarts erhalten. Um sie später zu entfernen, führe tailscale funnel reset und tailscale serve reset aus.

Option B: Reverse Proxy (Caddy)

Falls du einen Reverse Proxy wie Caddy verwendest, leite nur den spezifischen Pfad weiter:

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

Mit dieser Konfiguration werden Anfragen an your-domain.com/ ignoriert oder als 404 zurückgegeben, während your-domain.com/googlechat sicher zu OpenClaw geleitet wird.

Option C: Cloudflare Tunnel

Konfiguriere die Ingress-Regeln deines Tunnels so, dass nur der Webhook-Pfad weitergeleitet wird:

Path: /googlechat -> http://localhost:18789/googlechat
Default Rule: HTTP 404 (Not Found)

So funktioniert es

Google Chat sendet Webhook-POSTs an das Gateway. Jede Anfrage enthält einen Authorization: Bearer <token>-Header.
OpenClaw verifiziert den Token gegen den konfigurierten audienceType und 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-Key agent:<agentId>:googlechat:dm:<spaceId>.
- Spaces verwenden den Session-Key agent:<agentId>:googlechat:group:<spaceId>.
DM-Zugriff erfolgt standardmäßig über Pairing. Unbekannte Absender erhalten einen Pairing-Code; genehmige ihn mit:
- openclaw pairing approve googlechat <code>
Gruppen-Spaces erfordern standardmäßig eine @-Erwähnung. Verwende botUser, falls die Erwähnungserkennung den Benutzernamen der App benötigt.

Targets

Verwende diese Identifikatoren für Zustellung und Allowlists:

Direktnachrichten: users/<userId> oder users/<email> (E-Mail-Adressen werden akzeptiert).
Spaces: spaces/<spaceId>.

Konfigurations-Highlights

{
  channels: {
    googlechat: {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      audienceType: "app-url",
      audience: "https://gateway.example.com/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890", // optional; hilft bei der Erwähnungserkennung
      dm: {
        policy: "pairing",
        allowFrom: ["users/1234567890", "[email protected]"],
      },
      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-Credentials können auch inline mit serviceAccount (JSON-String) übergeben werden.
Der Standard-Webhook-Pfad ist /googlechat, falls webhookPath nicht gesetzt ist.
Reactions sind über das reactions-Tool und channels action verfügbar, wenn actions.reactions aktiviert ist.
typingIndicator unterstützt none, message (Standard) und reaction (reaction erfordert User-OAuth).
Anhänge werden über die Chat API heruntergeladen und in der Media-Pipeline gespeichert (Größe begrenzt durch mediaMaxMb).

Troubleshooting

405 Method Not Allowed

Falls der Google Cloud Logs Explorer Fehler wie diesen anzeigt:

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

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

Channel nicht konfiguriert: Der Abschnitt channels.googlechat fehlt in deiner Config. Überprüfe das mit:
```
openclaw config get channels.googlechat
```
Falls “Config path not found” zurückgegeben wird, füge die Konfiguration hinzu (siehe Konfigurations-Highlights).
Plugin nicht aktiviert: Prüfe den Plugin-Status:
```
openclaw plugins list | grep googlechat
```
Falls “disabled” angezeigt wird, füge plugins.entries.googlechat.enabled: true zu deiner Config hinzu.
Gateway nicht neu gestartet: Nach dem Hinzufügen der Config starte das Gateway neu:
```
openclaw gateway restart
```

Überprüfe, ob der Channel läuft:

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

Weitere Probleme

Prüfe openclaw channels status --probe auf Auth-Fehler oder fehlende Audience-Konfiguration.
Falls keine Nachrichten ankommen, bestätige die Webhook-URL und Event-Subscriptions der Chat-App.
Falls Mention-Gating Antworten blockiert, setze botUser auf den User-Ressourcennamen der App und überprüfe requireMention.
Verwende openclaw logs --follow, während du eine Testnachricht sendest, um zu sehen, ob Anfragen das Gateway erreichen.

Verwandte Dokumentation: