Gemini CLI

Gemini CLI — открытый терминальный агент от Google, который помогает понимать проекты, анализировать файлы и после разрешения использовать команды и инструменты. Настроив адрес Gemini API, ключ API и ID модели, вы можете использовать совместимую точку входа Gemini Generate Content платформы AGTCloud.

В этом руководстве рассматриваются только базовое подключение Gemini CLI и безопасная проверка. Изменение файлов, команды Shell, вызов функций и другие возможности агента зависят от целевой модели и её фактической поддержки структур Gemini Parts, Function Call и других элементов протокола.

Подготовка

Перед началом убедитесь, что вы:

• Установили Node.js версии 20 или выше;
• Подготовили терминал Bash, Zsh или PowerShell;
• Создали ключ API AGTCloud на странице API Keys;
• Скопировали из каталога моделей ID модели, доступной текущему ключу и поддерживающей Gemini Generate Content;
• Подготовили тестовый каталог без конфиденциального кода и производственных учётных данных.

MODEL_ID — заполнитель для замены, а не настоящее название модели. Используйте ID модели, доступной текущему ключу API и поддерживающей Gemini Generate Content.

Установка Gemini CLI

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

npm install -g @google/gemini-cli

После установки проверьте версию:

gemini --version

Если команда не найдена, откройте терминал заново и убедитесь, что каталог глобальных команд npm добавлен в PATH.

Настройка AGTCloud

Gemini CLI нужны четыре переменные окружения: ключ API, ID модели, пользовательский адрес Gemini API и способ аутентификации Bearer.

export GEMINI_API_KEY="your-api-key"
export GEMINI_MODEL="MODEL_ID"
export GOOGLE_GEMINI_BASE_URL="https://api.agtcloud.cn"
export GEMINI_API_KEY_AUTH_MECHANISM="bearer"

Назначение параметров

В этом руководстве GOOGLE_GENAI_API_VERSION не задаётся, поэтому Gemini CLI использует версию Gemini API по умолчанию — v1beta. Также не записывайте полный путь запроса generateContent в Base URL.

Сохранение пользовательской конфигурации

После проверки временных настроек можно записать переменные в пользовательский файл .env Gemini CLI. Он может содержать настоящий ключ API; не добавляйте его в репозиторий кода.

~/.gemini/.env

GEMINI_API_KEY=your-api-key
GEMINI_MODEL=MODEL_ID
GOOGLE_GEMINI_BASE_URL=https://api.agtcloud.cn
GEMINI_API_KEY_AUTH_MECHANISM=bearer

Gemini CLI ищет файлы окружения в текущем рабочем каталоге и родительских каталогах. Более близкий проектный .env или .gemini/.env может иметь приоритет над пользовательской конфигурацией. Если настройки не применяются, сначала проверьте эти файлы.

Фиксация аутентификации ключом API

Gemini CLI поддерживает несколько способов аутентификации Google. При использовании AGTCloud выбирайте Gemini API Key, а не вход Google или Vertex AI.

Добавьте следующую конфигурацию в пользовательский settings.json, не перезаписывая существующие настройки темы, прав и другие параметры:

{
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    }
  }
}

Расположение конфигурационного файла:

После сохранения полностью закройте Gemini CLI и запустите заново. selectedType выбирает процесс аутентификации ключом API, а GEMINI_API_KEY_AUTH_MECHANISM=bearer формирует Bearer Header по требованиям AGTCloud. Эти параметры не заменяют друг друга.

Выбор модели

Модель по умолчанию определяется GEMINI_MODEL. Чтобы временно задать модель для одного сеанса, выполните:

gemini --model MODEL_ID

Команда /model в интерактивном сеансе служит дополнительным способом выбора, но её список не обязательно содержит все модели текущего ключа API AGTCloud. Если модель отсутствует или недоступна, скопируйте полный ID из каталога моделей заново и предпочтительно задайте его через GEMINI_MODEL или --model.

Проверка подключения

gemini -p "Ответьте только: подключение к AGTCloud установлено." --output-format json

gemini -p "@README.md В трёх пунктах опишите назначение проекта. Не изменяйте никакие файлы." --output-format json

gemini

Частые вопросы

Если причину найти не удаётся, запишите время запроса, API Base URL, ID модели, версию Gemini CLI, HTTP-статус и обезличенную ошибку, затем обратитесь к разделу ошибок и диагностики. Не отправляйте полный ключ API или .env с учётными данными.

Рекомендации по безопасности

• Не записывайте настоящий ключ API в репозиторий, общие скрипты, скриншоты, журналы или переписку;
• Сначала рекомендуется проверить временные переменные, а после успеха сохранить пользовательскую конфигурацию;
• Установите подходящие права локального доступа к .env и не синхронизируйте его с общедоступным облачным хранилищем;
• При первом использовании инструментов оставьте ручное подтверждение и проверяйте их в непроизводственном проекте;
• Перед передачей диагностики удалите полный ключ, имена пользователей, локальные пути и исходный код приложения.

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

• Ключ API, Base URL и аутентификация
• Gemini Generate Content API Reference
• Gemini Stream Generate Content API Reference
• Выбор протокола
• Ошибки и диагностика