Подключение AI-агента к своему Google-аккаунту

Часть 0

Что мы вообще собираемся сделать

Это самая важная часть. Если понять её, все остальные шаги станут очевидными.

Проблема

Программа gws сама по себе — пустая. У неё нет никакого доступа к Google. И Google никогда не даст сторонней программе просто так залезть в чужую почту — иначе любой мог бы читать чужие письма.

Решение, которое придумал Google

Ты создаёшь своё собственное приложение внутри системы Google для разработчиков. А потом сам себе выдаёшь разрешение на доступ к своей же почте.

Звучит странно, но это ровно так и работает. Ты одновременно оказываешься в трёх ролях:

Программа gws — просто исполнитель. Она берёт данные твоего приложения и от его имени стучится в Gmail.

Аналогия

Представь, что Gmail — это охраняемое здание.

• Google не пускает внутрь незнакомцев с улицы.
• Поэтому ты регистрируешь свою фирму — это будет «проект» на сайте Google.
• Фирме выдают документы — файл с ключами, ты его скачаешь.
• Дальше ты как жилец здания подписываешь разрешение, что сотрудникам этой фирмы можно заходить в твою квартиру — это экран «Разрешить доступ» в браузере.
• После этого сотрудник фирмы — программа gws — ходит в здание с пропуском.

Вся длинная возня ниже — это регистрация фирмы и подписание разрешения. Один раз.

Порядок действий целиком

Часть 1

Словарь

Все термины, которые встретятся дальше. Возвращайся сюда, если что-то непонятно.

Терминал

Окно, где вместо кнопок печатают текстовые команды. На Mac открывается так: нажми Cmd + Пробел, набери «Терминал», нажми Enter. Появится окно с текстом. Команды из этой инструкции копируешь туда и жмёшь Enter.

Команда

Строка текста, которую ты вставляешь в Терминал. После Enter компьютер её выполняет. Если в ответ ничего не написалось — обычно это значит, что всё прошло хорошо.

CLI

Программа, которой управляют командами в Терминале, а не мышкой. gws — это CLI.

Homebrew (brew)

Магазин приложений для Терминала на Mac. Через него gws ставится одной командой.

Google Cloud

Отдельный сайт Google для разработчиков, console.cloud.google.com. Не путать с Google Диском. Это админка, где создают приложения.

Проект

Папка-контейнер внутри Google Cloud. В ней лежат настройки твоего приложения: какие сервисы включены, какие ключи выданы. Создаётся бесплатно, за секунды. Это не сервер и не платная услуга.

API

«Розетка», через которую программа подключается к сервису Google. У каждого сервиса своя: Gmail API, Drive API, Calendar API. В новом проекте все розетки выключены, каждую надо включить вручную одной кнопкой.

OAuth

Способ дать программе доступ, не сообщая ей свой пароль. Ты нигде не будешь вводить пароль от Google в gws. Вместо этого браузер спросит: «Приложение хочет читать твою почту — разрешаешь?»

OAuth-клиент

Паспорт твоего приложения. Пара «номер + секретный код». Скачивается файлом.

Desktop app

Тип приложения, который надо выбрать при создании паспорта. Означает «программа, запускаемая на компьютере». Любой другой тип не заработает.

client_secret.json

Имя файла-паспорта. Ты его скачаешь и положишь в определённую папку.

Scope (право)

Конкретное разрешение. Google не выдаёт «доступ ко всему», он выдаёт отдельные права: «читать письма», «отправлять письма», «смотреть календарь». Прав очень много, у одного Gmail их полтора десятка.

Экран согласия

Та самая страница «Приложение просит доступ к…». Её внешний вид надо один раз настроить.

Testing / In production

Состояние твоего приложения. Testing — черновик: работает только для аккаунтов, которые ты явно перечислил. In production — опубликовано. Разница важна, о ней в Части 6.

Test users

