English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Mainstream messaging

Google Chat

Status: Plugin do pobrania dla wiadomości bezpośrednich i pokoi przez webhooki Google Chat API (tylko HTTP).

Instalacja

Zainstaluj Google Chat przed skonfigurowaniem kanału:

openclaw plugins install @openclaw/googlechat

Lokalna kopia robocza (podczas uruchamiania z repozytorium git):

openclaw plugins install ./path/to/local/googlechat-plugin

Szybka konfiguracja (dla początkujących)

  1. Utwórz projekt Google Cloud i włącz Google Chat API.
  2. Utwórz konto usługi:
    • Naciśnij Utwórz dane uwierzytelniające > Konto usługi.
    • Nazwij je dowolnie (np. openclaw-chat).
    • Pozostaw uprawnienia puste (naciśnij Kontynuuj).
    • Pozostaw podmioty z dostępem puste (naciśnij Gotowe).
  3. Utwórz i pobierz klucz JSON:
    • Na liście kont usług kliknij to, które właśnie utworzyłeś.
    • Przejdź do karty Klucze.
    • Kliknij Dodaj klucz > Utwórz nowy klucz.
    • Wybierz JSON i naciśnij Utwórz.
  4. Zapisz pobrany plik JSON na hoście Gateway (np. ~/.openclaw/googlechat-service-account.json).
  5. Utwórz aplikację Google Chat w konfiguracji czatu Google Cloud Console:
    • Wypełnij Informacje o aplikacji:
      • Nazwa aplikacji: (np. OpenClaw)
      • Adres URL awatara: (np. https://openclaw.ai/logo.png)
      • Opis: (np. Personal AI Assistant)
    • Włącz Funkcje interaktywne.
    • W sekcji Funkcjonalność zaznacz Dołączanie do pokoi i rozmów grupowych.
    • W sekcji Ustawienia połączenia wybierz Adres URL punktu końcowego HTTP.
    • W sekcji Wyzwalacze wybierz Użyj wspólnego adresu URL punktu końcowego HTTP dla wszystkich wyzwalaczy i ustaw go na publiczny URL swojego Gateway z dodanym /googlechat.
      • Wskazówka: uruchom openclaw status, aby znaleźć publiczny URL swojego Gateway.
    • W sekcji Widoczność zaznacz Udostępnij tę aplikację Chat określonym osobom i grupom w <Your Domain>.
    • Wpisz swój adres e-mail (np. [email protected]) w polu tekstowym.
    • Kliknij Zapisz na dole.
  6. Włącz status aplikacji:
    • Po zapisaniu odśwież stronę.
    • Znajdź sekcję Status aplikacji (zwykle u góry lub u dołu po zapisaniu).
    • Zmień status na Aktywna - dostępna dla użytkowników.
    • Ponownie kliknij Zapisz.
  7. Skonfiguruj OpenClaw ze ścieżką do konta usługi i odbiorcą webhooka:
    • Env: GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json
    • Albo konfiguracja: channels.googlechat.serviceAccountFile: "/path/to/service-account.json".
  8. Ustaw typ i wartość odbiorcy webhooka (zgodne z konfiguracją aplikacji Chat).
  9. Uruchom Gateway. Google Chat będzie wysyłać żądania POST do ścieżki webhooka.

Dodawanie do Google Chat

Gdy Gateway działa, a Twój adres e-mail został dodany do listy widoczności:

  1. Przejdź do Google Chat.
  2. Kliknij ikonę + (plus) obok Wiadomości bezpośrednie.
  3. W pasku wyszukiwania (tam, gdzie zwykle dodajesz osoby) wpisz nazwę aplikacji skonfigurowaną w Google Cloud Console.
    • Uwaga: bot nie pojawi się na liście przeglądania „Marketplace”, ponieważ jest aplikacją prywatną. Musisz wyszukać go po nazwie.
  4. Wybierz bota z wyników.
  5. Kliknij Dodaj lub Czat, aby rozpocząć rozmowę 1:1.
  6. Wyślij „Hello”, aby uruchomić asystenta!

Publiczny URL (tylko Webhook)

Webhooki Google Chat wymagają publicznego punktu końcowego HTTPS. Ze względów bezpieczeństwa udostępniaj w internecie tylko ścieżkę /googlechat. Panel OpenClaw i inne wrażliwe punkty końcowe pozostaw w sieci prywatnej.

Opcja A: Tailscale Funnel (zalecane)

Użyj Tailscale Serve dla prywatnego panelu i Funnel dla publicznej ścieżki webhooka. Dzięki temu / pozostaje prywatne, a publicznie udostępnione jest tylko /googlechat.

  1. Sprawdź, z jakim adresem powiązany jest Twój Gateway:

    ss -tlnp | grep 18789

    Zanotuj adres IP (np. 127.0.0.1, 0.0.0.0 albo Twój adres IP Tailscale, taki jak 100.x.x.x).

  2. Udostępnij panel tylko w tailnet (port 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

  3. Udostępnij publicznie tylko ścieżkę webhooka:

    # 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. Autoryzuj Node do dostępu Funnel: Jeśli pojawi się monit, odwiedź URL autoryzacji widoczny w danych wyjściowych, aby włączyć Funnel dla tego Node w swojej polityce tailnet.

  5. Zweryfikuj konfigurację:

    tailscale serve status
tailscale funnel status

Twój publiczny URL webhooka będzie wyglądać tak: https://<node-name>.<tailnet>.ts.net/googlechat

Twój prywatny panel pozostaje dostępny tylko w tailnet: https://<node-name>.<tailnet>.ts.net:8443/

Użyj publicznego URL (bez :8443) w konfiguracji aplikacji Google Chat.

Uwaga: ta konfiguracja utrzymuje się po ponownych uruchomieniach. Aby usunąć ją później, uruchom tailscale funnel reset i tailscale serve reset.

Opcja B: Odwrotny proxy (Caddy)

Jeśli używasz odwrotnego proxy, takiego jak Caddy, przekierowuj tylko konkretną ścieżkę:

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

Przy tej konfiguracji każde żądanie do your-domain.com/ zostanie zignorowane albo zwróci 404, natomiast your-domain.com/googlechat zostanie bezpiecznie przekierowane do OpenClaw.

Opcja C: Cloudflare Tunnel

Skonfiguruj reguły ingress swojego tunelu tak, aby kierowały tylko ścieżkę webhooka:

  • Ścieżka: /googlechat -> http://localhost:18789/googlechat
  • Reguła domyślna: HTTP 404 (Nie znaleziono)

Jak to działa

  1. Google Chat wysyła webhookowe żądania POST do Gateway. Każde żądanie zawiera nagłówek Authorization: Bearer <token>.
    • OpenClaw weryfikuje uwierzytelnianie bearer przed odczytaniem/przetworzeniem pełnych treści webhooka, gdy nagłówek jest obecny.
    • Żądania dodatków Google Workspace zawierające authorizationEventObject.systemIdToken w treści są obsługiwane przez bardziej rygorystyczny budżet treści przed uwierzytelnieniem.
  2. OpenClaw weryfikuje token względem skonfigurowanych audienceType i audience:
    • audienceType: "app-url" → odbiorcą jest HTTPS URL webhooka.
    • audienceType: "project-number" → odbiorcą jest numer projektu Cloud.
  3. Wiadomości są kierowane według pokoju:
    • Wiadomości bezpośrednie używają klucza sesji agent:<agentId>:googlechat:direct:<spaceId>.
    • Pokoje używają klucza sesji agent:<agentId>:googlechat:group:<spaceId>.
  4. Dostęp do wiadomości bezpośrednich domyślnie odbywa się przez parowanie. Nieznani nadawcy otrzymują kod parowania; zatwierdź go za pomocą:
    • openclaw pairing approve googlechat <code>
  5. Pokoje grupowe domyślnie wymagają wzmianki @. Użyj botUser, jeśli wykrywanie wzmianki wymaga nazwy użytkownika aplikacji.

Cele

Używaj tych identyfikatorów do dostarczania i list dozwolonych:

  • Wiadomości bezpośrednie: users/<userId> (zalecane).
  • Surowy adres e-mail [email protected] jest zmienny i używany tylko do dopasowywania bezpośredniej listy dozwolonych, gdy channels.googlechat.dangerouslyAllowNameMatching: true.
  • Przestarzałe: users/<email> jest traktowane jako identyfikator użytkownika, a nie lista dozwolonych adresów e-mail.
  • Pokoje: spaces/<spaceId>.

Najważniejsze elementy konfiguracji

{
  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": {
          enabled: true,
          requireMention: true,
          users: ["users/1234567890"],
          systemPrompt: "Short answers only.",
        },
      },
      actions: { reactions: true },
      typingIndicator: "message",
      mediaMaxMb: 20,
    },
  },
}

