Я пишу эту статью, потому что потратил довольно много времени разбираясь с подключением сервисов Google Workspace к Claude Code CLI и OpenClaw. И хочу чтобы другим было проще. Я постарался объяснить что происходит, чтобы когда вы читали инструкции вашего агента или документацию, понимали что от вас хотят.

В статье нет пошагового гайда по настройке какого-то конкретного клиента. Это набор знаний, как настроить любой клиент (например, написанный вашим агентом)

А подключение агента к календарю и почте - тема полезная. Я уже не представляю как ставить встречи на много человек вручную (хотя вьетнамские флешбеки имеются =))

Также, раз уж пишу, расскажу свой тг-канал - Big Ledovsky ? Делюсь мнением про AI через призму руководителя AI-функции и 10 лет опыта в отрасли.

Как подключать агентов к Google Workspace

На самом деле путей подключения немало - целых три. Первый, самый простой - это коннектор вашего провайдера, например Claude или ChatGPT. Там все работает по кнопке connect.

Но этот способ ограничен. Я больше всего использую Claude, поэтому расскажу на его примере. Claude Code может использовать коннектор в облачных сессиях и в локальных сессиях через Claude Desktop. Claude Code CLI, который запускается в терминале, коннекторы claude.ai уже не видит. Если вы используете только UI, не ставите open source агентов, то коннектор - реально лучший вариант. Все что будет дальше, вам не нужно.

Два других способа - это MCP-сервер или API. На момент написания статьи я пришел к выводу, что проще всего использовать API с самописной CLI оберткой.

Google выпустил официальные MCP, но там есть нюансы. Там очень небольшой набор методов. Календарь не имеет доступа к контактам (People API). А MCP драйва у меня вообще не заработал. Наверное через какое-то время MCP доведут до ума, но пока имеем что имеем.

Существует много 3rd party MCP и CLI инструментов. В целом можно использовать их. Но знаете, овчинка выделки не стоит. Могут быть баги, чего-то может не хватать, а заодно они забьют ваш контекст тучей лишних методов. Я просто попросил агента написать свой клиент под конкретно мои требования. Это сейчас быстрее. А дальше агент зовет этот CLI как обычную команду в терминале, ему этого достаточно.

Если интересно, можете посмотреть репозиторий

Как работает авторизация Google Cloud

Главное, что нужно понять и принять - Google Cloud не рассчитан на одиночных пользователей. Он со всеми работает как с компанией.

Google не поддерживает PAT (Personal Access Token). Кажется: дайте мне просто токен, как делают большинство других сервисов, я раздам на него права и буду ходить агентом. Профит!

Но Google так не позволяет. Будь добр создай проект, в нем приложение, в нем клиент и т.д. Как будто ты делаешь сервис на тысячи людей. Потом сам с свое приложение заходи, как внешний пользователь, и получай права.

В качестве механизма авторизации Google предлагает OAuth. Что это значит с практической точки зрения:

• Наш MCP или CLI клиент должен создать ссылку в accounts.google.com. Мы ее открываем в браузере

• В этой ссылке содержится вся нужная информация - для какого приложения и какие права просим, а также по какой ссылке передать результат

• Мы как пользователь смотрим на то какие права нужно предоставить, нажимаем в браузере OK

• После этого Google перекидывает браузер на callback ссылку, которую мы дали. В нашем случае это локальный адрес на компьютере, где наш клиент поднял маленький веб-сервер и ждет. В ссылке приходит не токен, а одноразовый код

• Клиент сам, уже без браузера, обменивает этот код на токены прямым запросом в Google

Если вы настраиваете агента на сервере, то чтобы обработать callback ссылку, вам нужно прокинуть ssh туннель на localhost.

Вы возможно увидите еще два типа учетных данных, кроме OAuth клиента. Это API Key и Service Account. Можете не обращать внимание. API Key не идентифицирует пользователя и используется для технических запросов к проекту. А Service Account получает доступ к личным данным только через администратора организации в корпоративной версии (типа как секретарь), а для личного аккаунта не работает вовсе.

Ликбез используемых сущностей Google Cloud

• Project. Проект. Это просто контейнер для API, настроек доступов, лимитов и др. По умолчанию у вас есть один проект My First Project

• Google Auth Platform. Это набор интерфейсов, который содержит в себе настройки "приложения". Приложение - это сущность, которой пользователь дает доступ. Один проект - это одно приложение. У приложения есть название, и еще ряд параметров - ссылка на домашнюю страницу, privacy policy и др. Заполняем чем угодно, я везде поставил ссылку на свой гитхаб.

• Client. Клиент. Один набор учетных данных, ассоциированный с платформой (Desktop, iOS и т.д.). Т.е. предполагается, что у приложения могут быть разные клиенты. У клиента есть ID, по которому Google понимает, из какого клиента заходит пользователь.

• Scopes. Набор конкретных разрешений, что можно делать. Например, "Разрешить читать почту".

Вот тот JSON, который скачивается со страницы Clients. Секрет тут не особо секретный: client_id - идентификатор вашего клиента, а client_secret подтверждает этот id. Но сам по себе доступ к API он не дает. С помощью client_id мы проходим экран согласий.

{
  "installed": {
    "client_id": "1234567890-abc123.apps.googleusercontent.com",
    "project_id": "my-project-123456",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://oauth2.googleapis.com/token",
    "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
    "client_secret": "GOCSPX-...",
    "redirect_uris": ["http://localhost"]
  }
}

Структура OAuth токенов (так их сохраняет python-библиотека google-auth; у других клиентов формат может отличаться, но набор полей по смыслу тот же):

{
  "token": "ya29.a0...",
  "refresh_token": "1//0g...",
  "token_uri": "https://oauth2.googleapis.com/token",
  "client_id": "1234567890-abc123.apps.googleusercontent.com",
  "client_secret": "GOCSPX-...",
  "scopes": [
    "https://www.googleapis.com/auth/calendar",
    "https://www.googleapis.com/auth/drive"
  ],
  "universe_domain": "googleapis.com",
  "account": "",
  "expiry": "2026-09-05T18:30:00Z"
}

Не вдаваясь в подробности OAuth протокола, самое главное тут - refresh token. Он выдается после прохождения экрана согласия и с помощью него фактически получается доступ. А token - это короткоживущий access token, он живет час, и клиент сам перевыпускает его по refresh token. Токены сохраняются вашим клиентом (CLI или MCP).

Как настраивать OAuth клиент

Все делается в Google Cloud Console (https://console.cloud.google.com/), по большей части на страницах Google Auth Platform. Идем по шагам.

1. Google Auth Platform -> Branding

Нужно заполнить:

• App name - любое название

• User support email - просто ваш email

• App domain: home page, privacy policy, terms of service - везде ставим просто свой гитхаб. Это ок

• Лого - не нужно

• Authorized domain - github.com

• Developer contact information - опять свой email

2. Google Auth Platform -> Audience

• User type: External. Internal доступен только для корпоративных аккаунтов и в приложение могут логиниться только учетки из вашей организации. Неудобно, если у вас есть личный и корпоративный аккаунты

• Publishing status: In production. Testing выдает токены, которые истекают через 7 дней. In production дает бесконечный токен. Точнее, он умирает только если им не пользоваться полгода, отозвать доступ руками или сменить пароль от аккаунта

• Verification: не делаем, это тяжело, это для настоящих приложений на внешних пользователей

3. Google Auth Platform -> Clients

Создаем Desktop клиент. Desktop - важно, т.к. он позволяет делать редирект на localhost после прохождения экрана разрешений. Сохраняем JSON с client_id и client_secret.

Кроме OAuth клиента в проекте нужно включить сами API, к которым будет ходить агент. Ищем по названию и жмем Enable: Google Calendar API, Google Drive API, Gmail API, People API (это контакты и поиск людей в организации). Если этого не сделать, права у токена будут, но запросы будут падать с 403 ошибкой.

5. Первый вход

При первом входе, после выбора аккаунта, Google покажет тревожный экран "Google hasn't verified this app": приложение не проверено, "Back to safety" и все такое. Просто имейте в виду.

Полезные ссылки

• https://console.cloud.google.com/auth/overview - страница Google Auth Platform (Branding, Audience, Clients)

• https://console.cloud.google.com/apis/dashboard - страница APIs & Services. На ней можно смотреть дашборды с количеством запросов к разным API, лейтенси и коды ошибок. Там же, в разделе Library, включаются нужные API

• https://myaccount.google.com/connections - со стороны пользователя: какие приложения имеют доступ к аккаунту, там же доступ можно отозвать

• https://developers.google.com/workspace - документация API и официальных MCP. Можно дать вашему агенту

Заключение

Думаю, вы согласитесь: то, как реализовано подключение агентов к Google Workspace - это сущее безумие. Однако, это можно объяснить. Деньги Google Cloud зарабатывает с корпоративных клиентов. Consumer-сегмент пусть сидит через коннекторы внутри UI готовых приложений.

А мы, обычные инженеры, должны и так быть рады. API в принципе есть и мы можем бесплатно им пользоваться.