diff --git a/docs/uk/channels/googlechat.md b/docs/uk/channels/googlechat.md index e47f387eb..201e7c35d 100644 --- a/docs/uk/channels/googlechat.md +++ b/docs/uk/channels/googlechat.md @@ -4,15 +4,15 @@ read_when: summary: Стан підтримки застосунку Google Chat, можливості та конфігурація title: Google Chat x-i18n: - generated_at: "2026-05-02T07:07:28Z" + generated_at: "2026-05-03T22:00:26Z" model: gpt-5.5 provider: openai - source_hash: fdb8dcf651602e92801d7107646d853871ea6cef188a8733a831695a1243740e + source_hash: afa2ca4d9673396aa24a55ca5855a34ad26a4640c3a1f6928dbf7246e403cb04 source_path: channels/googlechat.md workflow: 16 --- -Status: завантажуваний plugin для DM і просторів через webhooks Google Chat API (лише HTTP). +Стан: завантажуваний Plugin для DM і просторів через Webhook Google Chat API (лише HTTP). ## Встановлення @@ -22,7 +22,7 @@ Status: завантажуваний plugin для DM і просторів че openclaw plugins install @openclaw/googlechat ``` -Локальний checkout (коли запускаєте з git-репозиторію): +Локальна копія (під час запуску з git-репозиторію): ```bash openclaw plugins install ./path/to/local/googlechat-plugin @@ -33,60 +33,60 @@ openclaw plugins install ./path/to/local/googlechat-plugin 1. Створіть проєкт Google Cloud і ввімкніть **Google Chat API**. - Перейдіть до: [Облікові дані Google Chat API](https://console.cloud.google.com/apis/api/chat.googleapis.com/credentials) - Увімкніть API, якщо його ще не ввімкнено. -2. Створіть **сервісний обліковий запис**: - - Натисніть **Створити облікові дані** > **Сервісний обліковий запис**. +2. Створіть **Service Account**: + - Натисніть **Create Credentials** > **Service Account**. - Назвіть його як завгодно (наприклад, `openclaw-chat`). - - Залиште дозволи порожніми (натисніть **Продовжити**). - - Залиште principals із доступом порожніми (натисніть **Готово**). -3. Створіть і завантажте **JSON-ключ**: - - У списку сервісних облікових записів натисніть той, який щойно створили. - - Перейдіть на вкладку **Ключі**. - - Натисніть **Додати ключ** > **Створити новий ключ**. - - Виберіть **JSON** і натисніть **Створити**. -4. Збережіть завантажений JSON-файл на хості Gateway (наприклад, `~/.openclaw/googlechat-service-account.json`). -5. Створіть застосунок Google Chat у [конфігурації Chat у Google Cloud Console](https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat): - - Заповніть **інформацію про застосунок**: - - **Назва застосунку**: (наприклад, `OpenClaw`) - - **URL аватара**: (наприклад, `https://openclaw.ai/logo.png`) - - **Опис**: (наприклад, `Personal AI Assistant`) - - Увімкніть **інтерактивні функції**. - - У розділі **Функціональність** позначте **Приєднуватися до просторів і групових розмов**. - - У розділі **Налаштування підключення** виберіть **URL HTTP endpoint**. - - У розділі **Тригери** виберіть **Використовувати спільний URL HTTP endpoint для всіх тригерів** і встановіть його на публічний URL вашого Gateway з доданим `/googlechat`. - - _Порада: запустіть `openclaw status`, щоб знайти публічний URL вашого Gateway._ - - У розділі **Видимість** позначте **Зробити цей застосунок Chat доступним для певних людей і груп у ``**. - - Введіть свою адресу електронної пошти (наприклад, `user@example.com`) у текстове поле. - - Натисніть **Зберегти** внизу. + - Залиште дозволи порожніми (натисніть **Continue**). + - Залиште принципали з доступом порожніми (натисніть **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 у [налаштуваннях Chat у Google Cloud Console](https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat): + - Заповніть **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 ``**. + - Введіть свою email-адресу (наприклад, `user@example.com`) у текстове поле. + - Натисніть **Save** внизу. 6. **Увімкніть статус застосунку**: - Після збереження **оновіть сторінку**. - - Знайдіть розділ **Статус застосунку** (зазвичай після збереження він розташований угорі або внизу). - - Змініть статус на **Live - доступно користувачам**. - - Натисніть **Зберегти** ще раз. -7. Налаштуйте OpenClaw зі шляхом до сервісного облікового запису + аудиторією webhook: + - Знайдіть розділ **App status** (зазвичай він з’являється біля верху або низу після збереження). + - Змініть статус на **Live - available to users**. + - Знову натисніть **Save**. +7. Налаштуйте OpenClaw із шляхом до service account + аудиторією Webhook: - Env: `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json` - Або config: `channels.googlechat.serviceAccountFile: "/path/to/service-account.json"`. -8. Встановіть тип і значення аудиторії webhook (має відповідати конфігурації вашого застосунку Chat). -9. Запустіть Gateway. Google Chat надсилатиме POST на шлях вашого webhook. +8. Встановіть тип і значення аудиторії Webhook (має відповідати конфігурації вашого застосунку Chat). +9. Запустіть Gateway. Google Chat надсилатиме POST-запити на шлях вашого Webhook. ## Додавання до Google Chat -Коли Gateway працює, а вашу електронну пошту додано до списку видимості: +Після запуску Gateway і додавання вашої email-адреси до списку видимості: 1. Перейдіть до [Google Chat](https://chat.google.com/). -2. Натисніть іконку **+** (плюс) поруч із **Прямі повідомлення**. -3. У рядку пошуку (де ви зазвичай додаєте людей) введіть **назву застосунку**, яку налаштували в Google Cloud Console. - - **Примітка**: бот _не_ з’явиться у списку перегляду "Marketplace", бо це приватний застосунок. Його потрібно знайти за назвою. -4. Виберіть свого бота в результатах. -5. Натисніть **Додати** або **Chat**, щоб почати розмову 1:1. -6. Надішліть "Привіт", щоб активувати помічника! +2. Натисніть іконку **+** (плюс) поруч із **Direct Messages**. +3. У рядку пошуку (де ви зазвичай додаєте людей) введіть **App name**, налаштоване в Google Cloud Console. + - **Примітка**: бот _не_ з’явиться в списку перегляду "Marketplace", оскільки це приватний застосунок. Його потрібно шукати за назвою. +4. Виберіть свого бота з результатів. +5. Натисніть **Add** або **Chat**, щоб почати розмову 1:1. +6. Надішліть "Hello", щоб запустити асистента! -## Публічний URL (лише Webhook) +## Публічна URL-адреса (лише Webhook) -Webhooks Google Chat потребують публічного HTTPS endpoint. З міркувань безпеки **відкривайте в інтернет лише шлях `/googlechat`**. Панель OpenClaw та інші чутливі endpoints залишайте у приватній мережі. +Webhook Google Chat вимагають публічного HTTPS endpoint. Для безпеки **відкривайте в інтернет лише шлях `/googlechat`**. Залишайте панель OpenClaw та інші чутливі endpoint у приватній мережі. ### Варіант A: Tailscale Funnel (рекомендовано) -Використовуйте Tailscale Serve для приватної панелі та Funnel для публічного шляху webhook. Так `/` залишається приватним, а відкритим є лише `/googlechat`. +Використовуйте Tailscale Serve для приватної панелі й Funnel для публічного шляху Webhook. Це залишає `/` приватним, відкриваючи лише `/googlechat`. 1. **Перевірте, до якої адреси прив’язаний ваш Gateway:** @@ -106,7 +106,7 @@ Webhooks Google Chat потребують публічного HTTPS endpoint. tailscale serve --bg --https 8443 http://100.106.161.80:18789 ``` -3. **Публічно відкрийте лише шлях webhook:** +3. **Публічно відкрийте лише шлях Webhook:** ```bash # If bound to localhost (127.0.0.1 or 0.0.0.0): @@ -116,8 +116,8 @@ Webhooks Google Chat потребують публічного HTTPS endpoint. tailscale funnel --bg --set-path /googlechat http://100.106.161.80:18789/googlechat ``` -4. **Авторизуйте node для доступу Funnel:** - Якщо з’явиться запит, відкрийте URL авторизації, показаний у виводі, щоб увімкнути Funnel для цього node у політиці вашого tailnet. +4. **Авторизуйте Node для доступу Funnel:** + Якщо з’явиться запит, відкрийте URL авторизації, показану у виводі, щоб увімкнути Funnel для цього Node у політиці вашого tailnet. 5. **Перевірте конфігурацію:** @@ -126,19 +126,19 @@ Webhooks Google Chat потребують публічного HTTPS endpoint. tailscale funnel status ``` -Ваш публічний URL webhook буде: +Публічна URL-адреса вашого Webhook буде: `https://..ts.net/googlechat` Ваша приватна панель залишається доступною лише в tailnet: `https://..ts.net:8443/` -Використовуйте публічний URL (без `:8443`) у конфігурації застосунку Google Chat. +Використовуйте публічну URL-адресу (без `:8443`) у конфігурації застосунку Google Chat. > Примітка: ця конфігурація зберігається після перезавантажень. Щоб видалити її пізніше, запустіть `tailscale funnel reset` і `tailscale serve reset`. ### Варіант B: Reverse Proxy (Caddy) -Якщо ви використовуєте reverse proxy на кшталт Caddy, проксіюйте лише конкретний шлях: +Якщо ви використовуєте Reverse Proxy на кшталт Caddy, проксіюйте лише конкретний шлях: ```caddy your-domain.com { @@ -146,40 +146,40 @@ your-domain.com { } ``` -З цією конфігурацією будь-який запит до `your-domain.com/` буде проігноровано або повернено як 404, тоді як `your-domain.com/googlechat` безпечно маршрутизуватиметься до OpenClaw. +З цією конфігурацією будь-який запит до `your-domain.com/` буде проігноровано або поверне 404, тоді як `your-domain.com/googlechat` безпечно маршрутизуватиметься до OpenClaw. ### Варіант C: Cloudflare Tunnel -Налаштуйте ingress rules вашого tunnel так, щоб маршрутизувався лише шлях webhook: +Налаштуйте ingress-правила вашого тунелю так, щоб маршрутизувати лише шлях Webhook: - **Шлях**: `/googlechat` -> `http://localhost:18789/googlechat` - **Правило за замовчуванням**: HTTP 404 (Not Found) ## Як це працює -1. Google Chat надсилає webhook POSTs до Gateway. Кожен запит містить заголовок `Authorization: Bearer `. - - OpenClaw перевіряє bearer auth перед читанням/розбором повних тіл webhook, коли заголовок наявний. - - Запити Google Workspace Add-on, які містять `authorizationEventObject.systemIdToken` у тілі, підтримуються через суворіший бюджет тіла pre-auth. -2. OpenClaw перевіряє token щодо налаштованих `audienceType` + `audience`: - - `audienceType: "app-url"` → аудиторія — це ваш HTTPS URL webhook. +1. Google Chat надсилає Webhook POST-запити до Gateway. Кожен запит містить заголовок `Authorization: Bearer `. + - OpenClaw перевіряє bearer-автентифікацію перед читанням/розбором повних тіл Webhook, коли заголовок присутній. + - Запити Google Workspace Add-on, які містять `authorizationEventObject.systemIdToken` у тілі, підтримуються через суворіший бюджет тіла перед автентифікацією. +2. OpenClaw перевіряє токен відносно налаштованих `audienceType` + `audience`: + - `audienceType: "app-url"` → аудиторія — це ваша HTTPS URL-адреса Webhook. - `audienceType: "project-number"` → аудиторія — це номер проєкту Cloud. 3. Повідомлення маршрутизуються за простором: - DM використовують ключ сесії `agent::googlechat:direct:`. - Простори використовують ключ сесії `agent::googlechat:group:`. 4. Доступ до DM за замовчуванням відбувається через pairing. Невідомі відправники отримують код pairing; підтвердьте за допомогою: - `openclaw pairing approve googlechat ` -5. Групові простори за замовчуванням потребують @-mention. Використовуйте `botUser`, якщо для виявлення згадок потрібне ім’я користувача застосунку. +5. Групові простори за замовчуванням потребують @-згадки. Використовуйте `botUser`, якщо для виявлення згадок потрібне ім’я користувача застосунку. ## Цілі -Використовуйте ці ідентифікатори для доставки та allowlists: +Використовуйте ці ідентифікатори для доставки й allowlists: - Прямі повідомлення: `users/` (рекомендовано). -- Raw email `name@example.com` є змінним і використовується лише для прямого зіставлення allowlist, коли `channels.googlechat.dangerouslyAllowNameMatching: true`. -- Застаріле: `users/` трактується як user id, а не email allowlist. +- Необроблена email-адреса `name@example.com` є змінною і використовується лише для зіставлення прямого allowlist, коли `channels.googlechat.dangerouslyAllowNameMatching: true`. +- Застаріле: `users/` трактується як user id, а не як email allowlist. - Простори: `spaces/`. -## Основні параметри config +## Основні моменти конфігурації ```json5 { @@ -199,7 +199,7 @@ your-domain.com { groupPolicy: "allowlist", groups: { "spaces/AAAA": { - allow: true, + enabled: true, requireMention: true, users: ["users/1234567890"], systemPrompt: "Short answers only.", @@ -215,16 +215,16 @@ your-domain.com { Примітки: -- Облікові дані сервісного облікового запису також можна передати inline через `serviceAccount` (JSON string). -- `serviceAccountRef` також підтримується (env/file SecretRef), включно з per-account refs у `channels.googlechat.accounts..serviceAccountRef`. -- Стандартний шлях webhook — `/googlechat`, якщо `webhookPath` не задано. -- `dangerouslyAllowNameMatching` повторно вмикає зіставлення змінних email principals для allowlists (режим сумісності break-glass). -- Reactions доступні через інструмент `reactions` і `channels action`, коли ввімкнено `actions.reactions`. -- Дії з повідомленнями надають `send` для тексту та `upload-file` для явного надсилання вкладень. `upload-file` приймає `media` / `filePath` / `path` плюс необов’язкові `message`, `filename` і targeting thread. -- `typingIndicator` підтримує `none`, `message` (за замовчуванням) і `reaction` (reaction потребує user OAuth). -- Вкладення завантажуються через Chat API і зберігаються в media pipeline (розмір обмежується `mediaMaxMb`). +- Облікові дані service account також можна передати inline через `serviceAccount` (JSON-рядок). +- `serviceAccountRef` також підтримується (env/file SecretRef), зокрема refs для окремих акаунтів у `channels.googlechat.accounts..serviceAccountRef`. +- Шлях Webhook за замовчуванням — `/googlechat`, якщо `webhookPath` не задано. +- `dangerouslyAllowNameMatching` знову вмикає зіставлення змінних email-принципалів для allowlists (режим сумісності break-glass). +- Реакції доступні через інструмент `reactions` і `channels action`, коли `actions.reactions` увімкнено. +- Дії повідомлень надають `send` для тексту та `upload-file` для явного надсилання вкладень. `upload-file` приймає `media` / `filePath` / `path` плюс необов’язкові `message`, `filename` і цільовий thread. +- `typingIndicator` підтримує `none`, `message` (за замовчуванням) і `reaction` (reaction потребує OAuth користувача). +- Вкладення завантажуються через Chat API і зберігаються в медіа-конвеєрі (розмір обмежено `mediaMaxMb`). -Докладніше про secrets reference: [Керування secrets](/uk/gateway/secrets). +Докладніше про посилання на секрети: [Керування секретами](/uk/gateway/secrets). ## Усунення несправностей @@ -236,31 +236,31 @@ your-domain.com { status code: 405, reason phrase: HTTP error response: HTTP/1.1 405 Method Not Allowed ``` -Це означає, що обробник webhook не зареєстрований. Поширені причини: +Це означає, що обробник Webhook не зареєстровано. Поширені причини: -1. **Канал не налаштований**: у вашому config відсутній розділ `channels.googlechat`. Перевірте за допомогою: +1. **Канал не налаштовано**: розділ `channels.googlechat` відсутній у вашій конфігурації. Перевірте за допомогою: ```bash openclaw config get channels.googlechat ``` - Якщо повертається "Config path not found", додайте конфігурацію (див. [Основні параметри config](#config-highlights)). + Якщо повертається "Config path not found", додайте конфігурацію (див. [Основні моменти конфігурації](#config-highlights)). -2. **Plugin не ввімкнено**: перевірте статус plugin: +2. **Plugin не ввімкнено**: перевірте статус Plugin: ```bash openclaw plugins list | grep googlechat ``` - Якщо показує "disabled", додайте `plugins.entries.googlechat.enabled: true` до вашого config. + Якщо показує "disabled", додайте `plugins.entries.googlechat.enabled: true` до своєї конфігурації. -3. **Gateway не перезапущено**: після додавання config перезапустіть Gateway: +3. **Gateway не перезапущено**: після додавання конфігурації перезапустіть Gateway: ```bash openclaw gateway restart ``` -Перевірте, що канал запущений: +Перевірте, що канал запущено: ```bash openclaw channels status @@ -269,21 +269,21 @@ openclaw channels status ### Інші проблеми -- Перевірте `openclaw channels status --probe` на помилки auth або відсутню конфігурацію аудиторії. -- Якщо повідомлення не надходять, підтвердьте URL webhook застосунку Chat + event subscriptions. -- Якщо mention gating блокує відповіді, встановіть `botUser` на user resource name застосунку та перевірте `requireMention`. -- Використовуйте `openclaw logs --follow` під час надсилання тестового повідомлення, щоб побачити, чи запити доходять до Gateway. +- Перевірте `openclaw channels status --probe` на помилки автентифікації або відсутню конфігурацію аудиторії. +- Якщо повідомлення не надходять, підтвердьте URL-адресу Webhook застосунку Chat + підписки на події. +- Якщо обмеження за згадками блокує відповіді, встановіть `botUser` як ім’я ресурсу користувача застосунку й перевірте `requireMention`. +- Використовуйте `openclaw logs --follow` під час надсилання тестового повідомлення, щоб побачити, чи доходять запити до Gateway. Пов’язані документи: - [Конфігурація Gateway](/uk/gateway/configuration) - [Безпека](/uk/gateway/security) -- [Reactions](/uk/tools/reactions) +- [Реакції](/uk/tools/reactions) ## Пов’язане - [Огляд каналів](/uk/channels) — усі підтримувані канали -- [Pairing](/uk/channels/pairing) — автентифікація DM і потік pairing -- [Групи](/uk/channels/groups) — поведінка групових чатів і mention gating +- [Pairing](/uk/channels/pairing) — автентифікація DM і процес pairing +- [Групи](/uk/channels/groups) — поведінка групового чату та обмеження за згадками - [Маршрутизація каналів](/uk/channels/channel-routing) — маршрутизація сесій для повідомлень -- [Безпека](/uk/gateway/security) — модель доступу та hardening +- [Безпека](/uk/gateway/security) — модель доступу та посилення захисту