Google Chat (Chat API)

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

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

  1. Создайте проект Google Cloud и включите Google Chat 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>.
    • Введите ваш email адрес (например [email protected]) в текстовое поле.
    • Нажмите Save внизу.
  6. Включите статус приложения:
    • После сохранения обновите страницу.
    • Найдите секцию App status (обычно сверху или снизу после сохранения).
    • Измените статус на Live - available to users.
    • Нажмите Save снова.
  7. Настройте OpenClaw с путем к service account + webhook audience:
    • Env: GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json
    • Или config: channels.googlechat.serviceAccountFile: "/path/to/service-account.json".
  8. Установите тип webhook audience + значение (соответствует конфигурации вашего Chat app).
  9. Запустите gateway. Google Chat будет отправлять POST на путь вашего webhook.

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

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

  1. Перейдите в Google Chat.
  2. Нажмите иконку + (плюс) рядом с Direct Messages.
  3. В строке поиска (где обычно добавляете людей) введите App name, который вы настроили в Google Cloud Console.
    • Примечание: Бот не появится в списке просмотра "Marketplace", потому что это приватное приложение. Вы должны искать его по имени.
  4. Выберите вашего бота из результатов.
  5. Нажмите Add или Chat, чтобы начать диалог 1:1.
  6. Отправьте "Hello", чтобы активировать ассистента!

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

Webhooks Google Chat требуют публичной HTTPS конечной точки. Для безопасности выставляйте только путь /googlechat в интернет. Держите панель OpenClaw и другие чувствительные конечные точки в вашей приватной сети.

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

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

  1. Проверьте, к какому адресу привязан ваш gateway:

    ss -tlnp | grep 18789

    Обратите внимание на IP-адрес (например, 127.0.0.1, 0.0.0.0 или ваш Tailscale IP типа 100.x.x.x).

  2. Выставьте панель только для tailnet (порт 8443):

    # Если привязан к localhost (127.0.0.1 или 0.0.0.0):
tailscale serve --bg --https 8443 http://127.0.0.1:18789

# Если привязан только к Tailscale IP (например, 100.106.161.80):
tailscale serve --bg --https 8443 http://100.106.161.80:18789

  3. Выставьте публично только путь webhook:

    # Если привязан к localhost (127.0.0.1 или 0.0.0.0):
tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat

# Если привязан только к Tailscale IP (например, 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

Ваш публичный URL webhook будет: 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

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

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

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

  1. Google Chat отправляет webhook POST на gateway. Каждый запрос включает заголовок Authorization: Bearer <token>.
  2. OpenClaw проверяет токен против настроенных audienceType + audience:
    • audienceType: "app-url" → audience — это ваш HTTPS URL webhook.
    • audienceType: "project-number" → audience — это номер проекта Cloud.
  3. Сообщения маршрутизируются по space:
    • Личные сообщения используют ключ сессии agent:<agentId>:googlechat:dm:<spaceId>.
    • Spaces используют ключ сессии agent:<agentId>:googlechat:group:<spaceId>.
  4. Доступ к личным сообщениям по умолчанию требует сопряжения. Неизвестные отправители получают код сопряжения; утвердите с помощью:
    • openclaw pairing approve googlechat <code>
  5. Групповые spaces требуют @-упоминания по умолчанию. Используйте botUser, если обнаружение упоминаний требует имя пользователя приложения.

Цели

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

  • Личные сообщения: users/<userId> или users/<email> (email адреса принимаются).
  • Spaces: 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", "[email protected]"]
      },
      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 также могут передаваться inline с помощью serviceAccount (JSON string).
  • Путь webhook по умолчанию /googlechat, если webhookPath не установлен.
  • Реакции доступны через инструмент reactions и channels action, когда включен actions.reactions.
  • typingIndicator поддерживает none, message (по умолчанию) и reaction (реакция требует пользовательский 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

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

  1. Канал не настроен: Секция channels.googlechat отсутствует в вашей конфигурации. Проверьте с помощью:

    openclaw config get channels.googlechat

    Если возвращает "Config path not found", добавьте конфигурацию (см. Основные моменты конфигурации).

  2. Плагин не включен: Проверьте статус плагина:

    openclaw plugins list | grep googlechat

    Если показывает "disabled", добавьте plugins.entries.googlechat.enabled: true в вашу конфигурацию.

  3. Gateway не перезапущен: После добавления конфигурации перезапустите gateway:

    openclaw gateway restart

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

openclaw channels status
# Должно показать: Google Chat default: enabled, configured, ...

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

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

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

← Назад к документации