gog — CLI-инструмент для работы с Gmail, Calendar, Drive, Docs, Sheets, Slides и другими сервисами Google и Google Workspace из терминала. В этом руководстве разберём установку, авторизацию, безопасное подключение к Codex и несколько сценариев, результат которых можно проверить самостоятельно.

🔗
Это продолжение руководства Google Workspace для бизнеса: руководство для новичка. Там описаны подключение домена, почты и доступов. Здесь — управление Workspace из терминала и передача ограниченного набора операций агенту.

Что такое gog и зачем он нужен пользователю Codex

gog, пакет gogcli, — CLI на Go с командами для сервисов Google и Google Workspace. Он работает через ваш Google Cloud-проект и обращается к Google API от имени авторизованного аккаунта.

Для агента gog служит предсказуемым интерфейсом к Workspace. Команды могут возвращать структурированный JSON, а встроенные ограничения помогают отделить чтение данных от операций записи.

💡
CLI (command-line interface) — программа, которой управляют текстовыми командами в терминале. Команду можно повторить вручную, включить в сценарий автоматизации или разрешить агенту.

Какие сервисы и задачи поддерживает gog

СервисПримеры задач
GmailПоиск и чтение писем, работа с черновиками, отправка, ответы, вложения и автоматические сценарии
CalendarПросмотр и создание событий, работа с несколькими календарями и периодами
DriveПоиск файлов, дерево папок, анализ занятого места, загрузка и аудит
Docs, Sheets, SlidesЧтение и изменение документов и таблиц, создание презентаций из Markdown
Workspace AdminПользователи, организационные подразделения и группы после отдельной настройки административного доступа
Другие сервисыForms, Apps Script, Contacts/People, Tasks, Classroom, Chat, Keep, YouTube, Photos и другие поддерживаемые поверхности

Актуальное дерево команд конкретной установленной версии можно получить без догадок:

gog schema --json

Схема содержит команды, аргументы, флаги, форматы вывода, коды завершения и действующие ограничения безопасности для текущего запуска.

Установка и OAuth-авторизация

Для начала потребуются Google-аккаунт, проект в Google Cloud и OAuth-клиент типа Desktop app. В проекте включите только те API, которые собираетесь использовать.

1. Установите gog

На macOS через Homebrew:

brew install openclaw/tap/gogcli
gog --version

Другие варианты установки, включая Docker, Windows ZIP и сборку из исходников, перечислены в официальной документации.

2. Создайте OAuth-клиент

В Google Cloud Console:

  1. Создайте или выберите проект.
  2. Включите нужные API, например Gmail, Calendar и Drive.
  3. Настройте экран согласия OAuth.
  4. Создайте OAuth-клиент типа Desktop app и скачайте JSON-файл.

Для просмотра плана автоматизированной настройки без изменений используйте:

gog --dry-run --json --no-input auth setup you@example.com --gcloud-project my-gog-project --enable-apis --open-console

Проверочный запуск показывает полный план и не создаёт проект, не включает API, не сохраняет credentials, не открывает браузер и не запускает OAuth-авторизацию.

3. Сохраните OAuth-клиент

gog auth credentials ~/Downloads/client_secret.json

Файл копируется в пользовательский каталог конфигурации gog с правами 0600. Это отдельный файл конфигурации; полученный после авторизации токен обновления (refresh token) хранится в системном хранилище секретов: Keychain на macOS, Secret Service на Linux или Credential Manager на Windows.

4. Авторизуйте аккаунт

gog auth add you@example.com --services gmail,calendar,drive

Откроется браузер с экраном согласия Google. Явный список --services помогает не запрашивать доступ к ненужным сервисам.

Адрес должен принадлежать личному Google Account или аккаунту Google Workspace. Обычный почтовый ящик, не связанный с Google Account, пройти такую авторизацию не сможет.

Личный аккаунт gmail.com подходит для обычных пользовательских API, включая Gmail, Calendar, Drive, Docs, Sheets, Slides, Forms, Apps Script, Contacts/People, Tasks и Classroom. Для Admin Directory, Cloud Identity Groups, Chat и Keep с делегированием на уровне домена (domain-wide delegation) нужен управляемый домен.

⚠️
OAuth-приложения со статусом External + Testing выдают токены обновления для пользовательских разрешений, которые могут истекать через семь дней. Для постоянного личного использования официальная документация рекомендует перевести приложение в режим In production, а затем при необходимости повторить авторизацию с теми же сервисами и --force-consent.

Для личного непроверенного приложения режим In production не означает прохождение верификации. Для чувствительных разрешений Google показывает предупреждение, а приложение остаётся ограничено лимитом в 100 пользователей за весь срок.

5. Проверьте авторизацию

gog auth list --check
gog auth doctor --check

После этого выполните минимальную операцию чтения:

gog calendar events --today

Успешная команда и ожидаемый список событий подтверждают, что аккаунт, OAuth-клиент и Calendar API работают вместе. Пустой список сам по себе не означает ошибку, если на сегодня нет событий.

6. Выберите аккаунт по умолчанию

Для постоянного выбора откройте менеджер аккаунтов и нажмите Set default рядом с нужной записью:

gog auth manage

Сохранённый выбор используется, когда не передан --account и не установлена переменная GOG_ACCOUNT. Для выбора аккаунта только в текущей оболочке:

export GOG_ACCOUNT=you@example.com

Явный флаг --account удобнее для автоматизации, потому что делает выбранную учётную запись видимой прямо в команде.

⚠️
Не коммитьте OAuth client JSON и не передавайте агенту содержимое credentials или токенов. Запрашивайте только нужные сервисы и используйте отдельные ограничения для команд агента.

Машинный вывод и коды завершения

Для автоматизации доступны два основных формата:

  • --json возвращает структурированный результат;
  • --plain возвращает стабильный TSV.

Основные данные выводятся в stdout, а подсказки, прогресс и предупреждения — в stderr. Благодаря этому результат можно безопаснее передавать в следующий этап сценария.

gog --json gmail search 'newer_than:7d' --max 10

В автоматических запусках добавляйте --no-input, чтобы процесс не зависал в ожидании ответа. Для ветвления используйте код завершения, а не текст ошибки. Среди стабильных кодов: 0 — успех, 2 — ошибка использования, 4 — требуется авторизация, 5 — объект не найден, 6 — недостаточно прав, 7 — превышена квота, 8 — временная ошибка, 10 — отсутствует локальная конфигурация.

Безопасная работа с данными Workspace

Для агентного контура полезны несколько независимых ограничений.

Режим только чтения

Флаг --readonly блокирует изменяющие запросы до отправки в сеть. Он не зависит от названия команды или выданных OAuth-разрешений и распространяется на дочерние процессы MCP.

gog --readonly --account you@example.com gmail search 'newer_than:7d' --json

Запрет интерактивного ввода

Добавляйте --no-input в CI и фоновых процессах. Интерактивные браузерные команды в этом режиме завершаются сразу, а не ждут действий пользователя.

Недоверенный текст для агента

Если текст из Gmail, Docs или других Google-сервисов будет читать языковая модель, используйте --wrap-untrusted. Флаг оборачивает свободный текст в формат недоверенных данных и снижает риск того, что содержащаяся в документе инструкция будет принята за команду агенту.

gog --readonly --no-input --wrap-untrusted --json gmail search 'newer_than:7d'

Для чтения Gmail также доступен --sanitize-content. В gmail get этот флаг возвращает санитизированные заголовки и тело сообщения. Это отдельный механизм: он не заменяет --wrap-untrusted, который нужен для передачи недоверенного текста агенту.

🔴
Начинайте с --readonly, --no-input, --wrap-untrusted и точного списка разрешённых команд. Права записи открывайте только для конкретной операции.

Подключение через MCP

gog может запускать MCP-сервер по stdio. MCP (Model Context Protocol) — протокол, через который агентный клиент получает типизированные инструменты с фиксированными схемами. Универсального инструмента для выполнения произвольных команд сервер не создаёт.

По умолчанию регистрируются инструменты чтения. Инструменты записи скрыты, пока их явно не разрешили политикой или флагом --allow-write. Фильтр --allow-tool дополнительно сужает доступную поверхность.

Минимальная конфигурация MCP-клиента:

{
  "command": "gog",
  "args": ["--account", "you@example.com", "mcp"]
}

Вариант только для чтения Docs и Sheets:

{
  "command": "gog",
  "args": [
    "--account", "you@example.com",
    "--enable-commands-exact", "mcp,docs.cat,sheets.get",
    "mcp",
    "--allow-tool", "docs_get,sheets_read_range"
  ]
}

Проверьте итоговый набор инструментов до подключения клиента:

gog --account you@example.com mcp --allow-tool docs_get,sheets_read_range --list-tools

MCP-сервер автоматически добавляет дочерним командам --json, --wrap-untrusted, --no-input и --color=never. Для операций записи всё равно нужны явные разрешения. Флаг --allow-tool не открывает запись без --allow-write, если она не разрешена узкой постоянной политикой.

Полезные сценарии

Сводка входящих писем

Задача: получить ограниченную выборку писем за неделю для последующего разбора агентом.

gog --readonly --account you@example.com --no-input --wrap-untrusted --json gmail search 'newer_than:7d' --max 10

Наблюдаемый результат — JSON со списком найденных сообщений в stdout. Если писем нет, успешный пустой результат не означает ошибку. Этот сценарий предназначен для чтения и не подходит для отправки писем или массовых изменений.

