​

Google Chat (Chat API)

​

Швидке налаштування (для початківців)

1. Створіть проєкт Google Cloud і ввімкніть Google Chat API.
   • Перейдіть до: Google Chat API Credentials
   • Увімкніть API, якщо воно ще не ввімкнене.
2. Створіть Service Account:
   • Натисніть Create Credentials > Service Account.
   • Задайте будь-яку назву (наприклад, openclaw-chat).
   • Залиште дозволи порожніми (натисніть Continue).
   • Залиште principals with access порожніми (натисніть Done).
3. Створіть і завантажте JSON Key:
   • У списку service accounts натисніть ту, яку ви щойно створили.
   • Перейдіть на вкладку Keys.
   • Натисніть Add Key > Create new key.
   • Виберіть JSON і натисніть Create.
4. Збережіть завантажений JSON-файл на вашому хості gateway (наприклад, ~/.openclaw/googlechat-service-account.json).
5. Створіть застосунок Google Chat у Google Cloud Console Chat Configuration:
   • Заповніть Application info:
     • App name: (наприклад, OpenClaw)
     • Avatar URL: (наприклад, https://openclaw.ai/logo.png)
     • Description: (наприклад, Personal AI Assistant)
   • Увімкніть Interactive features.
   • У розділі Functionality позначте Join spaces and group conversations.
   • У розділі Connection settings виберіть HTTP endpoint URL.
   • У розділі Triggers виберіть Use a common HTTP endpoint URL for all triggers і задайте URL публічного gateway з доданим /googlechat.
     • Порада: виконайте openclaw status, щоб знайти публічний URL вашого gateway.
   • У розділі Visibility позначте Make this Chat app available to specific people and groups in <Your Domain>.
   • Введіть свою адресу електронної пошти (наприклад, user@example.com) у текстове поле.
   • Унизу натисніть Save.
6. Увімкніть статус застосунку:
   • Після збереження оновіть сторінку.
   • Знайдіть розділ App status (зазвичай угорі або внизу після збереження).
   • Змініть статус на Live - available to users.
   • Ще раз натисніть Save.
7. Налаштуйте OpenClaw із шляхом до service account + аудиторією вебхука:
   • Env: GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json
   • Або config: channels.googlechat.serviceAccountFile: "/path/to/service-account.json".
8. Задайте тип і значення аудиторії вебхука (має збігатися з конфігурацією вашого застосунку Chat).
9. Запустіть gateway. Google Chat надсилатиме POST-запити на шлях вашого вебхука.

​

Додати до Google Chat

1. Перейдіть у Google Chat.
2. Натисніть значок + (плюс) поруч із Direct Messages.
3. У рядку пошуку (де ви зазвичай додаєте людей) введіть App name, яке ви налаштували в Google Cloud Console.
   • Примітка: бот не з’явиться у списку перегляду “Marketplace”, оскільки це приватний застосунок. Його потрібно шукати за назвою.
4. Виберіть свого бота з результатів.
5. Натисніть Add або Chat, щоб почати розмову 1:1.
6. Надішліть “Hello”, щоб активувати асистента!

​

Публічний URL (лише вебхук)

​

Варіант A: Tailscale Funnel (рекомендовано)

1. Перевірте, до якої адреси прив’язаний ваш gateway:
   ss -tlnp | grep 18789
   
   Зверніть увагу на IP-адресу (наприклад, 127.0.0.1, 0.0.0.0 або вашу адресу Tailscale на кшталт 100.x.x.x).
2. Відкрийте панель лише для tailnet (порт 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. Публічно відкрийте лише шлях вебхука:
   # 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. Авторизуйте вузол для доступу Funnel: Якщо з’явиться запит, відкрийте URL авторизації, показаний у виводі, щоб увімкнути Funnel для цього вузла у вашій політиці tailnet.
5. Перевірте конфігурацію:
   tailscale serve status
   tailscale funnel status
   

Примітка: ця конфігурація зберігається після перезавантаження. Щоб пізніше її видалити, виконайте tailscale funnel reset і tailscale serve reset.

​

Варіант B: Reverse Proxy (Caddy)

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

​

Варіант C: Cloudflare Tunnel

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

​

Як це працює

1. Google Chat надсилає webhook POST-запити до gateway. Кожен запит містить заголовок Authorization: Bearer <token>.
   • OpenClaw перевіряє bearer auth перед читанням/парсингом повних тіл вебхуків, якщо заголовок присутній.
   • Запити Google Workspace Add-on, які містять authorizationEventObject.systemIdToken у тілі, підтримуються через суворіший бюджет тіла для pre-auth.
2. OpenClaw перевіряє токен відповідно до налаштованих audienceType + audience:
   • audienceType: "app-url" → аудиторія — це ваш HTTPS URL вебхука.
   • audienceType: "project-number" → аудиторія — це номер Cloud-проєкту.
3. Повідомлення маршрутизуються за простором:
   • Особисті повідомлення використовують ключ сесії agent:<agentId>:googlechat:direct:<spaceId>.
   • Простори використовують ключ сесії agent:<agentId>:googlechat:group:<spaceId>.
4. Доступ до особистих повідомлень типово використовує pairing. Невідомі відправники отримують код pairing; схваліть його командою:
   • openclaw pairing approve googlechat <code>
5. Для групових просторів типово потрібне @-згадування. Використовуйте botUser, якщо для виявлення згадувань потрібне ім’я користувача застосунку.

​

Цілі

• Особисті повідомлення: users/<userId> (рекомендовано).
• Необроблена адреса електронної пошти name@example.com є змінною і використовується лише для прямого зіставлення в списку дозволу, коли channels.googlechat.dangerouslyAllowNameMatching: true.
• Застаріле: users/<email> обробляється як id користувача, а не як email у списку дозволу.
• Простори: spaces/<spaceId>.

​

Основні моменти конфігурації

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

• Облікові дані service account також можна передати вбудовано через serviceAccount (рядок JSON).
• Також підтримується serviceAccountRef (env/file SecretRef), включно з refs для окремих облікових записів у channels.googlechat.accounts.<id>.serviceAccountRef.
• Типовий шлях вебхука — /googlechat, якщо webhookPath не задано.
• dangerouslyAllowNameMatching знову вмикає зіставлення змінюваних email principals для списків дозволу (аварійний режим сумісності).
• Реакції доступні через інструмент reactions і channels action, якщо ввімкнено actions.reactions.
• Дії з повідомленнями надають send для тексту і upload-file для явного надсилання вкладень. upload-file приймає media / filePath / path, а також необов’язкові message, filename і націлювання на thread.
• typingIndicator підтримує none, message (типово) і reaction (для реакцій потрібен OAuth користувача).
• Вкладення завантажуються через Chat API і зберігаються в конвеєрі медіа (розмір обмежується mediaMaxMb).

​

Усунення несправностей

​

405 Method Not Allowed

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

1. Канал не налаштований: у вашій конфігурації відсутній розділ channels.googlechat. Перевірте командою:
   openclaw config get channels.googlechat
   
   Якщо вона повертає “Config path not found”, додайте конфігурацію (див. Основні моменти конфігурації).
2. Plugin не ввімкнено: перевірте статус plugin:
   openclaw plugins list | grep googlechat
   
   Якщо показано “disabled”, додайте plugins.entries.googlechat.enabled: true до вашої конфігурації.
3. Gateway не перезапущено: після додавання конфігурації перезапустіть gateway:
   openclaw gateway restart
   

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

​

Інші проблеми

• Перевірте openclaw channels status --probe на наявність помилок автентифікації або відсутньої конфігурації аудиторії.
• Якщо повідомлення не надходять, перевірте URL вебхука застосунку Chat + підписки на події.
• Якщо gating згадувань блокує відповіді, задайте botUser як ім’я ресурсу користувача застосунку та перевірте requireMention.
• Використовуйте openclaw logs --follow під час надсилання тестового повідомлення, щоб побачити, чи доходять запити до gateway.

• Конфігурація gateway
• Безпека
• Reactions

​

Пов’язане

• Огляд каналів — усі підтримувані канали
• Pairing — автентифікація особистих повідомлень і процес pairing
• Групи — поведінка групових чатів і gating згадувань
• Маршрутизація каналів — маршрутизація сесій для повідомлень
• Безпека — модель доступу та посилення захисту