Uwagi:

  • Dane uwierzytelniające konta usługi można też przekazać wprost przez serviceAccount (ciąg JSON).
  • Obsługiwane jest także serviceAccountRef (env/file SecretRef), w tym referencje dla poszczególnych kont w channels.googlechat.accounts.<id>.serviceAccountRef.
  • Domyślna ścieżka webhooka to /googlechat, jeśli webhookPath nie jest ustawione.
  • dangerouslyAllowNameMatching ponownie włącza dopasowywanie zmiennych głównych adresów e-mail dla list dozwolonych (tryb zgodności awaryjnej).
  • Reakcje są dostępne przez narzędzie reactions i channels action, gdy actions.reactions jest włączone.
  • Akcje wiadomości udostępniają send dla tekstu oraz upload-file dla jawnego wysyłania załączników. upload-file akceptuje media / filePath / path oraz opcjonalnie message, filename i wskazanie wątku.
  • typingIndicator obsługuje none, message (domyślnie) i reaction (reakcja wymaga OAuth użytkownika).
  • Załączniki są pobierane przez Chat API i zapisywane w potoku multimediów (rozmiar ograniczony przez mediaMaxMb).

Szczegóły referencji sekretów: Zarządzanie sekretami.

Rozwiązywanie problemów

405 Method Not Allowed