Подготовка к встречам

Задача: передать агенту сегодняшнее расписание без права менять календарь.

gog --readonly --account you@example.com --json calendar events --today

Результат можно проверить по названиям и времени событий в JSON. Если нужен другой часовой пояс, сначала сверяйте доступные флаги через gog schema --json или справку установленной версии. Сценарий не подходит для создания и изменения событий, поскольку --readonly блокирует изменяющие запросы.

Аудит папки Google Drive

Задача: увидеть структуру папки и самые крупные объекты без изменений.

gog --readonly --account you@example.com drive tree --parent <folderId> --depth 2
gog --readonly --account you@example.com drive du --parent <folderId> --max 20 --json

Первая команда показывает дерево, вторая — использование места. --readonly служит дополнительной защитой, даже если выбранная команда предназначена для чтения. Для запуска нужны идентификатор папки и права на её чтение; сам флаг не выдаёт доступ к Drive.

Чтение Docs и Sheets через MCP

Задача: разрешить агенту читать только документ и диапазон таблицы.

Поднимите сервер с --allow-tool docs_get,sheets_read_range, затем убедитесь через --list-tools, что другие инструменты отсутствуют. Наблюдаемый результат — в списке зарегистрированы только два разрешённых инструмента, а инструменты записи не показаны. Этот список подтверждает набор зарегистрированных инструментов, но не проверяет OAuth-доступ к конкретному аккаунту; для этого используйте auth doctor --check и минимальную команду чтения.

Создание презентации из Markdown

Когда агенту действительно нужна запись и вы осознанно выдали соответствующие права, презентацию можно создать командой:

gog slides create-from-markdown "Weekly update" --content-file slides.md

Перед реальным запуском проверьте команду через актуальную схему и используйте --dry-run, если он поддерживается выбранной операцией. Результат записи проверяйте по возвращённому идентификатору и наличию презентации в нужном аккаунте. Сценарий требует локального файла Markdown и прав записи, поэтому не подходит для профиля только для чтения.

Административные операции Workspace

После настройки Admin SDK и делегирования полномочий администратор может создавать пользователей и просматривать организационные подразделения:

gog --account admin@example.com admin users create ada@example.com --first-name Ada --last-name Lovelace --change-password
gog --account admin@example.com admin orgunits list --type all

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

Версии и изменения после первой публикации

Материал проверен 11 сентября 2026 года. В официальном changelog последний опубликованный релиз — 0.39.1 от 5 сентября 2026 года; 0.39.2 на момент проверки помечена как Unreleased.

В релизах с июня 2026 года в gog появились и изменились важные для агентных сценариев возможности: глобальный --readonly, команда auth setup, постоянные MCP-политики, дополнительные ограничения сетевых запросов, защита вывода недоверенного контента и более точные коды ошибок. Перед переносом готового сценария между версиями проверяйте:

gog --version
gog schema --json
gog auth doctor --check --json --no-input

Вывод схемы описывает текущий запуск, но сам по себе не проверяет credentials, токен обновления и доступ к Google API. Для этого нужен отдельный auth doctor --check и минимальная реальная команда чтения.

Стоимость и квоты Gmail API

При использовании gog учитывайте ограничения запросов и возможные расходы Google API: они зависят от правил Google и вашего Cloud-проекта.

По странице Google, обновлённой 10 сентября 2026 года и проверенной 11 сентября 2026 года, Gmail API использует единицы квоты (quota units):

  • 1 200 000 единиц в минуту на проект;
  • 6 000 единиц в минуту на пользователя в проекте;
  • 80 000 000 единиц в сутки на проект как суточный порог.

Стоимость одного вызова зависит от метода: например, messages.list расходует 5 единиц, messages.get — 20, а messages.send — 100. Для проектов, использовавших API с ноября 2025 по апрель 2026 года, могут сохраняться прежние квоты; проекты, созданные 1 мая 2026 года или позже, подпадают под новую модель.

Google указывает, что стандартное использование Gmail API пока не требует дополнительной платы. Превышение квот планируется сделать платным позже в 2026 году; Google обещает сообщить детали биллинга минимум за 90 дней до изменений. Проверяйте актуальные условия на официальной странице квот Gmail API.

При кодах 7 и 8 автоматизация должна ограничивать число повторов и учитывать Retry-After. gog ограничивает ожидание по этому заголовку 60 секундами на одну повторную попытку.

Официальные ссылки

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

Следующий шаг

Если вы ещё не подключили домен, почту и доступы к Google Workspace, начните с руководства по Google Workspace для бизнеса.

Ограниченный доступ к Workspace полезен, когда агент работает с почтой и документами по повторяемому сценарию.

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov