Gemini CLI

Windows

Причина: переменная PATH не содержит директорию %APPDATA%\npm, куда npm устанавливает глобальные пакеты.

'gemini' is not recognized as an internal or external command,
operable program or batch file.

Решение:

1. Откройте Параметры системы → Переменные среды
2. В переменной Path добавьте %APPDATA%\npm
3. Перезапустите терминал (или перезагрузите компьютер)
4. Проверьте: gemini --version

Issue #2170

macOS / Linux

Причина: директория npm bin не добавлена в PATH.

zsh: command not found: gemini

Решение:

1. Выполните: export PATH="$(npm config get prefix)/bin:$PATH"
2. Добавьте эту строку в ~/.zshrc (или ~/.bashrc) для постоянного эффекта
3. Перезапустите терминал: source ~/.zshrc

Issue #8397

macOS

Причина: Homebrew-установка Node.js не имеет прав на создание системных директорий.

EACCES: permission denied, mkdir '/Library/Application Support/GeminiCli'

Решение:

1. Создайте директорию вручную: sudo mkdir -p "/Library/Application Support/GeminiCli"
2. Передайте права текущему пользователю: sudo chown $(whoami) "/Library/Application Support/GeminiCli"
3. Повторите установку: npm install -g @google/gemini-cli

Issue #13547

Windows (Node.js v24/v25)

Причина: баг в npm v11, поставляемом с Node.js v24 и v25. Ломает проверку целостности пакетов.

npm error code ECOMPROMISED
npm error Integrity check failed

Решение:

1. Удалите текущую версию Node.js
2. Установите Node.js v22 LTS
3. Повторите: npm install -g @google/gemini-cli

Issue #14149

Все платформы

Причина: дефект в версиях 0.24.1-0.24.2 — не включён зависимый пакет.

Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@google/gemini-cli-core'

Решение:

1. Обновите до последней версии: npm install -g @google/gemini-cli@latest
2. Если не помогает, удалите и установите заново: npm uninstall -g @google/gemini-cli && npm install -g @google/gemini-cli

Issue #16897

Linux

Причина: postinstall-скрипт пытается скачать ripgrep, но не может (сеть или архитектура).

npm ERR! code 1
npm ERR! path .../node_modules/@vscode/ripgrep
npm ERR! command failed

Решение:

1. Установите ripgrep системно: sudo apt install ripgrep (Debian/Ubuntu) или sudo dnf install ripgrep (Fedora)
2. Повторите установку Gemini CLI

Issue #7862

Все платформы

Причина: Google Workspace аккаунты (корпоративные) не поддерживают бесплатный Free Tier. Нужен либо личный аккаунт, либо API-ключ.

Failed to login. Ensure your Google account is not a Workspace account
with restrictions that prevent access to Gemini.

Решение:

1. Перейдите на aistudio.google.com
2. Создайте API-ключ
3. Установите переменную: export GEMINI_API_KEY="ваш-ключ"
4. Запустите gemini — авторизация через OAuth не потребуется

Issue #1432

Все платформы

Причина: наличие переменной окружения GOOGLE_CLOUD_PROJECT переключает CLI в режим организационной авторизации через Vertex AI.

GOOGLE_CLOUD_PROJECT env var required for Vertex AI authentication

Решение:

1. Удалите переменную: unset GOOGLE_CLOUD_PROJECT
2. Проверьте, нет ли её в ~/.bashrc, ~/.zshrc или ~/.profile
3. Перезапустите терминал и попробуйте снова

Источник: документация

Корпоративные сети

Причина: корпоративный прокси подменяет SSL-сертификаты (MITM-инспекция трафика). Node.js не доверяет подменённому сертификату.

Error: self-signed certificate in certificate chain

Решение:

1. Получите корневой сертификат прокси у IT-отдела (файл .crt или .pem)
2. Укажите его для Node.js: export NODE_EXTRA_CA_CERTS="/path/to/corporate-cert.crt"
3. Добавьте в ~/.bashrc или ~/.zshrc для постоянного эффекта

Issue #2300

Корпоративные сети

Причина: аналогично предыдущей ошибке — Node.js не может проверить цепочку сертификатов через корпоративный прокси.

Error: unable to get local issuer certificate
code: 'UNABLE_TO_GET_ISSUER_CERT_LOCALLY'

Решение:

1. Рекомендуемый: export NODE_EXTRA_CA_CERTS="/path/to/cert.crt"
2. Небезопасный (временный): export NODE_TLS_REJECT_UNAUTHORIZED=0 — отключает проверку SSL полностью, используйте только для диагностики

Все платформы

Причина: бесплатный тариф ограничен 50 запросами в день (зависит от модели). Лимит сбрасывается через 24 часа.

429 RESOURCE_EXHAUSTED: You exceeded your current quota,
please check your plan and billing details.

Решение:

1. Подождите до следующего дня — лимит обнулится
2. Или подключите платный тариф в AI Studio
3. Мониторьте использование: gemini -- "check my quota"

Issue #6986

Все платформы

Причина: CLI использует API Key, привязанный к Free Tier, вместо OAuth-авторизации платной подписки.

429 RESOURCE_EXHAUSTED
(при активной платной подписке Google One AI Premium / Gemini Advanced)

Решение:

1. Перейдите в AI Studio → API Keys
2. Удалите существующий API-ключ
3. Удалите переменную: unset GEMINI_API_KEY
4. Перезапустите CLI — он предложит OAuth-авторизацию через браузер
5. Войдите аккаунтом с платной подпиской

Issue #24396

macOS 15.x (Sequoia)

Причина: macOS Sequoia ужесточила разрешения для временных директорий. CLI не может писать в стандартный temp.

EACCES: permission denied, open '/var/folders/.../gemini-cli-...'

Решение:

1. Обновите CLI до последней версии: npm install -g @google/gemini-cli@latest
2. Если проблема сохраняется, перенаправьте temp: mkdir -p ~/tmp && export TMPDIR=~/tmp
3. Добавьте export TMPDIR=~/tmp в ~/.zshrc

Issue #8690

Все платформы

Причина: песочница (sandbox) Gemini CLI блокирует операции записи за пределами текущего проекта.

Operation not permitted: write access denied by sandbox policy
Path: /home/user/other-project/file.txt

Решение:

1. Разрешите конкретную директорию: /sandbox allow /path/to/directory
2. Или запустите без песочницы: gemini --no-sandbox (менее безопасно)
3. Для постоянной настройки добавьте разрешённые пути в .gemini/settings.json

Источник: документация

CI/CD среды (GitHub Actions, GitLab CI, Jenkins)

Причина: пакет is-in-ci обнаруживает CI-среду и отключает интерактивный режим. CLI не запускается без TTY.

Error: Interactive mode is not available in CI environments.
Use --prompt flag to provide input non-interactively.

Решение:

1. Используйте неинтерактивный режим: gemini --prompt "ваш запрос"
2. Или удалите маркер CI: unset CI (перед запуском gemini)
3. Для авторизации в CI используйте API-ключ: GEMINI_API_KEY=... gemini --prompt "..."

Источник: документация

Все платформы

Причина: Gemini CLI требует Node.js v18+. Без него команды npm и npx не работают.

bash: node: command not found
bash: npm: command not found

Решение:

1. Windows: скачайте установщик с nodejs.org (версия LTS), запустите .msi, далее «Next» до конца
2. macOS: brew install node (если есть Homebrew) или скачайте .pkg с nodejs.org
3. Linux: sudo apt install nodejs npm (Ubuntu/Debian) или sudo dnf install nodejs npm (Fedora)
4. Проверьте: node --version — должно быть v18 или выше
5. Теперь установите Gemini CLI: npm install -g @google/gemini-cli

Все платформы

Причина: пользователи путают Google Cloud Console, Google AI Studio и Google One — ключ нужно создавать именно в AI Studio.

GEMINI_API_KEY environment variable not found.
Add that to your .env and try again, no reload needed!

Решение:

1. Откройте aistudio.google.com/apikey (нужен личный Google-аккаунт, НЕ корпоративный)
2. Нажмите Create API Key
3. Скопируйте ключ (начинается с AIza...)
4. Windows: в PowerShell: $env:GEMINI_API_KEY="AIza..."
5. macOS/Linux: добавьте в ~/.zshrc: export GEMINI_API_KEY="AIza..."
6. Перезапустите терминал и запустите gemini

Issue #1560

Все платформы

Причина: путаница между подписками Google AI Pro ($19.99/мес), Google AI Ultra ($249.99/мес), бесплатным Free Tier API и Gemini CLI. Подписки на Google AI Pro/Ultra дают лимиты в веб-приложении Gemini, но CLI использует API с отдельными квотами.

Как устроено:

1. Free Tier (бесплатно): OAuth-авторизация через Google-аккаунт — 60 запросов/мин для Flash, 10 для Pro. Достаточно для большинства задач
2. API Key (бесплатно): ключ из AI Studio — те же лимиты, но без привязки к подписке
3. Google AI Pro/Ultra: увеличенные лимиты в CLI при авторизации через OAuth аккаунтом с подпиской
4. Pay-as-you-go: через Google Cloud — платите за токены, без ограничений запросов

Вывод: для начала работы с Gemini CLI не нужно ничего платить. Бесплатного тарифа хватает для обучения и личных проектов.

Pricing docs

Все платформы

Причина: npx иногда молча завершается при кешировании или сетевых проблемах. Также npx https://github.com/... не работает — нужен npm-пакет, а не URL репозитория.

$ npx @google/gemini-cli
(тишина, возврат в командную строку)

Решение:

1. Установите глобально вместо npx: npm install -g @google/gemini-cli
2. Запустите: gemini
3. Если npx обязателен, очистите кеш: npx --yes @google/gemini-cli

Issue #2077

Все платформы

Причина: ключ скопирован с лишними пробелами, создан в неактивном проекте, или истёк/был удалён в AI Studio.

✕ [API Error: API key not valid. Please pass a valid API key.
(Status: INVALID_ARGUMENT)]

Решение:

1. Проверьте ключ: echo $GEMINI_API_KEY — не должно быть пробелов или кавычек внутри значения
2. Проверьте ключ через curl: curl "https://generativelanguage.googleapis.com/v1beta/models?key=$GEMINI_API_KEY"
3. Если ошибка — создайте новый ключ в AI Studio
4. Убедитесь, что Generative Language API включён в проекте (AI Studio включает автоматически)

Issue #4690

Windows / Все платформы

Причина: ранее установленная переменная GOOGLE_CLOUD_PROJECT (от Google Cloud SDK или другого проекта) переключает CLI в корпоративный режим Vertex AI.

Failed to login. Message: This account requires seting
the GOOGLE_CLOUD_PROJECT env var

Решение:

1. macOS/Linux: unset GOOGLE_CLOUD_PROJECT && unset GOOGLE_CLOUD_PROJECT_ID
2. Windows PowerShell: Remove-Item Env:GOOGLE_CLOUD_PROJECT
3. Проверьте ~/.bashrc, ~/.zshrc, .env — удалите оттуда эти переменные
4. Важно: индивидуальным пользователям эти переменные НЕ нужны — они только для организаций с Gemini Code Assist

Issue #8435

Все платформы

Причина: CLI использует неверный Google Cloud проект. Часто возникает при наличии gcloud на машине — он устанавливает дефолтный проект, который конфликтует с CLI.

API Error 403: Permission denied on resource project default.
Reason: CONSUMER_INVALID

Решение:

1. Удалите все переменные GCP: unset GOOGLE_CLOUD_PROJECT GOOGLE_CLOUD_PROJECT_ID GCLOUD_PROJECT
2. Проверьте gcloud: gcloud config list project — если проект задан, сбросьте: gcloud config unset project
3. Используйте API-ключ вместо OAuth: export GEMINI_API_KEY="ваш-ключ"
4. Перезапустите терминал

Issue #1808

macOS / Linux

Причина: файл OAuth-токена ~/.gemini/oauth_creds.json создаётся с правами 644 (читаем всеми), что является уязвимостью — любой пользователь системы может прочитать ваш токен.

$ ls -la ~/.gemini/oauth_creds.json
-rw-r--r-- 1 user user 1234 ... oauth_creds.json
(должно быть -rw-------, т.е. 600)

Решение:

1. Исправьте права вручную: chmod 600 ~/.gemini/oauth_creds.json
2. Обновите CLI до последней версии — в новых версиях права устанавливаются корректно для новых файлов
3. Проверьте: ls -la ~/.gemini/ — все файлы с токенами должны быть 600

Issue #6170

Все платформы

Причина: CLI ищет GEMINI.md от текущей директории вверх до корня Git-проекта. Если файл вне этого пути или нет .git, он не найдётся.

(инструкции из GEMINI.md не влияют на поведение модели,
 ответы не соответствуют описанным правилам)

Решение:

1. Убедитесь, что GEMINI.md в корне Git-проекта (рядом с .git/)
2. Проверьте загруженный контекст: команда /memory show в CLI
3. Принудительно перечитайте: /memory refresh
4. Для глобальных инструкций: ~/.gemini/GEMINI.md
5. Лимит поиска — 200 поддиректорий. Если проект очень большой, увеличьте context.discoveryMaxDirs в .gemini/settings.json

Issue #13652

Все платформы

Причина: модель «вспоминает» API из обучающих данных, которые изменились или не существовали. Особенно проблемно для быстро меняющихся фреймворков (Unreal Engine, React, Flutter).

// Gemini предлагает:
UGameplayStatics::GetAllActorsOfClassWithTag(...)
// Такого метода не существует в UE5

Решение:

1. Добавьте в GEMINI.md правило: «Не используй методы, в которых не уверен. Проверяй по документации»
2. Указывайте версию фреймворка в промпте: «используй UE 5.4 API»
3. Используйте @ для подключения файлов проекта как контекста — модель будет опираться на реальный код
4. Проверяйте сгенерированный код перед запуском — это общее правило для всех AI-агентов

Issue #12606

Все платформы

Причина: CLI неточно считает токены (завышает в 2-10 раз). Также возникает при работе с большими файлами или длинными сессиями.

⚠ Sending this message (1227474 tokens) might exceed
the remaining context window limit (1048348 tokens).

Решение:

1. Нажмите y для отправки — предупреждение часто ложное из-за бага подсчёта токенов
2. Если реально большой контекст — начните новую сессию: /clear или перезапустите CLI
3. Разбивайте большие файлы: вместо «прочитай весь проект» указывайте конкретные файлы через @
4. Обновите CLI — в новых версиях подсчёт токенов точнее

Issue #14333, Issue #11947

Все платформы

Причина: MCP-серверы (Model Context Protocol) могут зависать в состоянии «Connecting» из-за неверной конфигурации, несовместимости версий или сетевых проблем.

MCP ERROR: Error during discovery for MCP server "my-server"
Connection timeout after 30000ms

Решение:

1. Проверьте конфигурацию: cat .gemini/settings.json — убедитесь, что путь к серверу верный
2. Запустите MCP-сервер вручную, чтобы убедиться, что он работает
3. Проверьте совместимость: MCP-сервер должен поддерживать протокол версии, которую ожидает CLI
4. Для GitHub MCP: установите переменные GITHUB_TOKEN и проверьте GITHUB_TOOLSETS
5. Перезапустите CLI — /mcp для проверки статуса подключений

Issue #18987

Windows / Linux

Причина: вставка изображений (Ctrl+V) работает только на macOS. На других платформах мультимодальная функция ограничена или отсутствует.

(Ctrl+V не вставляет изображение, или появляется ссылка
@.gemini-clipboard/clipboard-123456.png без обработки)

Решение:

1. Сохраните изображение в файл и подключите через @путь/к/файлу.png
2. На macOS: используйте Ctrl+V для вставки из буфера обмена
3. Поддерживаемые форматы: PNG, JPEG, WebP, GIF
4. Максимальный размер: ограничен контекстным окном модели (каждое изображение ~ 258 токенов за тайл)

Issue #5316

Все платформы

Причина: при длинных сессиях модель может «забыть» недавний контекст и зацикливаться, повторяя одни и те же правки или отвечая на устаревшие сообщения.

(Gemini повторяет одну и ту же правку файла,
 или пытается применить изменение к уже изменённому коду:
 "old_string not found" — в цикле)

Решение:

1. Начните новую сессию: закройте CLI и откройте заново
2. Или очистите контекст: /clear
3. Разбивайте задачи на более мелкие — не пытайтесь сделать всё в одной сессии
4. Явно подключайте нужные файлы через @ вместо надежды, что модель «помнит» их

Issue #6474

Все платформы

Причина: CLI автоматически ретраит запрос при ошибке 429, но если квота исчерпана — уходит в бесконечный цикл повторов.

429 RESOURCE_EXHAUSTED (retrying in 5s...)
429 RESOURCE_EXHAUSTED (retrying in 10s...)
429 RESOURCE_EXHAUSTED (retrying in 20s...)
(бесконечно)

Решение:

1. Прервите CLI: Ctrl+C
2. Проверьте квоту в AI Studio
3. Подождите сброса лимита (обычно 1 минута для RPM, 24 часа для RPD)
4. Переключитесь на другую модель: /model gemini-2.5-flash — у Flash выше лимиты

Issue #6986