Правильная конфигурация 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](https://codelabs.developers.google.com/gemini-cli-hands-on) [2](https://www.philschmid.de/gemini-cli-cheatsheet) [3](https://geminicli.com/docs/get-started/authentication/) [4](https://milvus.io/ai-quick-reference/how-do-i-switch-models-in-gemini-cli) [5](https://geminicli.com/docs/get-started/configuration/) [6](https://ai.google.dev/gemini-api/docs/api-key) [7](https://github.com/google-gemini/gemini-cli/issues/1560) [8](https://developers.googleblog.com/en/5-things-to-try-with-gemini-3-pro-in-gemini-cli/) [9](https://www.linkedin.com/posts/iromin_gemini-cli-tutorial-seriespart-3-configuration-activity-7346495185725317120-Weo2) [10](https://audrey.feldroy.com/articles/2025-07-27-Gemini-CLI-Settings-With-MCP) [11](https://habr.com/en/articles/963264/) [12](https://docs.cloud.google.com/gemini/docs/codeassist/use-agentic-chat-pair-programmer) [13](https://github.com/google-gemini/gemini-cli) [14](https://github.com/google-gemini/gemini-cli/issues/5373) [15](https://developers.google.com/gemini-code-assist/docs/use-agentic-chat-pair-programmer) [16](https://www.reddit.com/r/GeminiCLI/comments/1oh61ts/whats_your_gemini_cli_setup_settingsjson_look/) [17](https://dev.to/auden/google-gemini-cli-tutorial-how-to-install-and-use-it-with-images-4phb) [18](https://addyo.substack.com/p/gemini-cli-tips-and-tricks) [19](https://www.reddit.com/r/GeminiAI/comments/1lqn6fs/anyone_know_how_i_add_my_gemini_api_key_to_gemini/) [20](https://support.google.com/gemini/thread/348900199/need-to-update-api-key-in-envirmonetal-settings?hl=en)