Список email-адресов, которым разрешено пользоваться приложением в статусе Testing. Свой адрес туда надо вписать руками, иначе ничего не заработает.

Токен

Электронный пропуск, который Google выдаёт программе после твоего «Разрешить». Подробно — в Части 2.

~ (тильда)

Сокращение для твоей домашней папки, то есть /Users/твоё_имя. Когда написано ~/.config/gws, имеется в виду папка gws внутри папки .config внутри домашней. Папки, чьё имя начинается с точки, в Finder по умолчанию не видны — чтобы показать, нажми Cmd + Shift + . (точка).

Часть 2

Как работают пропуска (токены)

Это нужно понять заранее, иначе через неделю всё «сломается» и будет непонятно почему.

После того как ты нажмёшь «Разрешить», Google выдаст программе два разных пропуска.

Связь между ними такая: когда часовой пропуск протухает, программа молча идёт к Google с абонементом и получает новый часовой пропуск. Ты этого не замечаешь. Это происходит незаметно круглые сутки.

Проблема возникает, когда протухает сам абонемент. Тогда получать новые пропуска не по чему, и всё встаёт.

Оба пропуска хранятся зашифрованными на твоём компьютере в папке ~/.config/gws, а ключ шифрования — в Связке ключей macOS (Keychain). Следствие: если удалить эту папку — придётся входить заново.

Часть 3

Установка программы

Открой Терминал: Cmd + Пробел → «Терминал» → Enter.

Шаг 3.1 · Проверь, есть ли Homebrew

Вставь и нажми Enter:

brew --version

• Вывелось что-то вроде Homebrew 4.x.x → переходи к шагу 3.2.
• Написало command not found → Homebrew нет, ставим:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Установка спросит пароль от компьютера. При вводе пароля символы не отображаются — это нормально, печатай вслепую и жми Enter. Займёт несколько минут. В конце может попросить выполнить ещё пару команд — сделай, что напишет, и перезапусти Терминал.

Шаг 3.2 · Ставим gws

brew install googleworkspace-cli

Шаг 3.3 · Проверяем

gws --version

Должен вывестись номер версии. Если да — программа стоит. Прав на твою почту у неё пока ноль, это дальше.

Часть 4

Настройка на стороне Google

Всё в браузере. Открой console.cloud.google.com и войди тем самым аккаунтом Gmail, к которому хочешь дать доступ. При первом входе сайт может попросить принять условия — прими.

Шаг 4.1 · Создать проект

1. Вверху слева, рядом с логотипом Google Cloud, есть выпадающий список проектов. Нажми на него.
2. В открывшемся окне справа вверху — New Project.
3. Project name: напиши gws-cli.
4. Create.
5. Подожди 15–20 секунд, пока проект создастся.
6. Обязательно убедись, что в списке проектов вверху выбран именно gws-cli. Все следующие шаги делаются внутри него. Это частая ошибка — настроить всё не в том проекте.
7. На главной странице проекта найди строку Project ID — что-то вроде gws-cli-473829. Скопируй его куда-нибудь, он понадобится дальше.

Шаг 4.2 · Включить три сервиса

Мы подключаем почту, диск и календарь. Каждый включается отдельно.

1. В меню слева (три полоски вверху слева, если меню скрыто) выбери APIs & Services → Library.
2. В поиске набери Gmail API, открой найденное, нажми синюю Enable. Подожди, пока прогрузится.
3. Вернись в Library, найди Google Drive API, нажми Enable.
4. Снова в Library, найди Google Calendar API, нажми Enable.

Если позже захочешь ещё Документы и Таблицы — включишь Google Docs API и Google Sheets API тем же способом. Пока не надо, почему — в Части 7.

Шаг 4.3 · Настроить экран согласия

Перейди по адресу, подставив вместо ТВОЙ_PROJECT_ID то, что скопировал в шаге 4.1:

https://console.cloud.google.com/apis/credentials/consent?project=ТВОЙ_PROJECT_ID

