Если у вас уже подключён Google Workspace и вы хотите отдать рутину агенту — почту, календарь, диск, документы — вам нужен один бинарь, а не десять вкладок и не самописная обвязка над каждым API. gogcli — это open-source CLI на Go, который закрывает весь Workspace из терминала и одинаково работает из shell-скриптов и из Codex.
Что это
Gogcli — open-source проект (репозиторий openclaw/gogcli, сайт документации gogcli.sh). Один бинарник на Go, который заменяет десяток разрозненных клиентов под каждый сервис Google. Под капотом — стандартные Google APIs, сверху — workflow-команды под конкретные задачи: найти письмо, прочитать безопасно, создать пользователя, отредактировать таблицу, собрать презентацию.
Проект не аффилирован с Google. Лицензия — MIT, можно использовать в коммерческих продуктах, форкать, дорабатывать под себя.
Ключевое правило: gogcli — это не «CLI-обёртка над каждым API». Это workflow-команды, поверх которых уже есть контракт вывода (JSON/TSV), коды возврата и слои безопасности. Агент работает по контракту, а не угадывает флаги.
gws от Google Workspace — другой CLI, построенный на Discovery Service. Тоже легитимный и публичный (github.com/googleworkspace/cli), но с другим подходом: gws ближе к сырому API и подхватывает новые методы динамически. gogcli ставит во главу угла предсказуемый вывод, безопасность по слоям и удобную работу с агентом — об этом подробно ниже.
Зачем нужно
- Один инструмент для всех ключевых сервисов Workspace — Gmail, Calendar, Drive, Docs, Sheets, Slides, Forms, Contacts, Tasks, Apps Script, Admin.
- Стабильный вывод: флаг —json даёт предсказуемый JSON в stdout, флаг —plain — TSV. Прогресс и предупреждения идут в stderr, поэтому пайпы не ломаются.
- Runtime-контракт для агента: команда gog schema —json выдаёт машинно-читаемое описание всех команд, коды выхода и состояние безопасности. Агент читает схему один раз и дальше работает по контракту.
- Слои безопасности встроены в сам инструмент: режим только-чтение (—readonly), запрет отправки Gmail (—gmail-no-send), command guards, обёртка недоверенного контента (—sanitize-content), готовые safety-профили.
- Несколько аккаунтов и OAuth-клиентов в одном конфиге: подходит для работы, личного ящика и админского контура одновременно.
- Режим MCP-сервера: gogcli умеет отдавать типизированные и заранее разрешённые инструменты агентным клиентам — Codex подключается напрямую, без общего мостика в shell.
Как устроено
| Сервис Google | Что делает gogcli |
|---|---|
| Gmail | Поиск по телу писем, чтение, отправка и черновики, фильтры, экспорт rules.xml |
| Calendar | События на сегодня и за период, вторичные календари, создание и обновление встреч |
| Drive | Аудит дерева папок и прав, размеры, инвентаризация (без изменений по умолчанию) |
| Docs | Загрузка Markdown напрямую, форматирование, атомарные пакеты правок |
| Sheets | Добавление строк, изменение графиков, работа с таблицами |
| Slides | Сборка презентации из Markdown, рендер превью слайдов |
| Admin | Создание пользователей, орг-юниты и группы через Admin SDK и domain-wide delegation |
| Forms / Contacts / Tasks / Chat | Шаблоны форм, контакты, задачи, чат-пространства |
| Apps Script / Classroom / YouTube | Управление скриптами, курсами, видео (mutate только под явные флаги) |
| Keep / Groups / Search Console / Analytics | Заметки, группы, вебмастер, аналитика (через service account) |
Внутри gogcli — единый движок workflow-команд, поверх которого лежит тонкий слой Google API. На каждый сервис — свои команды с предсказуемыми флагами. Все write-операции по умолчанию требуют явного подтверждения (например, —apply), read-only операции безопасны из коробки.
Контракт вывода — отдельный модуль: —json собирает структурированный ответ, —plain — TSV для awk/cut, всё остальное (прогресс, подсказки) уходит в stderr. Это позволяет запускать gogcli в пайпах и CI без парсинга человекочитаемого вывода.
Когда использовать
| Ситуация | Подходит | Почему |
|---|---|---|
| Codex/Claude должен читать почту для контекста | Да | JSON-вывод + —sanitize-content защищает от prompt-injection |
| Codex ведёт таблицу задач в Google Sheets | Да | sheets table append дописывает строки идемпотентно |
| Codex собирает еженедельный отчёт в Docs/Slides | Да | docs format и slides create-from-markdown работают из Markdown |
| Codex должен создавать пользователей/орг-юниты в Workspace | Да, с ограничениями | Нужен admin-аккаунт и domain-wide delegation |
| Агент рассылает письма без участия человека | С осторожностью | Только через явные —allow-write, иначе —gmail-no-send блокирует отправку |
| Чисто discovery-ориентированная работа с любым новым API | Нет, лучше gws | gws динамически подхватывает новые методы из Google Discovery |
| Локальный однопользовательский скрипт без агента | Допустимо | gogcli избыточен, можно проще через curl |
| Свежесозданный gmail-аккаунт для массовой рассылки | Нет | Google блокирует такие аккаунты, риск бана |
Пример
Типичный сценарий — Codex собирает утреннюю сводку: входящие за неделю, расписание на сегодня и краткий аудит папки на диске. Все три действия — по одной команде с предсказуемым JSON:
# 1. Входящие за неделю в JSON для агента
gog --account you@example.com --readonly \
gmail search 'newer_than:7d' --max 10 --json
# 2. Прочитать конкретное письмо в безопасном виде
# (тело обёрнуто, чтобы текст из письма не стал командой)
gog gmail get <messageId> --sanitize-content --json
# 3. Расписание на сегодня
gog calendar events --today --json
# 4. Аудит папки на диске — только просмотр
gog drive audit sharing --parent <folderId> --jsonВсе четыре команды безопасны из коробки: ничего не отправляется и не удаляется, агент парсит JSON и формирует сводку. Если сводка нужна в виде документа — следом можно записать её в Docs через gog docs.
Подключение как MCP-сервер для Codex
У gogcli есть режим MCP-сервера: он отдаёт типизированные и заранее разрешённые инструменты агентным клиентам. По умолчанию MCP-сервер работает только на чтение. Write-инструменты скрыты, пока вы явно не запустите сервер с —allow-write, а —allow-tool сужает набор до конкретных инструментов или сервисов.
{
"command": "gog",
"args": [
"--account", "you@example.com",
"--enable-commands-exact", "mcp,docs.cat,sheets.get",
"mcp",
"--allow-tool", "docs_get,sheets_read_range"
]
}С такой конфигурацией агент не сможет ничего изменить в Workspace, пока вы сами не откроете запись через —allow-write. Это и есть смысл «слоёв безопасности»: права расширяются осознанно и только под конкретную задачу.
Установка и быстрый старт
Полная настройка занимает 10–15 минут. Сначала — Homebrew (на macOS) или другой способ установки со страницы загрузки gogcli.sh. Дальше — OAuth-клиент в Google Cloud Console и авторизация рабочего аккаунта.
# Шаг 1. Установка (macOS)
brew install openclaw/tap/gogcli
# Шаг 2. Сохранить OAuth-клиент (файл client_secret_....json)
gog auth credentials ~/Downloads/client_secret_....json
# Шаг 3. Авторизовать рабочий аккаунт
# Сразу сужаем доступ до нужных сервисов:
gog auth add you@yourcompany.com \
--services gmail,calendar,drive,docs,sheets,contacts
# Шаг 4. Проверить, что всё работает
gog auth doctor --check
# Шаг 5. Тестовая команда
export GOG_ACCOUNT=you@yourcompany.com
gog calendar events --todayOAuth-клиент — это «пропуск», который вы выдаёте gogcli от имени своего Google-проекта. Он определяет, к каким сервисам разрешён доступ. Один раз настроили в Cloud Console — дальше gogcli работает с этим клиентом.
Важно: client_secret.json и токены доступа — это ключи от вашей почты и диска. gogcli хранит их в системном keyring (по умолчанию) или в шифрованном файле (GOG_KEYRING_BACKEND=file), но не в открытом виде. Не коммитьте client_secret.json в репозиторий и не передавайте агенту его содержимое.
Безопасность и лимиты
gogcli бесплатен, ограничения — это квоты Google API на ваш OAuth-проект. Для личного и командного использования их обычно хватает с запасом. При массовых операциях (тысячи писем, крупные миграции) держите квоты в голове и разносите задачи по времени.
OAuth-приложение в режиме Testing ограничено: refresh-токены для user-data scopes истекают через 7 дней. Для рабочего CLI-приложения нужно Publish app в Google Auth Platform → Audience — это переводит приложение в In production (без верификации Google). Unverified app работает в production, но для sensitive scopes показывает предупреждение и имеет lifetime-cap в 100 пользователей. Для публичных приложений проходят полную верификацию Google.
Workspace-only API (Admin Directory, Cloud Identity Groups, Chat, Keep, domain-wide delegation) требуют managed-домена. Consumer gmail.com работает только для user-API: Gmail, Calendar, Drive, Docs, Sheets, Slides, Forms, Apps Script, Analytics, Search Console, Contacts/People, Tasks, Classroom.
Ограничения
Ограничения
Жёсткие границы инструмента — фиксируйте их до того, как отдадите gogcli агенту.
Зависимость от OAuth-проекта
нужен собственный OAuth-клиент в Google Cloud Console и включённые API; расходы — на стороне Google.
Квоты Google API
на массовых операциях (тысячи писем, миграции) упираетесь в дневные/минутные лимиты проекта.
Workspace-only API
Admin Directory, Cloud Identity Groups, Chat, Keep, domain-wide delegation работают только на managed-домене.
Refresh-токен в testing-режиме
OAuth-приложение в Testing теряет refresh-токен через 7 дней; для продакшна нужен Publish app.
Unverified app cap
неподтверждённое приложение ограничено 100 пользователями и показывает предупреждение для sensitive scopes.
Свежие аккаунты под нагрузкой
Google блокирует новые ящики, если на них сразу идёт ботоподобная активность — массовое чтение или рассылки.
MIT-лицензия без SLA
open-source без официальной поддержки Google; критичные операции дублируйте ручной проверкой.
Антипаттерны
Антипаттерны
Типовые ошибки, которые ломают безопасность или приводят к бану аккаунта.
Отдавать бинарь без —readonly
агент с полными правами способен разослать письма или удалить файлы — стартуйте с read-only профиля и расширяйте осознанно.
Передавать агенту client_secret.json
это ключ от вашей почты и диска — коммитить в репозиторий, класть в AGENTS.md или совать в контекст агента нельзя.
Игнорировать —sanitize-content на входящих
без обёртки текст из чужого письма может выполниться как команда — это классическая prompt-injection через почту.
Запускать MCP-сервер с —allow-write без аудита
сразу открывать запись на все инструменты — антипаттерн; сначала dry-run и read-only, потом явный —allow-tool под задачу.
Делать gogcli на свежем gmail-аккаунте
аккаунт без истории, массовое чтение или рассылки — прямой путь к бану; используйте рабочий домен с историей.
Чеклист
Чеклист
Перед тем как подключать gogcli к Codex как MCP-сервер, пройдите по этим пунктам.
OAuth-клиент создан
в Google Cloud Console есть Desktop OAuth client, client_secret.json скачан и сохранён вне репозитория.
Нужные API включены
в том же Cloud-проекте включены Gmail/Calendar/Drive/Docs/Sheets/API, под которые планируете вызовы.
Аккаунт авторизован с минимальными scope
флаг —services при gog auth add сразу ограничивает набор сервисов; не авторизуйте «всё по максимуму».
Бинарь запускается с —readonly
для Codex-сценариев стартовая конфигурация идёт с —readonly и/или —gmail-no-send.
MCP-конфиг идёт с явным —allow-tool
вместо голого mcp указан список конкретных инструментов; —allow-write появляется только под конкретную задачу.
client_secret.json не в Git
файл добавлен в .gitignore и хранится отдельно от проекта; gogcli складывает токены в системный keyring или шифрованный файл.
Тестовый прогон отработал
gog auth doctor —check проходит, gog calendar events —today возвращает ожидаемое расписание.
Ссылки
Ссылки
- Сайт: gogcli.sh — документация и quickstart
- GitHub: openclaw/gogcli — репозиторий, исходники, changelog
- Лицензия: MIT — можно использовать в коммерческих продуктах
- Альтернатива: googleworkspace/cli (gws) — Discovery-driven CLI от Google
- Google Cloud: Создание проекта и OAuth-клиента в Cloud Console
- Google API: Библиотека Google API — что включать в проекте