Gemini CLI が起動しない・認証が通らないときに見る場所

npm install が通らない、認証画面が開かない、インストールしたはずの gemini コマンドが見つからない。Gemini CLI でつまずくポイントの多くは、実際に使い始める前のセットアップ段階に集中しています。

インストール・認証・PATH・サンドボックス・プロキシ・レート制限という領域ごとに、実際に表示されるエラーメッセージと対処法を並べました。

インストール時のエラー

Node.js のバージョンが要件を満たしていない

Gemini CLI を使用するには、Node.js 18.0.0 以上が必要です。古いバージョンを使用している場合、インストール時に互換性エラーが発生します。

# 現在のNode.jsバージョンを確認
node --version
 
# Node.jsが古い場合はアップグレード（macOS、homebrewの場合）
brew upgrade node
 
# または最新版をインストール
brew install node

アップグレード後、npm のキャッシュをクリアしてから再度インストールしてください。

npm cache clean --force
npm install -g @google/generative-ai-cli

npm の権限エラー（Permission denied）

npm グローバルパッケージのインストール時に権限不足エラーが出る場合があります。これは npm がシステムディレクトリに書き込み権限を持たないために発生します。

推奨される解決法: npm のデフォルトディレクトリを変更します（sudo を使用しない方法）。

# npm のグローバルディレクトリを確認
npm config get prefix
 
# ユーザーディレクトリを設定（例：~/.npm-global）
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
 
# PATHに追加（~/.bashrc または ~/.zshrc）
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
 
# その後、インストール
npm install -g @google/generative-ai-cli

npm install の失敗（ネットワークエラー）

ネットワークが不安定な場合、インストール途中でエラーが発生することがあります。

# タイムアウト値を増やして再実行
npm install -g @google/generative-ai-cli --no-audit --legacy-peer-deps
 
# または npm レジストリミラーを変更（中国など一部の地域）
npm config set registry https://registry.npmmirror.com
npm install -g @google/generative-ai-cli

認証エラー

API キーが認識されない

Gemini CLI は環境変数 GEMINI_API_KEY から API キーを読み込みます。設定されていないか、形式が間違っている可能性があります。

# 現在の環境変数を確認
echo $GEMINI_API_KEY
 
# APIキーが設定されていない場合、設定を追加
export GEMINI_API_KEY='YOUR_GEMINI_API_KEY'
 
# 永続化するため ~/.bashrc または ~/.zshrc に追加
echo "export GEMINI_API_KEY='YOUR_GEMINI_API_KEY'" >> ~/.bashrc
source ~/.bashrc
 
# 正しく設定されたか確認
gemini auth test

注意: API キーは Google AI Studio（aistudio.google.com）から生成できます。また、API キーを Git にコミットしたり、公開リポジトリに含めたりしないでください。

Google アカウント認証の失敗

一部のオフラインモードでは、Google のサーバーとの通信が必要です。プロキシの背後にいる場合、認証が失敗することがあります。

# キャッシュをクリア
gemini auth clear
 
# 再度ログイン
gemini auth login
 
# プロキシ経由の場合、プロキシ設定を追加
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=https://proxy.example.com:8080
gemini auth login

コマンドが見つからない（command not found）

PATH 設定が正しくない

gemini: command not found というエラーは、インストールされたコマンドがシステムの PATH に含まれていないことを示します。

# グローバルインストール先を確認
npm config get prefix
 
# インストール先の bin ディレクトリが PATH に含まれているか確認
echo $PATH
 
# 含まれていない場合、~/.bashrc または ~/.zshrc に以下を追加
export PATH="/usr/local/bin:$PATH"
# または、npm がカスタムディレクトリに設定されている場合
export PATH="$HOME/.npm-global/bin:$PATH"
 
# 変更を反映
source ~/.bashrc

シェル設定ファイルの反映

macOS の新しいバージョンでは、デフォルトシェルが zsh に変更されました。bash の設定を追加しても反映されません。

# 現在のシェルを確認
echo $SHELL
 
# zsh を使用している場合、~/.zshrc に追加
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
 
# 新しいターミナルウィンドウを開いて確認
gemini --version

Plan Mode が使えない

Plan Mode（計画モード）を使用するには、Google AI Studio で Pro プランに登録する必要があります。Pro プラン未登録の状態で Plan Mode を使用しようとすると、エラーが発生します。

# 現在のプラン情報を確認
gemini status
 
# Pro プランの登録状況を確認
# https://aistudio.google.com/app/plan にアクセス

Pro プランの登録後、キャッシュをクリアして再度試してみてください。