Google недавно переименовал этот раздел в Google Auth Platform, там вкладки Overview, Branding, Audience, Clients, Data Access. Если увидишь другой внешний вид — суть та же, ищи поля по названиям.

Заполни:

• App name — gws-local. Это название ты потом увидишь на экране «Разрешить доступ».
• User support email — выбери свой gmail из списка.
• Audience (или User type) — External. Не пугайся слова «External», оно не значит «доступно всем». Для бесплатного аккаунта это единственный возможный вариант, второй (Internal) существует только для корпоративных доменов. Приложение всё равно будет работать только для тех адресов, которые ты сам впишешь.
• Developer contact information — свой gmail.
• Нажми Save.

Шаг 4.4 · Вписать себя в список разрешённых

На той же странице найди вкладку Audience (в старом интерфейсе — блок Test users).

1. Нажми Add users.
2. Впиши свой адрес Gmail — тот самый, к которому даёшь доступ.
3. Save.

Шаг 4.5 · Создать паспорт приложения и скачать файл

Перейди по адресу:

https://console.cloud.google.com/apis/credentials?project=ТВОЙ_PROJECT_ID

1. Вверху нажми Create credentials → в списке выбери OAuth client ID.
2. Application type → Desktop app. Это обязательно: при любом другом типе вход завершится ошибкой redirect_uri_mismatch, потому что программа ловит ответ Google на твоём же компьютере, а так разрешено делать только приложениям типа Desktop.
3. Name — любое, например gws.
4. Create.
5. Появится окно с номером и секретным кодом. Нажми Download JSON. В папку загрузок скачается файл вроде client_secret_12345-abcde.apps.googleusercontent.com.json.

Теперь положим его туда, где программа его ищет. Вернись в Терминал и выполни три команды по очереди:

mkdir -p ~/.config/gws

mv ~/Downloads/client_secret_*.json ~/.config/gws/client_secret.json

ls -l ~/.config/gws/

Последняя команда должна показать строку с файлом client_secret.json. Имя должно быть ровно таким — программа ищет файл по этому имени.

Часть 5

Вход и проверка

Шаг 5.1 · Вход

gws auth login -s gmail,drive,calendar

Если Терминал ответит, что не понимает -s, напиши длинную форму:

gws auth login --scopes gmail,drive,calendar

Шаг 5.2 · Что произойдёт дальше

1. В Терминале появится длинная ссылка, браузер откроется сам. Если не открылся — скопируй ссылку из Терминала в браузер вручную.
2. Выбери свой аккаунт Google.
3. Появится красный экран «Google hasn't verified this app». Это нормально и ожидаемо: приложение написал ты сам для себя, проверка Google нужна только тем, кто раздаёт приложение посторонним. Нажми Advanced (внизу слева, мелким шрифтом) → Go to gws-local (unsafe).
4. Появится список прав с галочками. Отметь нужные или нажми Select all. Затем Continue.
5. Браузер напишет что-то вроде «authentication flow has completed» — можешь закрывать вкладку.
6. Вернись в Терминал, там будет подтверждение входа.

Если на четвёртом пункте Google ругнётся на количество прав — значит, даже три сервиса не влезли в лимит. Тогда сузь до одного и добавляй по мере надобности:

gws auth login -s gmail

Шаг 5.3 · Проверка

Три команды. Каждая должна что-то вывести.

Непрочитанные письма — кто, о чём, когда:

gws gmail +triage

Ближайшие события календаря:

gws calendar +agenda

Пять последних файлов на Диске:

gws drive files list --params '{"pageSize": 5, "fields": "files(id,name)"}'

Если все три отработали — настройка закончена.

Часть 6

Что делать с «протухает раз в неделю»

Напоминание из Части 2: пока приложение в статусе Testing, Google отзывает пропуск через 7 дней. Симптом — команды перестают работать, появляется ошибка invalid_grant.

