Правильная конфигурация settings.json и переменных окружения для Gemini CLI 3.0

Структура settings.json

Gemini CLI использует иерархическую структуру настроек, которая применяется в следующем порядке приоритета (от высшего к низшему):[1][2]

• Проектные настройки: .gemini/settings.json (в корне проекта)

• Пользовательские настройки: ~/.gemini/settings.json

• Системные настройки: /etc/gemini-cli/settings.json (Linux/macOS) или %ProgramData%\gemini-cli\settings.json (Windows)

Примеры путей к файлам настроек

• Windows (пользовательские): %USERPROFILE%\.gemini\settings.json → обычно C:\Users\<ВашUsername>\.gemini\settings.json

• Windows (системные): %ProgramData%\gemini-cli\settings.json

• macOS/Linux: ~/.gemini/settings.json → /Users/<ВашUsername>/.gemini/settings.json

• Linux (системные): /etc/gemini-cli/settings.json[1]

Основные переменные окружения

Аутентификация и API

Gemini CLI поддерживает несколько методов аутентификации через переменные окружения:[3][4]

• GEMINI_API_KEY: Ключ Google AI Studio (приоритетнее GOOGLE_API_KEY)

• GOOGLE_API_KEY: Альтернативный API ключ

• GOOGLE_GENAI_USE_VERTEXAI: Установите true для использования Vertex AI вместо Google AI Studio

• GOOGLE_CLOUD_PROJECT: ID вашего Google Cloud проекта (для Vertex AI)

• GOOGLE_APPLICATION_CREDENTIALS: Путь к JSON-файлу учётных данных сервисного аккаунта[5]

Порядок приоритета переменных окружения

При использовании API ключей:

• GEMINI_API_KEY — имеет приоритет

• GOOGLE_API_KEY — используется, если GEMINI_API_KEY не установлен[6]

Примеры settings.json

Базовая конфигурация

{
"theme": "GitHub",
"vimMode": true,
"autoAccept": false,
"model": "gemini-2.5-flash",
"tools": {
"shell": {
"enableInteractiveShell": true,
"pager": "less"
}
}
}

Конфигурация с MCP-серверами

{
"theme": "Dark",
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_TOKEN"
}
},
"git": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-git"]
}
}
}

Можно использовать синтаксис $VAR_NAME или ${VAR_NAME} для ссылок на переменные окружения в settings.json.[5]

Настройка .env файлов

Глобальный .env файл

Создайте файл ~/.gemini/.env для глобальных настроек:

# ~/.gemini/.env
GEMINI_API_KEY="your_actual_api_key_here"
GITHUB_TOKEN="your_github_token"

Проектный .env файл

Для проектных настроек создайте .gemini/.env в корне проекта:

# ./.gemini/.env
GEMINI_API_KEY="project_specific_api_key"
GOOGLE_CLOUD_PROJECT="your-project-id"

CLI автоматически загружает .env файлы из этих директорий.[2]

Практические примеры конфигурации

Пример 1: Использование ключей API в settings.json

{
"apiKey": "$GEMINI_API_KEY",
"model": "gemini-2.5-flash",
"previewFeatures": true
}

Пример 2: Конфигурация для разработки

{
"general": {
"previewFeatures": true,
"logPrompts": false
},
"tools": {
"sandbox": "docker",
"autoAccept": false
}
}

Пример 3: Настройка Vertex AI

{
"model": "gemini-2.5-pro",
"auth": {
"useVertexAI": true,
"projectId": "$GOOGLE_CLOUD_PROJECT"
}
}

Установка переменных окружения в разных ОС

Linux/macOS (bash/zsh)

Добавьте в ~/.bashrc или ~/.zshrc:

export GEMINI_API_KEY="your_actual_api_key_here"
export GOOGLE_CLOUD_PROJECT="your-project-id"

После редактирования выполните:

source ~/.zshrc  # или source ~/.bashrc

Windows (PowerShell)

[Environment]::SetEnvironmentVariable("GEMINI_API_KEY", "your_api_key", "User")

Windows (Command Prompt)

setx GEMINI_API_KEY "your_api_key"

Распространённые проблемы и решения

Проблема: GEMINI_API_KEY не обнаружен

Если CLI не видит переменную окружения:[7]

• Проверьте переменную:

echo $GEMINI_API_KEY

• Создайте .env файл в домашней директории:

mkdir -p ~/.gemini
echo 'GEMINI_API_KEY="your_key"' > ~/.gemini/.env

• Для zsh на macOS добавьте в /etc/zshrc вместо ~/.zshrc[7]

Проблема: Модель по умолчанию не изменяется

Если указание модели в settings.json не работает, используйте переменную окружения:

export GEMINI_MODEL="gemini-2.5-flash"

или укажите модель при запуске:

gemini -m "gemini-2.5-pro"

Лучшие практики

Безопасность

• Никогда не коммитьте API ключи: используйте .env файлы и добавьте их в .gitignore

• Используйте переменные окружения: вместо хранения ключей напрямую в settings.json используйте синтаксис $GEMINI_API_KEY[5]

• Разделение конфигураций: используйте глобальные настройки для общих параметров и проектные для специфичных[1]

Организация

• Создавайте проектные настройки: для каждого проекта создавайте .gemini/settings.json с нужными MCP-серверами

• Используйте preview features: включайте "previewFeatures": true для доступа к новым функциям[8]

• Настройте тему: выберите тему, поддерживающую ваш терминал (GitHub, Dark, Light)

Производительность

• Включите автоматическое принятие: для безопасных операций установите "autoAccept": true

• Используйте sandbox: для изоляции выполнения команд установите "sandbox": "docker"[2]

• Настройте логирование: отключите "logPrompts": false для повышения производительности

Проверка конфигурации

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

gemini /about

Это покажет текущую версию CLI, используемую модель и метод аутентификации.[7]

Для проверки конкретных настроек используйте команду /settings внутри CLI, чтобы открыть редактор настроек.[8]

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20

---

Хотите внедрить ИИ-агентов или автоматизировать бизнес-процессы? Мы создаем интеллектуальных помощников, внедряем RAG-системы и настраиваем интеграции (n8n, Make, API). Свяжитесь с нами, чтобы обсудить ваш проект и рассчитать окупаемость.