Версия Markdown

AI-translated from English; not yet reviewed by a fluent editor.

# Подключите Claude Code к Google Workspace с помощью пяти проверок чтения

> Настройка по документации для проверки учетной записи Google Workspace CLI в Claude Code, разрешений OAuth и запросов доступа через ограниченное чтение Drive, Sheets, Docs и Gmail.

By BIG CHANGE Editorial

Published: 2026-10-20T09:34:40.461Z
Updated: 2026-10-20T09:34:40.461Z
Canonical: https://bigchange.ai/blog/claude-code-google-workspace-cli-read-checks

![Conceptual charcoal illustration of one person studying abstract command lines on a desktop monitor, with a plain folder, grid sheet, document and sealed envelope on the table.](https://bigchange.ai/api/media/file/gws-claude-read-check-workstation-hero-v1.png)
AI-generated conceptual illustration by BIG CHANGE.

Claude Code может выполнять команды Google Workspace CLI (`gws`) из локальной оболочки, используя учетную запись Google, прошедшую аутентификацию в `gws`. Уполномоченный владелец учетной записи может проверить подключение на одной безопасной записи в каждом сервисе: Drive, Sheets, Docs и Gmail. Сначала подтвердите учетную запись и разрешения. Руководство следует документированному интерфейсу репозитория CLI, изученному 20 октября 2026 года. BIG CHANGE не устанавливал эти инструменты и не обращался к учетной записи.

## Главное изменение

- **Что изменилось:** Современный `gws` CLI предоставляет методы Google Workspace API в виде команд оболочки, которые может запускать Claude Code. Одна аутентифицированная учетная запись открывает путь к нескольким рабочим сервисам в пределах фактически выданных разрешений и прав агента на работу с оболочкой.
- **Почему это важно:** То же подключение, которое позволяет агенту просматривать выбранный файл или сообщение, может давать доступ к другим данным в пределах его областей OAuth. Владелец учетной записи может сравнить небольшие известные результаты в терминале и Claude Code, прежде чем поручать больше работы.
- **На что обратить внимание:** Проверяйте сгенерированные команды установленного CLI и действующие правила доступа сеанса при каждом изменении настройки. CLI еще не достиг версии 1.0; узкий пример запроса или маска полей не сужает разрешение на уровне всей учетной записи.

## Перед подключением

Используйте отдельную одобренную тестовую учетную запись Google без конфиденциальных данных и проект Cloud, где вы вправе настраивать OAuth. Спросите администратора, разрешены ли четыре API и запрашиваемые права. Подготовьте существующий файл Drive с уникальным именем, таблицу с известными значениями в небольшом диапазоне, короткий текстовый Google Doc с одной вкладкой и безопасное сообщение Gmail. Для Gmail получите его RFC-идентификатор `Message-ID` через **Show original**. Вы сравните эти оригиналы с результатами CLI. Проверки ничего не создают и не отправляют.

Установите Claude Code на контролируемый компьютер. Установите `gws` из [выпуска репозитория для вашей ОС](https://github.com/googleworkspace/cli/releases) либо, если есть Node.js 18 или новее, используйте документированную команду:

```bash
npm install -g @googleworkspace/cli
gws --version
gws --help
gws auth login --help
```

Непублично запишите установленные версии CLI и Claude Code. CLI еще до версии 1.0, а команды строятся по документам обнаружения API Google. Прежде чем запускать примеры, проверьте установленную справку и схемы методов ниже.

## 1. Настройте вход OAuth с ограниченными правами

В одобренном проекте Cloud включите API Drive, Sheets, Docs и Gmail. Настройте аудиторию OAuth и создайте клиент типа **Desktop app**. Если приложение имеет тип External и находится на тестировании, добавьте выбранную учетную запись как тестового пользователя. Сохраните загруженный JSON клиента в документированном месте `~/.config/gws/client_secret.json` либо используйте отдельный каталог, выбранный через `GOOGLE_WORKSPACE_CLI_CONFIG_DIR`. Держите каталог вне проекта Claude и предоставьте доступ только владельцу учетной записи.

Перед входом непублично проверьте, задана ли `GOOGLE_WORKSPACE_CLI_TOKEN` или `GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE`, в том числе через файл `.env`. Эти источники имеют приоритет над сохраненными учетными данными OAuth. Не выводите их значения и не просите Claude Code читать файлы учетных данных. Используйте чистое окружение и нужную конфигурацию клиента.

Явно запросите эти четыре области доступа:

```bash
gws auth login --scopes 'https://www.googleapis.com/auth/drive.metadata.readonly,https://www.googleapis.com/auth/spreadsheets.readonly,https://www.googleapis.com/auth/documents.readonly,https://www.googleapis.com/auth/gmail.readonly'
gws auth status
```

Выберите учетную запись и дайте согласие самостоятельно. Зафиксированная версия исходного кода CLI также добавляет области идентификации `openid`, `userinfo.email` и `userinfo.profile`. Непублично сравните согласие и сведения из `gws auth status` об учетной записи, правах и действительности токена с вашими намерениями; отсутствующее поле статуса остается непроверенным. Остановитесь, если учетная запись неверна или осталось неожиданно широкое разрешение. Выбор сервисов при входе лишь фильтрует варианты, а не задает эти четыре области только для чтения.

Области доступа шире примеров запросов. Доступ к метаданным Drive охватывает метаданные доступных файлов; чтение Sheets и Docs охватывает доступные таблицы и документы; Gmail только для чтения может обращаться к содержимому почтового ящика. Имена, ID, диапазоны, запросы и маски полей ограничивают отдельный ответ, а не полномочия токена. Инструмент оболочки может обращаться и к локальным учетным данным, поэтому скрытый путь или инструкция в запросе не изолируют их.

## 2. Выполните ограниченные чтения напрямую

Сначала изучите каждый метод через `gws schema drive.files.list` и соответствующие имена схем для остальных методов. Проверьте сгенерированную справку `--help`, если параметр отличается в установленной версии. Ниже используется синтаксис одинарных кавычек Bash; осознанно адаптируйте кавычки для другой оболочки. Заменяйте только тестовые идентификаторы и имя. Выполняйте по одной команде и непублично сохраняйте ее фактический ответ или ошибку без токенов и конфиденциального содержимого.

Найдите файл Drive по имени. JSON-последовательность `\u0027` экранирует апострофы в поисковом выражении Drive, сохраняя кавычки Bash:

```bash
gws drive files list --params '{"pageSize":5,"q":"trashed = false and name = \u0027GWS connection check\u0027","fields":"files(id,name,mimeType),nextPageToken,incompleteSearch"}'
```

Сопоставьте ID и имя с файлом в Drive. Отсутствие совпадения или `incompleteSearch` не доказывает доступ к нужному файлу.

Прочитайте известные ячейки, используя фактический ID таблицы и имя листа:

```bash
gws sheets spreadsheets values get --params '{"spreadsheetId":"SPREADSHEET_ID","range":"Sheet1!A1:C3","fields":"range,majorDimension,values"}'
```

Сравните возвращенные значения с таблицей. Google может пропускать пустые ячейки в конце, поэтому подготовьте известные непустые значения.

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

```bash
gws docs documents get --params '{"documentId":"DOCUMENT_ID","includeTabsContent":false,"fields":"documentId,title,body(content(paragraph(elements(textRun(content)))))"}'
```

Сопоставьте ID, заголовок и известный текст. Этот ограниченный ответ не проверяет другие вкладки, комментарии или всю структуру документа.

Для Gmail найдите существующее сообщение по RFC-идентификатору `Message-ID`, затем используйте возвращенный Gmail ID, чтобы запросить два заголовка:

```bash
gws gmail users messages list --params '{"userId":"me","maxResults":1,"q":"rfc822msgid:MESSAGE_ID_FROM_SHOW_ORIGINAL","fields":"messages(id,threadId),nextPageToken,resultSizeEstimate"}'
gws gmail users messages get --params '{"userId":"me","id":"GMAIL_MESSAGE_ID","format":"metadata","metadataHeaders":["Message-ID","Subject"],"fields":"id,threadId,payload(headers)"}'
```

Сравните возвращенный `Message-ID` и безопасную тему с оригиналом. Первый вызов возвращает ID сообщений, а не заголовки. Второй запрашивает метаданные заголовков, а не тело сообщения. Пустой первый ответ не позволяет выполнить вторую проверку. Более узкая область OAuth для метаданных Gmail не разрешает поисковый запрос, использованный здесь; явное разрешение Gmail только для чтения разрешает.

## 3. Повторите через Claude Code с запросами разрешения

Запустите Claude Code в контролируемом проекте с той же одобренной конфигурацией учетной записи. В `/permissions` изучите действующий режим и правила оболочки. Используйте Manual (также называется `default`) и правило **Ask** для фактического инструмента оболочки; устраните более широкие правила разрешения или обхода согласно политике организации. Избегайте общего разрешения для `gws *` или обертки оболочки. При каждой предложенной команде изучайте ее целиком и одобряйте только нужное ограниченное чтение.

Обычными словами попросите Claude Code предложить пять команд выше для тех же тестовых объектов и выполнять их по одной только после вашего решения о разрешении. Попросите сообщать вывод или ошибки, не читая учетные данные, не расширяя запросы и не выполняя запись. Затем сравните каждый результат и с прямым результатом, и с исходным объектом. Инструкции проекта могут описывать задачу, но доступ определяют действующие права инструментов и разрешения OAuth.

| Сервис | Подтверждение выполнения обоими способами |
| --- | --- |
| Drive | Тот же ID и имя файла; поиск завершен. |
| Sheets | Ожидаемый лист, диапазон и известные значения ячеек. |
| Docs | Ожидаемый ID, заголовок и текст первой вкладки. |
| Gmail | Список находит тестовое сообщение; получение метаданных подтверждает его `Message-ID` и тему. |

В частном проверочном листе запишите версии, аутентифицированную учетную запись, фактические права, целевые ID, прямой результат, результат Claude и ошибки. Неудачный запрос, успешный пустой ответ и проверенный объект — разные исходы. Завершайте только после проверки всех четырех сервисов обоими способами.

## Если проверка не удалась

Ошибка **Access blocked** при входе может означать, что тестовая учетная запись отсутствует в списке тестовых пользователей приложения OAuth. При ошибке API или области доступа подтвердите включенный API, выбранную учетную запись и фактические права, прежде чем запрашивать одобренное повторное согласие. Если список пуст, проверьте точный объект, запрос и учетную запись. Если установленная справка отличается от примеров, сначала используйте актуальную схему метода. Если Claude Code предлагает изменяющую или более широкую команду, отклоните ее в запросе разрешения и вернитесь к ограниченному чтению.

Репозиторий CLI доступен без платного пакета. Учетная запись или тариф Workspace, квоты Cloud и тариф Claude Code либо использование API могут повлечь расходы. Полученное содержимое может обрабатывать провайдер, настроенный в Claude Code, поэтому используйте только одобренные несекретные тестовые данные. CLI указывает, что не является официально поддерживаемым продуктом Google, и предупреждает об изменениях до версии 1.0. BIG CHANGE не проверял производительность или совместимость. Остановитесь перед любой записью, отправкой или изменением учетной записи. [Отдельное дополнение Claude для Google Workspace](https://bigchange.ai/blog/claude-google-workspace-add-on-edit-open-files) описывает редактирование открытых файлов с одобрением другим способом.

## Sources

- [README Google Workspace CLI](https://github.com/googleworkspace/cli/blob/a3768d0e82ad83cca2da97724e46bea4ff0e6dbd/README.md) — Официальный репозиторий на зафиксированной ревизии, изученный 20 октября 2026 года. Подтверждает установку, ручную настройку OAuth, динамические команды, приоритет учетных данных, нестабильность версий и предупреждение об отсутствии официальной поддержки продукта. Не подтверждает результат выполнения BIG CHANGE.
- [Контекст команд Google Workspace CLI](https://github.com/googleworkspace/cli/blob/a3768d0e82ad83cca2da97724e46bea4ff0e6dbd/CONTEXT.md) — Официальные инструкции на зафиксированной ревизии по вложенным методам, --params, проверке схем и ограниченному выбору полей; нужно проверить фактически установленную справку.
- [Реализация аутентификации Google Workspace CLI](https://github.com/googleworkspace/cli/blob/a3768d0e82ad83cca2da97724e46bea4ff0e6dbd/crates/google-workspace-cli/src/auth_commands.rs) — Зафиксированный код аутентификации подтверждает пользовательские --scopes, отдельное поведение выбора сервисов и добавляемые области идентификации. Изучение кода не показывает фактические права читателя.
- [Руководство по включению Google Workspace API](https://developers.google.com/workspace/guides/enable-apis) — Инструкции Google по включению API в проекте Cloud; доступ по-прежнему определяется правилами проекта и администратора.
- [Справочник Drive files.list](https://developers.google.com/workspace/drive/api/reference/rest/v3/files/list) — Подтверждает Drive q, pageSize и поля ответа для ограничения поиска метаданных. Узкий запрос не сужает полномочия OAuth.
- [Справочник Sheets spreadsheets.values.get](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets.values/get) — Подтверждает чтение по ID таблицы и диапазону A1, а также формат ответа; пустые ячейки в конце могут отсутствовать.
- [Справочник Docs documents.get](https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/get) — Подтверждает получение документа и ограничение первой вкладкой при includeTabsContent=false. Пример предназначен для простого текстового тестового документа с одной вкладкой.
- [Справочники Gmail messages.list и messages.get](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/list) — Справочник list описывает поиск по ID сообщения и результаты только с ID; q недоступен с gmail.metadata. Парный справочник get — https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/get, он описывает metadataHeaders с форматом METADATA.
- [Разрешения Claude Code](https://code.claude.com/docs/en/permissions) — Текущий справочник Anthropic по режиму Manual/default, правилам Ask, действующим правам инструментов и запросам разрешения оболочки. Не доказывает, что в конкретном сеансе читателя есть конкретное правило.