Вариант А — ничего не делать

Раз в неделю выполняешь одну команду и делаешь два клика в браузере. 30 секунд.

gws auth login -s gmail,drive,calendar

Вариант Б — опубликовать приложение

Зайди на страницу экрана согласия (адрес из шага 4.3), вкладка Audience → кнопка Publish app.

Что изменится: статус станет In production, семидневный отзыв пропуска и лимит на 100 разрешённых адресов исчезнут. Красный экран «Google hasn't verified this app» останется — он не денется без официальной проверки, но нажимать «Advanced → Go to» надо только при входе, то есть теперь очень редко.

Проверка Google формально не требуется для приложений личного пользования, которыми пользуется меньше 100 человек.

Часть 7

Как добавить сервисы позже

Тут есть тонкость, из-за которой люди застревают. Рубильника два, и нужны оба.

• Включил API, но не запросил право → ошибка «нет доступа».
• Запросил право, но не включил API → ошибка accessNotConfigured.

Поэтому оба списка всегда должны совпадать. Мы включили три сервиса и вошли с тремя правами — всё сходится.

Чтобы добавить, например, Google Таблицы:

1. На сайте Google: APIs & Services → Library → найти Google Sheets API → Enable.
2. В Терминале войти заново, дописав сервис в список.

gws auth login -s gmail,drive,calendar,sheets

Помни про лимит примерно в 25 прав — с каждым добавленным сервисом ты к нему приближаешься.

Часть 8

Если что-то пошло не так

Программа возвращает понятные коды завершения: 0 — успех, 1 — ошибка на стороне Google, 2 — проблема с доступом, 3 — неправильная команда, 4 — не смогла получить описание сервиса, 5 — внутренний сбой.

Часть 9

Как всё отключить

Три уровня, от мягкого к жёсткому.

Отозвать доступ у приложения

Сама почта не тронута, программа просто мгновенно теряет права. Открой myaccount.google.com/permissions, найди в списке gws-local, нажми Remove access.

Стереть данные входа с компьютера

rm -rf ~/.config/gws

Удалить приложение полностью

На сайте Google Cloud удалить OAuth-клиент, при желании — весь проект (Settings → Shut down). Проект удаляется с отсрочкой в 30 дней, всё это время удаление можно отменить.

Часть 10

Что не работает на бесплатном Gmail

Это ограничение не программы, а самого Google — таких сервисов для личных аккаунтов просто не существует:

• Admin SDK — управление сотрудниками организации
• Google Chat — рабочие пространства
• Workspace Events
• Vault — архивирование для юристов

Работает полностью: Gmail, Google Диск, Календарь, Документы, Таблицы, Задачи, Презентации, Apps Script.

Часть 11

Подключение к AI-агенту

Этот раздел не обязателен для того, чтобы всё работало — он про то, как «объяснить» агенту, какими командами пользоваться.

Команды ниже требуют установленного Node.js. Проверить — node --version; если не установлен — brew install node. Куда именно установятся инструкции, зависит от того, каким агентом ты пользуешься. Если не уверена — пропусти этот раздел и спроси.

После того как проверка из шага 5.3 прошла:

npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-gmail

npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-drive

npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-calendar

Напоследок

Про сам инструмент — трезво

Google Workspace CLI (gws) лежит в репозитории под организацией Google на GitHub, но с явной пометкой, что это не официально поддерживаемый продукт Google. Проект пока не дошёл до версии 1.0, и авторы прямо предупреждают, что ломающие изменения возможны.

Что это значит на практике: после обновления команда может начать работать иначе. Для личного рабочего окружения это приемлемо, для критичных процессов — нет.

По безопасности: доступ выдаётся широкий — вся почта, весь диск, весь календарь. Ставить стоит только на свой доверенный компьютер. Если хочется подстраховаться — можно завести под это отдельный аккаунт Google с ограниченным содержимым и подключать агента к нему.