Jeśli Google Cloud Logs Explorer pokazuje błędy takie jak:

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

Oznacza to, że obsługa webhooka nie jest zarejestrowana. Typowe przyczyny:

  1. Kanał nie jest skonfigurowany: sekcji channels.googlechat brakuje w konfiguracji. Zweryfikuj to za pomocą:

    openclaw config get channels.googlechat

    Jeśli zwraca „Config path not found”, dodaj konfigurację (zobacz Najważniejsze elementy konfiguracji).

  2. Plugin nie jest włączony: sprawdź status Plugin:

    openclaw plugins list | grep googlechat

    Jeśli pokazuje „disabled”, dodaj plugins.entries.googlechat.enabled: true do konfiguracji.

  3. Gateway nie został ponownie uruchomiony: po dodaniu konfiguracji uruchom ponownie Gateway:

    openclaw gateway restart

Zweryfikuj, czy kanał działa:

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

Inne problemy

  • Sprawdź openclaw channels status --probe pod kątem błędów uwierzytelniania lub brakującej konfiguracji odbiorcy.
  • Jeśli wiadomości nie przychodzą, potwierdź URL webhooka aplikacji Chat i subskrypcje zdarzeń.
  • Jeśli bramkowanie wzmianek blokuje odpowiedzi, ustaw botUser na nazwę zasobu użytkownika aplikacji i zweryfikuj requireMention.
  • Użyj openclaw logs --follow podczas wysyłania wiadomości testowej, aby sprawdzić, czy żądania docierają do Gateway.

Powiązane dokumenty:

Powiązane