> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velesagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Навык: Google Workspace

> Описание навыка для работы с Gmail, календарём, диском, контактами, таблицами и документами Google через настроенный доступ OAuth 2.0.

# Навык: Google Workspace

`google-workspace` — встроенный навык Велеса для работы с сервисами Google: Gmail, календарём, диском, контактами, таблицами и документами.

Навык перенесён из Hermes Agent и адаптирован под хранилище секретов Велеса. Файл клиента Google, токен доступа и временное состояние авторизации сохраняются не открытыми файлами, а в зашифрованном локальном хранилище.

***

## Когда использовать

Навык подходит, когда Велесу нужно:

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

Для задач только с почтой можно использовать этот навык, если уже настроен доступ Google Workspace. Если нужен только Gmail и пользователь не хочет создавать проект Google Cloud, проще выбрать отдельный почтовый способ с паролем приложения, если он доступен в окружении.

***

## Что входит в навык

В каталоге `veles/skills/google-workspace/` находятся:

* `SKILL.md` — инструкция для Велеса;
* `scripts/setup.py` — пошаговая настройка доступа;
* `scripts/google_api.py` — единый командный интерфейс к сервисам Google;
* `scripts/gws_bridge.py` — мост для внешней программы `gws`;
* `scripts/google_secrets.py` — работа с зашифрованными секретами Велеса;
* `references/gmail-search-syntax.md` — справка по поисковым операторам Gmail.

Скрипт `google_api.py` сначала пытается использовать `gws`, если она установлена. Если `gws` нет, он работает через библиотеки Google для Python.

***

## Первичная настройка

Пользователю нужен проект Google Cloud, включённые интерфейсы Gmail, Calendar, Drive, Sheets, Docs и People, а также файл клиента OAuth 2.0 типа “Desktop app”.

Удобная команда для настройки:

```bash theme={null}
GSETUP="python ${VELES_HOME:-$HOME/.veles}/skills/google-workspace/scripts/setup.py"
```

Проверка текущего состояния:

```bash theme={null}
$GSETUP --check
```

Обычный порядок настройки:

```bash theme={null}
$GSETUP --client-secret /path/to/client_secret.json
$GSETUP --auth-url --services email,calendar,drive,docs --format json
$GSETUP --auth-code "PASTE_THE_REDIRECT_URL_OR_CODE" --format json
$GSETUP --check
```

После успешной настройки данные хранятся в зашифрованном файле секретов Велеса:

* `skills.google-workspace.google_client_secret_json` — файл клиента Google;
* `skills.google-workspace.google_token_json` — токен Google;
* `skills.google-workspace.google_oauth_pending_json` — временное состояние авторизации до обмена кода на токен.

Для записи и чтения этих значений нужен `VELES_SECRETS_MASTER_KEY`. Если ключ не задан, скрипт настройки остановится с ошибкой и объяснит, что нужно настроить главный ключ секретов.

***

## Использование

Удобная команда для работы:

```bash theme={null}
GAPI="python ${VELES_HOME:-$HOME/.veles}/skills/google-workspace/scripts/google_api.py"
```

Примеры чтения:

```bash theme={null}
$GAPI gmail search "is:unread" --max 10
$GAPI gmail get MESSAGE_ID
$GAPI calendar list
$GAPI drive search "quarterly report" --max 10
$GAPI contacts list --max 20
$GAPI sheets get SHEET_ID "Sheet1!A1:D10"
$GAPI docs get DOC_ID
```

Примеры действий, которые меняют данные:

```bash theme={null}
$GAPI gmail send --to user@example.com --subject "Hello" --body "Message text"
$GAPI calendar create --summary "Meeting" --start 2026-03-01T10:00:00Z --end 2026-03-01T10:30:00Z
$GAPI drive share FILE_ID --email user@example.com --role reader
$GAPI sheets append SHEET_ID "Sheet1!A:C" --values '[["new","row","data"]]'
$GAPI docs append DOC_ID --text "Additional content"
```

***

## Правила безопасности

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

* отправка писем и ответов;
* создание или удаление событий календаря;
* удаление файлов с диска Google;
* выдача доступа к файлам;
* изменение таблиц и документов.

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

***

## Частые проблемы

`NOT_AUTHENTICATED` означает, что настройка ещё не завершена или в секретах нет токена Google. Запустите `setup.py --check`, затем повторите шаги авторизации.

`REFRESH_FAILED` обычно означает, что токен отозван или устарел. Нужно заново получить ссылку авторизации и обменять новый код.

`HttpError 403: Insufficient Permission` означает, что текущему токену не хватает разрешений. Обычно помогает `setup.py --revoke` и повторная авторизация с нужным набором сервисов.

`HttpError 403: Access Not Configured` означает, что нужный интерфейс Google не включён в проекте Google Cloud.

`ModuleNotFoundError` означает, что не установлены библиотеки Google для Python. Для локальной установки можно использовать:

```bash theme={null}
$GSETUP --install-deps
```

***

## Связанные страницы

* [Навыки Велеса: простое объяснение](/skills/index_ru)
* [Навыки Велеса: подробный справочник](/skills/reference_ru)