gemini auth clear
gemini auth login

詳しい Plan Mode の活用方法については、「Gemini CLI Plan Mode 活用ガイド」をご覧ください。

Linux 固有のエラー（gVisor サンドボックス）

Linux 環境で実行する場合、gVisor サンドボックスに関連するエラーが出ることがあります。これは Plan Mode の実行時に特に見られます。

# gVisor の状態確認（Ubuntu/Debian）
which runsc
 
# gVisor がインストールされていない場合のエラー
# E: Cannot locate runsc
 
# gVisor をインストール（Ubuntu 20.04 以降）
curl -fsSL https://gvisor.dev/archive.key | sudo apt-key add -
sudo add-apt-repository "deb https://storage.googleapis.com/gvisor/releases release main"
sudo apt-get update
sudo apt-get install -y runsc

gVisor なしで実行したい場合は、以下の環境変数を設定してください。

export GEMINI_CLI_NO_SANDBOX=1
gemini plan

ネットワーク・プロキシ関連のエラー

接続タイムアウト（Connection timeout）

ネットワークの遅延やプロキシが原因で接続がタイムアウトすることがあります。

# タイムアウト値を増やす
export NODE_OPTIONS="--max-old-space-size=4096"
gemini --timeout 60000 plan
 
# プロキシ経由の場合
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=https://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1
gemini plan

SSL/TLS 証明書エラー

企業の SSL インターセプションプロキシを使用している場合、証明書検証エラーが発生することがあります。

# 自己署名証明書を許可（開発環境のみ）
export NODE_TLS_REJECT_UNAUTHORIZED=0
gemini plan
 
# より安全な方法：企業のCA証明書をシステムに追加
# Linux の場合
sudo cp /path/to/ca-certificate.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates
 
# macOS の場合
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain /path/to/ca-certificate.crt

レート制限エラー（429 Too Many Requests）

API キーがレート制限に達した場合、429 エラーが返されます。これは 1 分間のリクエスト数が上限に達したことを示しています。

# レート制限の詳細を確認
gemini status
 
# 対処法：リトライ間隔を設定
export GEMINI_RETRY_DELAY=5000  # 5秒待機
gemini plan

Gemini API のレート制限については、「Gemini API 429 エラー・クォータ問題トラブルシューティング」で詳しく解説しています。

バージョンアップデート時のトラブル

v0.34.0 → v0.35.0 での変更点

v0.35.0 では、設定ファイルの形式が一部変更されました。古い設定ファイルを使用していると、エラーが発生することがあります。

# インストール済みのバージョンを確認
gemini --version
 
# 最新版にアップグレード
npm install -g @google/generative-ai-cli@latest
 
# 設定ファイルをリセット
gemini config reset
 
# キャッシュをクリア
gemini cache clear

アップグレード後、設定を再度入力してください。

gemini auth login
gemini config set model gemini-2.5-pro

CLI セットアップ確認スクリプト

以下のスクリプトで、Gemini CLI のセットアップ状況を一括診断できます。

#!/bin/bash
# Gemini CLI セットアップ診断スクリプト
 
echo "=== Gemini CLI セットアップ診断 ==="
 
# Node.js バージョン確認
echo -n "Node.js: "
node --version
 
# npm バージョン確認
echo -n "npm: "
npm --version
 
# Gemini CLI インストール確認
echo -n "Gemini CLI: "
if command -v gemini &> /dev/null; then
  gemini --version
else
  echo "インストールされていません"
  exit 1
fi
 
# API キー確認
if [ -z "$GEMINI_API_KEY" ]; then
  echo "警告: GEMINI_API_KEY 環境変数が設定されていません"
else
  echo "API キー: 設定済み（最初の10文字: ${GEMINI_API_KEY:0:10}...）"
fi
 
# PATH 確認
echo -n "PATH に gemini コマンドが含まれている: "
which gemini
 
# Gemini CLI の動作確認
echo "--- 機能テスト ---"
gemini auth test && echo "認証: OK" || echo "認証: NG"

このスクリプトを実行することで、どの部分に問題があるのかを素早く特定できます。

次のステップ

基本的なセットアップが完了したら、次のガイドを参考にして、Gemini CLI をさらに活用してください。

Gemini CLI 完全ガイド — コマンド、オプション、設定方法の詳細解説
Gemini CLI Plan Mode 活用ガイド — 高度な計画機能の使い方

参考資料

何か問題が解決しない場合は、Google AI Studio のコミュニティフォーラムで質問することをお勧めします。