Как изменить каталог gemini cli?

Открытый проект Google — Gemini CLI, терминальный ИИ-агент, который приносит возможности Gemini прямо в вашу оболочку, — с момента запуска быстро повзрослел и теперь поддерживает расширенную конфигурацию, файлы контекста проекта (GEMINI.md / .gemini), пользовательские slash-команды и управление рабочими каталогами. Проект активно развивается на GitHub (официальный репозиторий), перешел в стадию публичного превью со щедрыми квотами и интегрируется в другие инструменты разработчика (интеграции с редакторами и CI/Actions). Но по мере масштабирования команд или при работе на разных дисках и в ограниченных средах (контейнеры, корпоративные ноутбуки, Cloud Shell, системы Windows) вы быстро столкнетесь с практическим вопросом: где Gemini хранит свои файлы и как изменить каталоги, из которых Gemini читает и в которые записывает?

Что такое Gemini CLI?

Gemini CLI — это консольный ИИ-агент с открытым исходным кодом от Google, который приносит мощь моделей Gemini прямо в ваш терминал. Он предоставляет интерактивные возможности агента для помощи с кодом, анализа файлов и проектов, выполнения команд оболочки (с мерами безопасности) и интеграции инструментов, таких как Google Search, расширения Model Context Protocol (MCP) и средства генерации медиа, поставляемые вместе с Gemini. CLI задуман как легковесный, сценарируемый и расширяемый; он доступен из официального репозитория и упакован для простой установки.

Почему каталог важен

Gemini CLI хранит конфигурацию (например, settings.json), системные подсказки или контекст (GEMINI.md), кэшированные учетные данные, идентификаторы телеметрии и другое постоянное состояние внутри каталога .gemini. Расположение этого каталога влияет на:

• какие настройки загружает CLI (глобальные или проектные),
• какие «файлы памяти» будет читать агент,
• где кэшируются учетные данные (влияет на поведение входа),
• воспроизводимость между машинами или в CI, когда вы хотите предоставить собственный репозиторий конфигурации.

Понимание и (при необходимости) изменение каталога помогает в многопроектных рабочих процессах, CI, контейнеризированных развертываниях и командам с централизованными хранилищами конфигурации.

Где по умолчанию хранится конфигурация Gemini CLI?

По умолчанию CLI использует каталог .gemini. Для большинства пользовательских установок он разрешается в ~/.gemini (папка .gemini в домашнем каталоге). CLI также поддерживает проектные файлы .gemini (например, .gemini/settings.json в корне проекта), которые переопределяют пользовательские настройки, когда вы работаете из этой папки проекта. Системные настройки считываются из специфичных для ОС мест (например, /etc/ в Linux или %PROGRAMDATA% в Windows), когда это применимо. Типичные пути:

• Linux / macOS: ~/.gemini/ (например, /home/alice/.gemini или /Users/alice/.gemini).
• Windows: %USERPROFILE%\.gemini (например, C:\Users\Alice\.gemini).
  Внутри .gemini обычно находятся settings.json, GEMINI.md, commands/ и локальные кэши. CLI также читает проектные папки .gemini/ (корень проекта) для настроек на уровне проекта.

Этот дефолт важен: исторически каталог конфигурации был жестко задан как .gemini в домашнем каталоге.

---

Как изменить или перенаправить каталог конфигурации Gemini CLI?

Есть несколько практичных способов — от самых простых (работать в нужной папке) до более надежных (переменные окружения или перенаправление файловой системы). Выберите подход в зависимости от того, контролируете ли вы среду выполнения (локальная машина разработчика vs. CI), на какой ОС работаете и предпочитаете ли временное или постоянное изменение.

1) Используйте проектный .gemini (рекомендуется для настроек на уровне проекта)

Если вам нужны настройки на уровне проекта, создайте подкаталог .gemini в корне вашего проекта и поместите туда settings.json, GEMINI.md и другие проектные файлы. Gemini CLI отдает предпочтение настройкам проекта, если вы запускаете его из каталога этого проекта:

your-project/├─ .gemini/│  ├─ settings.json│  └─ GEMINI.md└─ src/

Запустите gemini, находясь в your-project/, и CLI подхватит файлы .gemini из этого дерева (он поднимается вверх по дереву каталогов, чтобы найти контекст проекта). Это самый безопасный и явный способ для конфигурации на уровне проекта.

2) Используйте документированные переменные окружения (если поддерживается)

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

