Google Chat (Chat API)

Status: gotowy do DM + przestrzeni przez webhooki Google Chat API (tylko HTTP).

Szybka konfiguracja (dla poczatkujacych)

Utworz projekt Google Cloud i wlacz Google Chat API.
- Wejdz na: Google Chat API Credentials
- Wlacz API jesli nie jest jeszcze wlaczone.
Utworz Service Account:
- Kliknij Create Credentials > Service Account.
- Nazwij jak chcesz (np. openclaw-chat).
- Pozostaw uprawnienia puste (kliknij Continue).
- Pozostaw principals z dostepem puste (kliknij Done).
Utworz i pobierz JSON Key:
- Na liscie service accounts kliknij ten, ktory wlasnie utworzyles.
- Przejdz do zakladki Keys.
- Kliknij Add Key > Create new key.
- Wybierz JSON i kliknij Create.
Zapisz pobrany plik JSON na hoscie gateway (np. ~/.openclaw/googlechat-service-account.json).
Utworz aplikacje Google Chat w Google Cloud Console Chat Configuration:
- Wypelnij Application info:
  - App name: (np. OpenClaw)
  - Avatar URL: (np. https://openclaw.ai/logo.png)
  - Description: (np. Personal AI Assistant)
- Wlacz Interactive features.
- W sekcji Functionality zaznacz Join spaces and group conversations.
- W sekcji Connection settings wybierz HTTP endpoint URL.
- W sekcji Triggers wybierz Use a common HTTP endpoint URL for all triggers i ustaw na publiczny URL twojego gateway z dolaczonym /googlechat.
  - Wskazowka: Uruchom openclaw status aby znalezc publiczny URL twojego gateway.
- W sekcji Visibility zaznacz Make this Chat app available to specific people and groups in <Your Domain>.
- Wpisz swoj adres email (np. [email protected]) w pole tekstowe.
- Kliknij Save na dole.
Wlacz status aplikacji:
- Po zapisaniu odswiez strone.
- Znajdz sekcje App status (zwykle blisko gory lub dolu po zapisaniu).
- Zmien status na Live - available to users.
- Kliknij Save ponownie.
Skonfiguruj OpenClaw ze sciezka service account + audience webhooka:
- Zmienna: GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json
- Lub konfiguracja: channels.googlechat.serviceAccountFile: "/path/to/service-account.json".
Ustaw typ i wartosc audience webhooka (pasujace do konfiguracji twojej aplikacji Chat).
Uruchom gateway. Google Chat bedzie wyslylac POST-y na sciezke webhooka.

Dodawanie do Google Chat

Gdy gateway dziala i twoj email jest na liscie widocznosci:

Wejdz na Google Chat.
Kliknij ikone + (plus) obok Direct Messages.
W pasku wyszukiwania (gdzie zwykle dodajesz osoby) wpisz App name skonfigurowana w Google Cloud Console.
- Uwaga: Bot nie pojawi sie w liscie przegladania “Marketplace”, poniewaz jest prywatna aplikacja. Musisz wyszukac go po nazwie.
Wybierz bota z wynikow.
Kliknij Add lub Chat aby rozpoczac rozmowe 1:1.
Wyslij “Hello” aby uruchomic asystenta!

Publiczny URL (tylko webhook)

Webhooki Google Chat wymagaja publicznego endpointu HTTPS. Dla bezpieczenstwa udostepnij publicznie tylko sciezke /googlechat. Przechowuj dashboard OpenClaw i inne wrazliwe endpointy w sieci prywatnej.

Opcja A: Tailscale Funnel (zalecana)

Uzyj Tailscale Serve dla prywatnego dashboardu i Funnel dla publicznej sciezki webhooka. Dzieki temu / pozostaje prywatne, a tylko /googlechat jest udostepnione.

Sprawdz, na jakim adresie jest powiazany twoj gateway:
```
ss -tlnp | grep 18789
```
Zanotuj adres IP (np. 127.0.0.1, 0.0.0.0 lub twoj IP Tailscale jak 100.x.x.x).

Udostepnij dashboard tylko w tailnet (port 8443):

# Jesli powiazany z localhost (127.0.0.1 lub 0.0.0.0):
tailscale serve --bg --https 8443 http://127.0.0.1:18789

# Jesli powiazany tylko z IP Tailscale (np. 100.106.161.80):
tailscale serve --bg --https 8443 http://100.106.161.80:18789

Udostepnij publicznie tylko sciezke webhooka:

# Jesli powiazany z localhost (127.0.0.1 lub 0.0.0.0):
tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat

# Jesli powiazany tylko z IP Tailscale (np. 100.106.161.80):
tailscale funnel --bg --set-path /googlechat http://100.106.161.80:18789/googlechat

Autoryzuj wezel dla dostepu Funnel: Jesli zostaniesz poproszony, odwiedz URL autoryzacji pokazany w danych wyjsciowych, aby wlaczyc Funnel dla tego wezla w polityce twojego tailnet.

Zweryfikuj konfiguracje:

tailscale serve status
tailscale funnel status

Twoj publiczny URL webhooka to: https://<node-name>.<tailnet>.ts.net/googlechat

Twoj prywatny dashboard pozostaje dostepny tylko w tailnet: https://<node-name>.<tailnet>.ts.net:8443/

Uzyj publicznego URL (bez :8443) w konfiguracji aplikacji Google Chat.

Uwaga: Ta konfiguracja jest trwala miedzy restartami. Aby ja pozniej usunac, uruchom tailscale funnel reset i tailscale serve reset.

Opcja B: Reverse Proxy (Caddy)

Jesli uzywasz reverse proxy takiego jak Caddy, proxyuj tylko konkretna sciezke:

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

Z ta konfiguracja zadania do your-domain.com/ beda ignorowane lub zwroca 404, a your-domain.com/googlechat jest bezpiecznie routowane do OpenClaw.

Opcja C: Cloudflare Tunnel

Skonfiguruj reguly ingress tunelu, aby routowac tylko sciezke webhooka:

Sciezka: /googlechat -> http://localhost:18789/googlechat
Regula domyslna: HTTP 404 (Not Found)

Jak dziala

Google Chat wysyla POST-y webhooka do gateway. Kazde zadanie zawiera naglowek Authorization: Bearer <token>.
- OpenClaw weryfikuje uwierzytelnianie bearer przed odczytaniem/parsowaniem pelnych cial webhooka, gdy naglowek jest obecny.
- Zadania Google Workspace Add-on zawierajace authorizationEventObject.systemIdToken w ciele sa obslugiwane przez bardziej restrykcyjny budzet ciala pre-auth.
OpenClaw weryfikuje token wobec skonfigurowanego audienceType + audience:
- audienceType: "app-url" -> audience to twoj URL webhooka HTTPS.
- audienceType: "project-number" -> audience to numer projektu Cloud.
Wiadomosci sa routowane wedlug przestrzeni:
- DM uzywaja klucza sesji agent:<agentId>:googlechat:direct:<spaceId>.
- Przestrzenie uzywaja klucza sesji agent:<agentId>:googlechat:group:<spaceId>.
Dostep DM domyslnie wymaga parowania. Nieznani nadawcy otrzymuja kod parowania; zatwierdz przez:
- openclaw pairing approve googlechat <code>
Przestrzenie grupowe domyslnie wymagaja @-wzmianki. Uzyj botUser jesli wykrywanie wzmianek potrzebuje nazwy uzytkownika aplikacji.

Cele

Uzyj tych identyfikatorow do dostarczania i list dozwolonych:

Wiadomosci bezposrednie: users/<userId> (zalecane).
Surowy email [email protected] jest zmienny i uzywany tylko do bezposredniego dopasowania listy dozwolonych gdy channels.googlechat.dangerouslyAllowNameMatching: true.
Przestarzale: users/<email> jest traktowane jako user id, nie lista dozwolonych emaili.
Przestrzenie: spaces/<spaceId>.

Wazne ustawienia konfiguracji

{
  channels: {
    googlechat: {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      // lub serviceAccountRef: { source: "file", provider: "filemain", id: "/channels/googlechat/serviceAccount" }
      audienceType: "app-url",
      audience: "https://gateway.example.com/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890", // opcjonalnie; pomaga w wykrywaniu wzmianek
      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,
    },
  },
}

Uwagi:

Dane logowania service account moga byc tez przekazane inline przez serviceAccount (ciag JSON).
serviceAccountRef jest rowniez obslugiwany (env/file SecretRef), wlacznie z ref per konto pod channels.googlechat.accounts.<id>.serviceAccountRef.
Domyslna sciezka webhooka to /googlechat jesli webhookPath nie jest ustawiony.
dangerouslyAllowNameMatching ponownie wlacza zmienne dopasowywanie principal emaila do list dozwolonych (tryb awaryjny kompatybilnosci).
Reakcje sa dostepne przez narzedzie reactions i channels action gdy actions.reactions jest wlaczone.
typingIndicator obsluguje none, message (domyslnie) i reaction (reaction wymaga OAuth uzytkownika).
Zalaczniki sa pobierane przez Chat API i przechowywane w pipeline mediow (rozmiar ograniczony przez mediaMaxMb).

Szczegoly referencji sekretow: Zarzadzanie sekretami.

Rozwiazywanie problemow

405 Method Not Allowed

Jesli Google Cloud Logs Explorer pokazuje bledy takie jak:

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

Oznacza to, ze handler webhooka nie jest zarejestrowany. Czeste przyczyny:

Kanal nie skonfigurowany: Sekcja channels.googlechat brakuje w konfiguracji. Zweryfikuj:
```
openclaw config get channels.googlechat
```
Jesli zwraca “Config path not found”, dodaj konfiguracje (zobacz Wazne ustawienia konfiguracji).
Plugin nie wlaczony: Sprawdz status pluginu:
```
openclaw plugins list | grep googlechat
```
Jesli pokazuje “disabled”, dodaj plugins.entries.googlechat.enabled: true do konfiguracji.
Gateway nie zrestartowany: Po dodaniu konfiguracji zrestartuj gateway:
```
openclaw gateway restart
```

Zweryfikuj, ze kanal dziala:

openclaw channels status
# Powinno pokazac: Google Chat default: enabled, configured, ...

Inne problemy

Sprawdz openclaw channels status --probe pod katem bledow autoryzacji lub brakujacej konfiguracji audience.
Jesli zadne wiadomosci nie docieraja, potwierdz URL webhooka aplikacji Chat + subskrypcje zdarzen.
Jesli bramkowanie wzmiankami blokuje odpowiedzi, ustaw botUser na nazwe zasobu uzytkownika aplikacji i zweryfikuj requireMention.
Uzyj openclaw logs --follow podczas wysylania testowej wiadomosci, aby sprawdzic, czy zadania docieraja do gateway.

Powiazana dokumentacja: