OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Mainstream messaging

Google Chat

Google Chat працює як офіційний plugin @openclaw/googlechat: особисті повідомлення та простори через вебхуки Google Chat API (лише кінцева точка HTTP, без Pub/Sub).

Встановлення

bash
openclaw plugins install @openclaw/googlechat

Локальна робоча копія (під час запуску з репозиторію git):

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

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

  1. Створіть проєкт Google Cloud і ввімкніть Google Chat API.
  2. Створіть Service Account:
    • Натисніть Create Credentials > Service Account.
    • Назвіть його як завгодно (наприклад, openclaw-chat).
    • Залиште дозволи та суб’єкти порожніми (Continue, потім Done).
  3. Створіть і завантажте ключ JSON:
    • Натисніть новий сервісний обліковий запис > вкладка Keys > Add Key > Create new key > JSON > Create.
  4. Збережіть завантажений файл JSON на хості Gateway (наприклад, ~/.openclaw/googlechat-service-account.json).
  5. Створіть застосунок Google Chat у розділі налаштування Chat у Google Cloud Console:
    • Заповніть Application info (назва застосунку, URL аватара, опис).
    • Увімкніть 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 (див. Публічна URL-адреса).
    • У розділі Visibility позначте Make this Chat app available to specific people and groups in <Your Domain> і введіть свою адресу електронної пошти.
    • Натисніть Save.
  6. Увімкніть статус застосунку: оновіть сторінку, знайдіть App status, установіть Live - available to users і знову натисніть Save.
  7. Налаштуйте OpenClaw за допомогою сервісного облікового запису та аудиторії вебхука (має відповідати конфігурації застосунку Chat):
    • Змінна середовища: GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json (лише для облікового запису за замовчуванням), або
    • Конфігурація: див. Основні параметри конфігурації. openclaw channels add --channel googlechat також приймає --audience-type, --audience, --webhook-path і --webhook-url.
  8. Запустіть Gateway. Google Chat надсилатиме POST-запити на шлях вебхука (за замовчуванням /googlechat).

Додавання до Google Chat

Коли Gateway запущено, а вашу адресу електронної пошти додано до списку видимості:

  1. Перейдіть до Google Chat.
  2. Натисніть значок + (плюс) поруч із Direct Messages.
  3. Знайдіть App name, налаштовану в Google Cloud Console.
    • Бот не відображається у списку огляду Marketplace, оскільки це приватний застосунок; шукайте його за назвою.
  4. Виберіть бота, натисніть Add або Chat і надішліть повідомлення.

Публічна URL-адреса (лише вебхук)

Для вебхуків Google Chat потрібна публічна кінцева точка HTTPS. З міркувань безпеки відкривайте в інтернеті лише шлях /googlechat, а панель керування OpenClaw та інші кінцеві точки залишайте приватними.

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

Використовуйте Tailscale Serve для приватної панелі керування та Funnel для публічного шляху вебхука.

  1. Перевірте, до якої адреси прив’язано Gateway:

    bash
    ss -tlnp | grep 18789

    Занотуйте IP-адресу (наприклад, 127.0.0.1, 0.0.0.0 або адресу Tailscale 100.x.x.x).

  2. Відкрийте доступ до панелі керування лише для tailnet (порт 8443):

    bash
    # Якщо прив’язано до localhost (127.0.0.1 або 0.0.0.0):tailscale serve --bg --https 8443 http://127.0.0.1:18789 # Якщо прив’язано лише до IP-адреси Tailscale:tailscale serve --bg --https 8443 http://100.x.x.x:18789

  3. Відкрийте публічний доступ лише до шляху вебхука:

    bash
    # Якщо прив’язано до localhost (127.0.0.1 або 0.0.0.0):tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat # Якщо прив’язано лише до IP-адреси Tailscale:tailscale funnel --bg --set-path /googlechat http://100.x.x.x:18789/googlechat

  4. Якщо з’явиться запит, перейдіть за URL-адресою авторизації, показаною у виводі, щоб увімкнути Funnel для цього вузла.

  5. Перевірте:

    bash
    tailscale serve statustailscale funnel status

Публічна URL-адреса вебхука: https://<node-name>.<tailnet>.ts.net/googlechat; панель керування залишається доступною лише в tailnet за адресою https://<node-name>.<tailnet>.ts.net:8443/. Використовуйте публічну URL-адресу (без :8443) у конфігурації застосунку Google Chat.

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

Варіант B: зворотний проксі (Caddy)

Проксіюйте лише шлях вебхука:

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

Запити до your-domain.com/ ігноруються або отримують відповідь 404, а your-domain.com/googlechat спрямовується до OpenClaw.

Варіант C: Cloudflare Tunnel

Налаштуйте правила вхідного трафіку тунелю, щоб спрямовувати лише шлях вебхука:

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

Принцип роботи

  1. Google Chat надсилає JSON за допомогою POST-запитів на шлях вебхука Gateway (лише POST, потрібен тип вмісту JSON, діє обмеження частоти запитів для кожної IP-адреси).
  2. OpenClaw автентифікує кожен запит перед передаванням:
    • Події застосунку Chat містять Authorization: Bearer <token>; токен перевіряється до розбору повного тіла запиту.
    • Події доповнення Google Workspace містять токен у тілі (authorizationEventObject.systemIdToken) і зчитуються до перевірки в межах суворіших обмежень попередньої автентифікації (16 КБ, 3 с).
  3. Токен перевіряється за audienceType + audience:
    • audienceType: "app-url" → аудиторією є URL-адреса HTTPS вашого вебхука.
    • audienceType: "project-number" → аудиторією є номер проєкту Cloud.
    • Для токенів доповнень із app-url додатково потрібно встановити appPrincipal у числовий ідентифікатор клієнта OAuth 2.0 застосунку (21 цифра, не адреса електронної пошти); інакше перевірка завершується помилкою із записом попередження в журнал.
  4. Повідомлення маршрутизуються за простором:
    • Простори отримують окремі сеанси agent:<agentId>:googlechat:group:<spaceId>; відповіді надсилаються до гілки повідомлення.
    • Особисті повідомлення за замовчуванням об’єднуються з основним сеансом агента; установіть session.dmScope для окремих сеансів особистих повідомлень із кожним співрозмовником (див. Сеанс).
  5. Доступ до особистих повідомлень за замовчуванням потребує сполучення. Невідомі відправники отримують код сполучення; підтвердьте його за допомогою:
    • openclaw pairing approve googlechat <code>
  6. У групових просторах за замовчуванням потрібна @згадка. Згадки виявляються за анотаціями Chat USER_MENTION, спрямованими на застосунок; установіть botUser (наприклад, users/1234567890), якщо для виявлення потрібне ім’я ресурсу користувача застосунку.
  7. Коли запит на схвалення виконання команди або plugin ініційовано з Google Chat і налаштовано стабільного схвалювача users/<id>, OpenClaw публікує вбудовану картку схвалення (cardsV2) у вихідному просторі або гілці. Кнопки картки містять непрозорі токени зворотного виклику; запит ручного введення /approve <id> <decision> з’являється лише тоді, коли вбудоване доставлення недоступне.

Цілі

Використовуйте ці ідентифікатори для доставлення та списків дозволених:

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

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

json5
{  channels: {    googlechat: {      enabled: true,      serviceAccountFile: "/path/to/service-account.json",      // або serviceAccountRef: { source: "file", provider: "filemain", id: "/channels/googlechat/serviceAccount" }      audienceType: "app-url",      audience: "https://gateway.example.com/googlechat",      appPrincipal: "123456789012345678901", // лише перевірка доповнення; числовий ідентифікатор клієнта OAuth      webhookPath: "/googlechat",      botUser: "users/1234567890", // необов’язково; допомагає виявляти згадки      allowBots: false,      dm: {        policy: "pairing",        allowFrom: ["users/1234567890"],      },      groupPolicy: "allowlist",      groups: {        "spaces/AAAA": {          enabled: true,          requireMention: true,          users: ["users/1234567890"],          systemPrompt: "Лише короткі відповіді.",        },      },      typingIndicator: "message",      mediaMaxMb: 20,    },  },}

Примітки:

  • Облікові дані сервісного облікового запису: serviceAccountFile (шлях), serviceAccount (вбудований рядок або об’єкт JSON) чи serviceAccountRef (SecretRef для змінної середовища або файлу). Змінні середовища GOOGLE_CHAT_SERVICE_ACCOUNT (вбудований JSON) і GOOGLE_CHAT_SERVICE_ACCOUNT_FILE (шлях) застосовуються лише до облікового запису за замовчуванням. У конфігураціях із кількома обліковими записами використовується channels.googlechat.accounts.<id> із тими самими ключами, зокрема окремим serviceAccountRef для кожного облікового запису.
  • Якщо webhookPath не встановлено, шлях вебхука за замовчуванням — /googlechat; натомість шлях можна вказати через webhookUrl.
  • Ключами груп мають бути стабільні ідентифікатори просторів (spaces/<spaceId>). Ключі з відображуваними назвами застаріли, і це фіксується в журналі.
  • dangerouslyAllowNameMatching повторно вмикає зіставлення змінних суб’єктів електронної пошти зі списками дозволених (режим аварійної сумісності); doctor попереджає про записи з адресами електронної пошти.
  • Дії з реакціями Google Chat недоступні. Plugin використовує автентифікацію сервісного облікового запису, тоді як кінцеві точки реакцій Google Chat потребують автентифікації користувача. Наявна конфігурація actions.reactions приймається для сумісності, але не має жодного ефекту.
  • Вбудовані картки схвалення використовують натискання кнопок Google Chat cardsV2, а не події реакцій. Схвалювачі беруться з dm.allowFrom або defaultTo та мають бути стабільними числовими значеннями users/<id>.
  • Дії з повідомленнями надають лише текстову дію send. Для передавання вкладень Google Chat потрібна автентифікація користувача, тоді як цей plugin використовує автентифікацію сервісного облікового запису, тому вихідне передавання файлів недоступне.
  • typingIndicator: message (за замовчуванням) публікує заповнювач _&lt;Bot&gt; is typing..._ і замінює його першою відповіддю; none вимикає його; reaction потребує OAuth користувача й наразі повертається до message із записом помилки в журнал за автентифікації сервісного облікового запису.
  • Вхідні вкладення (перше вкладення кожного повідомлення) завантажуються через Chat API до конвеєра медіаданих з обмеженням mediaMaxMb (за замовчуванням 20).
  • Повідомлення, створені ботами, за замовчуванням ігноруються. За allowBots: true прийняті повідомлення ботів використовують спільний захист від зациклення ботів: налаштуйте channels.defaults.botLoopProtection, а потім перевизначте через channels.googlechat.botLoopProtection або channels.googlechat.groups.<space>.botLoopProtection.

Докладніше про посилання на секрети: Керування секретами.

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

405 Method Not Allowed

Якщо Google Cloud Logs Explorer показує помилки на кшталт:

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

Обробник вебхука не зареєстровано. Поширені причини:

  1. Канал не налаштовано: розділ channels.googlechat відсутній. Перевірте за допомогою:

    bash
    openclaw config get channels.googlechat

    Якщо команда повертає "Config path not found", додайте конфігурацію (див. Основні параметри конфігурації).

  2. Plugin не ввімкнено: перевірте стан plugin:

    bash
    openclaw plugins list | grep googlechat

    Якщо відображається "disabled", додайте plugins.entries.googlechat.enabled: true до конфігурації.

  3. Gateway не перезапущено після змін конфігурації:

    bash
    openclaw gateway restart

Переконайтеся, що канал працює:

bash
openclaw channels status# Має відображатися: Google Chat default: enabled, configured, ...

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

  • openclaw channels status --probe показує помилки автентифікації та відсутню конфігурацію аудиторії (audience і audienceType є обов’язковими).
  • Якщо повідомлення не надходять, перевірте URL-адресу вебхука та конфігурацію тригерів застосунку Chat.
  • Якщо вимога згадки блокує відповіді, установіть botUser на ім’я ресурсу користувача застосунку та перевірте requireMention.
  • openclaw logs --follow під час надсилання тестового повідомлення показує, чи досягають запити Gateway.

Пов’язане

Was this useful?
On this page

On this page