• GEMINI_API_KEY, GEMINI_MODEL и др. обычно используются для аутентификации и выбора модели.
• В кодовой базе и документации есть ссылки на переменные вроде GEMINI_CLI_SYSTEM_SETTINGS_PATH (используется для переопределения пути системных настроек) и константы вроде GEMINI_CONFIG_DIR (дефолтное имя .gemini, используемое в коде). Некоторые запросы сообщества и PR предлагают добавить и поддерживать переменную окружения GEMINI_CONFIG_DIR, чтобы пользователи могли перенести весь каталог конфигурации.

Пример (bash / macOS / Linux):

# Temporary for this shell sessionexport GEMINI_CONFIG_DIR="$HOME/custom_gemini_dir"​# Or override system settings path if your install supports it:export GEMINI_CLI_SYSTEM_SETTINGS_PATH="/etc/my-gemini/system.settings.json"​# Then rungemini

PowerShell (Windows):

$env:GEMINI_CONFIG_DIR = 'C:\Users\you\CustomGemini'gemini

Важное предупреждение: согласно последним обсуждениям и задачам сообщества, GEMINI_CONFIG_DIR запрашивали и упоминали в коде в некоторых местах — но были сообщены платформенно-специфичные ошибки и нестабильное поведение (особенно в Windows). Это означает, что перенаправление на основе переменных окружения может быть неравномерно надежным на всех платформах или релизах. Проверьте примечания к релизам Gemini CLI и задачи в репозитории для вашей установленной версии, если вы полагаетесь на это.

3) Добавляйте каталоги в рабочую область Gemini в рамках сеанса

Если нужно, чтобы Gemini видел дополнительные каталоги (чтобы читать файлы как контекст), используйте интерактивный набор команд /directory. Например:

/directory add path/to/another/project/directory list

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

4) Создайте симлинк или привязку файловой системы (практичное обходное решение)

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

В Unix/macOS:

# move the original config foldermv ~/.gemini ~/gemini_backup​# create a symlink to your desired locationln -s /path/to/central/gemini-config ~/.gemini

В Windows (PowerShell с правами администратора):

# Move the original directoryMove-Item -Path $env:USERPROFILE\.gemini -Destination C:\GeminiConfigBackup​# Create a junction (administrator)New-Item -ItemType Junction -Path $env:USERPROFILE\.gemini -Target C:\CentralGeminiConfig

Этот подход принуждает CLI читать из нужного вам расположения без необходимости нативной поддержки в CLI. Примечание: симлинки/точки соединения требуют соответствующих прав файловой системы и могут вести себя по-разному в контейнерах или средах Windows. Используйте с осторожностью. (См. «Заметки, специфичные для Windows» ниже.)

5) Измените эффективный домашний каталог для процесса (прием для контейнеров/CI)

При запуске в CI, контейнерах или эфемерных средах вы можете изменить переменную $HOME (Unix) или %USERPROFILE% (Windows) для процесса gemini, чтобы его дефолтный ~/.gemini разрешался в путь, которым вы управляете:

# Run gemini with a custom HOME (bash)HOME=/ci/workspace/you gemini --some-command​# Or in a container DockerfileENV HOME=/app/userRUN mkdir -p /app/user/.geminiCOPY config /app/user/.gemini

Это полезно для воспроизводимости в CI, но имейте в виду: изменение HOME может влиять на другие инструменты и потоки аутентификации (например, кэши Google OAuth), поэтому ограничьте применение этого приема изолированными контейнерами или процессными обертками.

Как установить и использовать Gemini CLI через CometAPI?

Короткий ответ: у вас есть два практичных пути — (A) вызывать модели Gemini напрямую через CometAPI (рекомендуется и проще), или (B) заставить официальный Gemini CLI работать с CometAPI, либо используя релиз Gemini-CLI, поддерживающий кастомный базовый URL (это есть в некоторых релизах/PR), либо запустив небольшой локальный прокси, который переводит запросы Gemini-CLI в вызовы в стиле CometAPI/OpenAI.

Что такое CometAPI?

CometAPI — это агрегатор/шлюз API, который предоставляет сотни сторонних моделей (включая семейство Google Gemini) через HTTP API в стиле OpenAI. Вы регистрируетесь, получаете ключ доступа типа bearer, затем вызываете конечные точки, такие как https://api.cometapi.com/v1/chat/completions. CometAPI использует стандартные bearer-токены в заголовке Authorization.

Почему использовать CometAPI? Он предлагает более низкие цены на API по сравнению с официальным API, чтобы упростить интеграцию. Руководство по установке и использованию Gemini CLI:

Как вызывать модели Gemini напрямую через CometAPI? (Рекомендуется)

Если ваша цель — просто использовать модели Gemini и вам не критичны функции Gemini CLI, прямые вызовы CometAPI просты и надежны.

export COMET_KEY="sk-xxxx"​curl -s -X POST "https://api.cometapi.com/v1/chat/completions" \  -H "Authorization: Bearer $COMET_KEY" \  -H "Content-Type: application/json" \  -d '{    "model": "gemini-2.5-pro",    "messages": [      {"role": "system", "content": "You are a helpful assistant."},      {"role": "user", "content": "Summarize the 3 key benefits of unit tests."}    ],    "max_tokens": 300  }' | jq .

Такие прямые вызовы позволяют интегрировать CometAPI в скрипты, приложения или CI без зависимости от Gemini CLI.

Можно ли заставить Gemini CLI использовать CometAPI?

Некоторые версии/PR Gemini CLI добавляют переменные окружения для переопределения базового URL Gemini API. Если ваш установленный gemini поддерживает настройку кастомного базового URL Gemini и использование ключа CometAPI, вы можете указать на CometAPI и установить ключ CometAPI как GEMINI_API_KEY (CLI ожидает переменную ключа под названием GEMINI_API_KEY для аутентификации к Gemini API).

Пример:

# example env — *check your gemini-cli docs for exact var names*export GEMINI_API_KEY="sk-xxxxx"                    # CometAPI keyexport GOOGLE_GEMINI_BASE_URL="https://api.cometapi.com/v1"  # if supportedgemini   # run the CLI; it will use the configured base URL

Устранение неполадок: распространенные проблемы и решения

Проблема: Gemini не видит файлы в другом репозитории

1. Попробуйте gemini --include-directories /path/to/repo при запуске. Или в сеансе: /directory add /path/to/repo.
2. Если репозиторий находится на сетевом ресурсе, проверьте права и что пользователь процесса CLI может читать файлы.
3. Если вы использовали симлинк для переноса .gemini, убедитесь, что CLI следует симлинку для GEMINI.md и settings.json (в некоторых версиях по соображениям безопасности определенные симлинки не обрабатываются).

Проблема: gemini не может создать ~/.gemini в Windows (EPERM)

Обычно это означает, что процессу не хватает прав на запись в %USERPROFILE%. Решения:

• Запустите терминал от имени администратора или скорректируйте права на папку.
• Установите пользовательское расположение конфигурации через симлинк или, когда поддерживается, через переменную окружения (следите за будущей поддержкой GEMINI_CONFIG_DIR).

Проблема: cd не изменяет рабочий каталог в режиме оболочки

Это признанная проблема на некоторых платформах. Рекомендация: переключитесь на выполнение команд оболочки вне процесса Gemini CLI или добавляйте каталоги через /directory add.

Проблема: имена моделей CometAPI не совпадают с ожидаемыми

Вызовите конечную точку /v1/models и изучите JSON. Идентификаторы моделей часто содержат точные строковые варианты (например, gemini-2.5-flash-preview-04-17). Используйте точную строку в запросе.

Заключение

Дефолтный дизайн Gemini CLI отдает предпочтение понятному поведению: глобальный ~/.gemini для пользовательских настроек по умолчанию и проектный .gemini для переопределений на уровне репозитория. Сообщество продвигает более гибкую нативную настраиваемость (явные переменные окружения или флаги), чтобы сделать инструмент более дружелюбным для многопользовательских, контейнеризированных и корпоративных сред.

Как изменить каталог Gemini CLI:

Обзор: Gemini CLI хранит пользовательскую конфигурацию и файлы контекста в каталоге .gemini (обычно ~/.gemini). Вы можете повлиять на то, какой каталог использует CLI, (1) полагаясь на проектный .gemini в текущем рабочем каталоге, (2) используя переменные окружения или опции CLI там, где это поддерживается, (3) добавляя каталоги рабочей области в интерактивном сеансе или (4) применяя техники на уровне файловой системы (симлинки, bind-монты или изменение переменных home/profile), когда нативные опции отсутствуют.

Для начала изучите возможности моделей Gemini (таких как Gemini 3 Pro) в Playground и обратитесь к API guide за подробными инструкциями. Прежде чем начать, убедитесь, что вы вошли в CometAPI и получили ключ API. CometAPI предлагает цену значительно ниже официальной, чтобы помочь вам с интеграцией.

Готовы начать?→ Бесплатная пробная версия моделей Gemini !