Google Chat (Chat API)

Статус: готов для ЛС + пространств через вебхуки Google Chat API (только HTTP).

Быстрая настройка (для начинающих)

Создайте проект Google Cloud и включите Google Chat API.
- Перейдите: Google Chat API Credentials
- Включите API, если он ещё не включён.
Создайте Service Account:
- Нажмите Create Credentials > Service Account.
- Назовите как угодно (например, openclaw-chat).
- Оставьте разрешения пустыми (нажмите Continue).
- Оставьте principals with access пустым (нажмите Done).
Создайте и скачайте JSON-ключ:
- В списке сервисных аккаунтов кликните на созданный.
- Перейдите на вкладку Keys.
- Нажмите Add Key > Create new key.
- Выберите JSON и нажмите Create.
Сохраните скачанный JSON-файл на хосте шлюза (например, ~/.openclaw/googlechat-service-account.json).
Создайте приложение 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 шлюза с путём /googlechat.
  - Совет: выполните openclaw status, чтобы узнать публичный URL шлюза.
- В разделе Visibility отметьте Make this Chat app available to specific people and groups in <Your Domain>.
- Введите ваш email (например, [email protected]).
- Нажмите Save.
Включите статус приложения:
- После сохранения обновите страницу.
- Найдите раздел App status.
- Измените статус на Live - available to users.
- Снова нажмите Save.
Настройте OpenClaw с путём к сервисному аккаунту + аудиторией вебхука:
- Env: GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json
- Или конфиг: channels.googlechat.serviceAccountFile: "/path/to/service-account.json".
Задайте тип и значение аудитории вебхука (соответствует конфигурации Chat-приложения).
Запустите шлюз. Google Chat будет отправлять POST на путь вебхука.

Добавление в Google Chat

Когда шлюз запущен и ваш email добавлен в список видимости:

Перейдите в Google Chat.
Нажмите + рядом с Direct Messages.
В строке поиска введите имя приложения, заданное в Google Cloud Console.
- Примечание: бот не появится в списке Marketplace, потому что это приватное приложение. Его нужно искать по имени.
Выберите бота из результатов.
Нажмите Add или Chat, чтобы начать диалог 1:1.
Отправьте «Hello», чтобы активировать ассистента!

Публичный URL (только вебхук)

Вебхуки Google Chat требуют публичный HTTPS-эндпоинт. В целях безопасности открывайте только путь /googlechat в интернет. Оставьте панель OpenClaw и другие конфиденциальные эндпоинты в приватной сети.

Вариант A: Tailscale Funnel (рекомендуется)

Используйте Tailscale Serve для приватной панели и Funnel для публичного пути вебхука. Так / останется приватным, а будет открыт только /googlechat.

Проверьте, на каком адресе слушает шлюз:
```
ss -tlnp | grep 18789
```
Откройте панель только для tailnet (порт 8443):
```
tailscale serve --bg --https 8443 http://127.0.0.1:18789
```

Откройте публично только путь вебхука:

tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat

Авторизуйте узел для Funnel: При запросе перейдите по URL авторизации для включения Funnel для этого узла.

Проверьте конфигурацию:

tailscale serve status
tailscale 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: Reverse Proxy (Caddy)

Если используете reverse proxy типа Caddy, проксируйте только конкретный путь:

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

Вариант C: Cloudflare Tunnel

Настройте правила ingress туннеля для маршрутизации только пути вебхука:

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

Как это работает

Google Chat отправляет POST-запросы на шлюз. Каждый запрос содержит заголовок Authorization: Bearer <token>.
- OpenClaw проверяет bearer auth до чтения/разбора полного тела вебхука.
- Запросы Google Workspace Add-on с authorizationEventObject.systemIdToken в теле поддерживаются через более строгий бюджет пред-авторизации тела.
OpenClaw проверяет токен по настроенным audienceType + audience:
- audienceType: "app-url" — аудитория — ваш HTTPS URL вебхука.
- audienceType: "project-number" — аудитория — номер Cloud-проекта.
Сообщения маршрутизируются по пространству:
- ЛС используют ключ сессии agent:<agentId>:googlechat:direct:<spaceId>.
- Пространства используют ключ agent:<agentId>:googlechat:group:<spaceId>.
Доступ к ЛС по умолчанию использует спаривание. Неизвестные отправители получают код; подтверждение:
- openclaw pairing approve googlechat <code>
Групповые пространства по умолчанию требуют @-упоминания. Используйте botUser, если обнаружение упоминаний требует имени пользователя приложения.

Цели

Используйте эти идентификаторы для доставки и списков доступа:

Прямые сообщения: users/<userId> (рекомендуется).
Сырой email [email protected] изменчив и используется для прямого сопоставления со списком доступа только при channels.googlechat.dangerouslyAllowNameMatching: true.
Устарело: users/<email> трактуется как user id, а не email для списка доступа.
Пространства: spaces/<spaceId>.

Основные настройки конфигурации

{
  channels: {
    googlechat: {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      audienceType: "app-url",
      audience: "https://gateway.example.com/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890",
      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,
    },
  },
}

Примечания:

Учётные данные сервисного аккаунта также можно передать инлайн через serviceAccount (JSON-строка).
serviceAccountRef тоже поддерживается (env/file SecretRef), включая per-account refs под channels.googlechat.accounts.<id>.serviceAccountRef.
Путь вебхука по умолчанию — /googlechat, если webhookPath не задан.
dangerouslyAllowNameMatching повторно включает изменяемое сопоставление по email principal для списков доступа (аварийный режим совместимости).
Реакции доступны через инструмент reactions и channels action, когда actions.reactions включён.
typingIndicator поддерживает none, message (по умолчанию) и reaction (reaction требует user OAuth).
Вложения загружаются через Chat API и сохраняются в медиа-конвейере (размер ограничен mediaMaxMb).

Подробнее об управлении секретами: Управление секретами.

Устранение неполадок

405 Method Not Allowed

Если Google Cloud Logs Explorer показывает ошибки вида:

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

Это означает, что обработчик вебхука не зарегистрирован. Частые причины:

Канал не настроен: секция channels.googlechat отсутствует в конфиге. Проверьте:
```
openclaw config get channels.googlechat
```
Если возвращает «Config path not found», добавьте конфигурацию.
Плагин не включён: проверьте статус плагина:
```
openclaw plugins list | grep googlechat
```
Шлюз не перезапущен: после добавления конфига перезапустите шлюз:
```
openclaw gateway restart
```

Проверьте, что канал работает:

openclaw channels status

Другие проблемы

Проверьте openclaw channels status --probe на ошибки auth или отсутствующую конфигурацию аудитории.
Если сообщения не приходят, подтвердите URL вебхука + подписки на события в Chat-приложении.
Если гейтинг по упоминанию блокирует ответы, задайте botUser с именем ресурса приложения и проверьте requireMention.
Используйте openclaw logs --follow при отправке тестового сообщения для проверки доставки запросов.

Связанная документация: