# Google Workspace в AI-агенте: почему OAuth такой странный и как это всё-таки настроить
Каноническая страница: https://plainews.ru/posts/google-workspace-agent-oauth-guide
Опубликовано: 2026-09-08T11:01:32.599Z

Три способа подключить Google Workspace к агенту — коннектор, MCP и самописный CLI. Разбираем OAuth, scopes и подводные камни без воды.
Google не даёт просто выписать токен и пойти работать. Вместо этого — проект, приложение, клиент, экран согласия, callback-сервер. Если вы уже потратили час и всё ещё не понимаете, что от вас хотят — эта статья для вас. Разбираем три реальных пути подключения и объясняем, почему Google устроен именно так.

## Три способа, и только один из них «просто работает»

Самый быстрый путь — встроенный коннектор вашего AI-провайдера. В Claude это кнопка Connect в интерфейсе claude.ai: нажал, авторизовался, готово. ChatGPT работает аналогично. Если вы используете только веб-интерфейс или Claude Desktop — остановитесь здесь, дальше вам не нужно.

Проблема возникает, когда вы выходите за пределы UI. Claude Code CLI, запущенный в терминале, коннекторы claude.ai уже не видит. Open-source агенты — тоже. Там нужны два других варианта: MCP-сервер или прямой вызов Google API через CLI-обёртку.

| Способ | Когда подходит | Ограничения |
| --- | --- | --- |
| Коннектор провайдера | Только UI / Claude Desktop | Нет доступа из CLI и open-source агентов |
| MCP-сервер | Хочется стандартного протокола | Официальный MCP сырой, мало методов |
| Самописный CLI-клиент | CLI-агенты, кастомные требования | Нужно один раз написать / сгенерировать |

Официальные MCP от Google на момент написания (сентябрь 2026) работают частично: в Calendar нет доступа к контактам через People API, а MCP для Drive может вообще не запуститься. Сторонние MCP вроде @piotr-agier/google-drive-mcp существуют, но добавляют в контекст агента лишние методы и могут содержать баги. Практичнее всего — попросить агента написать минимальный CLI-клиент под ваши задачи, а потом вызывать его как обычную команду в терминале.

## Почему Google не даёт просто токен

Google Cloud изначально проектировался для компаний, а не для одного разработчика с ноутбуком. Большинство сервисов поддерживают PAT (Personal Access Token): создал, выдал права, вставил в .env. Google так не умеет.

Вместо этого — OAuth 2.0. Механизм рабочий, но требует понять несколько сущностей:

**Google Cloud Project** — контейнер для всего. По умолчанию у вас уже есть «My First Project».

**Google Auth Platform** — раздел внутри проекта, где настраивается «приложение». Приложение — это сущность, которой пользователь даёт разрешения. Один проект = одно приложение. Название, ссылка на homepage и privacy policy — заполните чем угодно, хоть ссылкой на GitHub.

**Client (Клиент)** — набор учётных данных внутри приложения, привязанный к платформе (Desktop, Web и т.д.). Именно отсюда скачивается JSON с client_id и client_secret.

**Scopes** — конкретные разрешения: читать почту, создавать события в календаре и т.д. Запрашиваются при авторизации.

```json
{
  "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"]
  }
}
```

client_secret здесь не особо секретный: сам по себе он доступ к API не даёт, только подтверждает client_id при обмене кода на токен.

## Как работает OAuth-флоу на практике

Вот что происходит, когда ваш CLI-клиент или MCP-сервер запрашивает доступ:

1. Клиент формирует ссылку на accounts.google.com с параметрами: какое приложение, какие scopes, куда вернуть результат.
2. Вы открываете ссылку в браузере, видите экран согласия, нажимаете «Разрешить».
3. Google редиректит браузер на callback-адрес — в случае Desktop-клиента это http://localhost:<порт>.
4. Ваш клиент в этот момент держит маленький веб-сервер на этом порту и ловит запрос.
5. В запросе — одноразовый код, не токен. Клиент сам обменивает его на токены прямым запросом к https://oauth2.googleapis.com/token.

После этого python-библиотека google-auth сохраняет токены примерно в таком формате:

```json
{
  "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"]
}
```

refresh_token — долгоживущий, именно он позволяет получать новые token без повторной авторизации через браузер.

> **К сведению.** На странице Clients в Google Cloud Console вы увидите ещё два типа учётных данных: API Key и Service Account. API Key не идентифицирует пользователя. Service Account работает с личными данными только через администратора Google Workspace (корпоративная версия) — для личного аккаунта он бесполезен.

## Минимальный CLI-клиент: что попросить у агента

Если вы решили идти по пути самописного клиента, дайте агенту конкретное задание. Пример промпта:

```plain
Напиши CLI на Python, который:
1. Читает credentials.json (OAuth Desktop-клиент Google)
2. При первом запуске открывает браузер для авторизации и сохраняет token.json
3. Поддерживает команды:
   - calendar list --days 7
   - calendar create --title "..." --start "2026-09-10T10:00" --end "..." --attendees "a@b.com,c@d.com"
   - drive list --folder-id "..."
   - drive upload --file ./report.pdf --folder-id "..."
Scopes: calendar, drive.file, contacts.readonly
```

Агент напишет клиент, вы один раз пройдёте авторизацию в браузере, токены сохранятся в token.json. Дальше агент вызывает CLI как обычную bash-команду — никаких MCP, никакого лишнего контекста.

```bash
python gcal.py calendar list --days 7
python gcal.py calendar create --title "Sync" --start "2026-09-15T14:00" --end "2026-09-15T15:00"
```

## Где это ломается

**Настройка на сервере без браузера.** Callback приходит на localhost, но браузера на сервере нет. Решение — SSH-туннель: пробросьте локальный порт на сервер (ssh -R 8080:localhost:8080 user@server), пройдите авторизацию локально, скопируйте token.json на сервер.

**Экран согласия в статусе «Testing».** Пока приложение не прошло верификацию Google, refresh_token живёт 7 дней, потом отзывается. Для личного использования переведите приложение в статус «In production» — верификация не нужна, если вы единственный пользователь.

**Официальный MCP Calendar без People API.** Если агенту нужны контакты для автодополнения участников встречи — официальный MCP не поможет. Придётся добавить scope https://www.googleapis.com/auth/contacts.readonly и вызывать People API вручную.

**Протухший `token`.** ya29.a0... живёт около часа. Библиотека google-auth обновляет его автоматически при наличии refresh_token. Если пишете клиент не на Python — убедитесь, что реализовали refresh-логику.

## Что попробовать дальше

Когда базовое подключение работает, следующий шаг — дать агенту доступ к Google Tasks и Google Meet через те же scopes в одном клиенте. Также стоит посмотреть на agno Google Calendar Context Provider — он оборачивает OAuth-флоу в готовый провайдер с переменными окружения GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET, что удобно для быстрого старта в Python-агентах.

---

## FAQ

### Нужно ли платить за Google Cloud, чтобы подключить Calendar и Drive?

Нет. Google Calendar API и Google Drive API входят в бесплатный уровень с достаточными лимитами для личного использования. Платить нужно только если вы превышаете квоты — для одного агента это практически нереально.

### Чем отличается OAuth Desktop-клиент от Web-клиента?

Desktop-клиент использует http://localhost как redirect URI и не требует публичного домена. Web-клиент нужен, если callback должен приходить на внешний URL. Для агента на локальной машине — всегда Desktop.

### Можно ли использовать один token.json для нескольких агентов?

Да, если они запускаются под одним пользователем и читают один файл. Главное — не запускать их одновременно с записью в файл, иначе возможна гонка при обновлении токена.

### Почему refresh_token иногда исчезает из ответа Google?

Google возвращает refresh_token только при первой авторизации или если пользователь явно отозвал доступ и авторизовался заново. Если токен не сохранился — отзовите доступ в myaccount.google.com/permissions и пройдите авторизацию снова.

### Как добавить новый scope, не заставляя пользователя заново авторизоваться?

Никак — при изменении набора scopes нужна повторная авторизация. Поэтому лучше сразу запросить все нужные разрешения с запасом, чем добавлять их по одному.

## Источники

- Habr AI: Как подключить Google Calendar и Google Drive к агенту или Почему все так сложно