Gemini CLI configuration

概要

環境変数、コマンドライン引数、settings ファイルによる設定。このページは公式リファレンスのうち日常的に使う設定を抜き出したもので、全設定を網羅していない。 網羅的な一覧は出典を参照する。

仕様

設定レイヤーの優先順位

優先度の低い順（後のものが前を上書きする）。

1. Default values: アプリケーション内のハードコードされた既定値
2. System defaults file: 他の settings ファイルに上書きされうるシステム全体の既定
3. User settings file: 現在のユーザーのグローバル設定
4. Project settings file: プロジェクト固有の設定
5. System settings file: 他のすべての settings ファイルを上書きするシステム全体の設定
6. Environment variables: .env から読み込まれうる変数
7. Command-line arguments: 起動時に渡した値

settings ファイルの場所

• JSON 対応エディタは生成済みスキーマ（リポジトリの schemas/settings.schema.json、またはホストされたもの）を参照して補完と検証ができる
• プロジェクトの .gemini ディレクトリには settings 以外にカスタムの sandbox プロファイル（.gemini/sandbox-macos-custom.sb、.gemini/sandbox.Dockerfile）も置ける

設定内の環境変数展開

• settings.json と gemini-extension.json の文字列値は $VAR_NAME、${VAR_NAME}、${VAR_NAME:-DEFAULT_VALUE} の構文で環境変数を参照できる。設定の読み込み時に解決される
• 各 extension は自身のディレクトリに .env を持て、自動的に読み込まれる

主な設定（settings.json）

設定はカテゴリに整理され、対応するトップレベルのカテゴリオブジェクトの中に置く。

general

output / ui

• output.format: "text"（既定）または "json"
• ui.theme、ui.customThemes、ui.autoThemeSwitching（既定 true）、ui.terminalBackgroundPollingInterval（既定 60 秒）
• ui.inlineThinkingMode: "off"（既定）/ "full"
• ui.dynamicWindowTitle（既定 true）: ターミナルタイトルに状態アイコンを出す
• ui.showHomeDirectoryWarning（既定 true、要再起動）: ホームディレクトリで実行したとき警告する
• ui.escapePastedAtSymbols（既定 false）: 貼り付けテキスト内の @ をエスケープして意図しない @path 展開を防ぐ
• ui.compactToolOutput（既定 true）、ui.hideTips（既定 false）、ui.showShortcutsHint（既定 true）

tools

mcp

• mcp.serverCommand（要再起動）、mcp.allowed（許可する MCP サーバー一覧、要再起動）、mcp.excluded（除外、要再起動）

security

advanced

• advanced.autoConfigureMemory（既定 true、要再起動）: Node.js のメモリ上限を自動設定する。メモリはプロセス起動時に確保されるため、この設定はグローバルの user settings からのみ読まれ、workspace レベルの上書きを無視する
• advanced.dnsResolutionOrder（要再起動）
• advanced.excludedEnvVars（既定 ["DEBUG", "DEBUG_MODE"]）: プロジェクトのコンテキストから除外する環境変数
• advanced.ignoreLocalEnv（既定 false、要再起動）: プロジェクトディレクトリの汎用 .env を無視する
• advanced.bugCommand: bug report コマンドの設定

admin

policyPaths / adminPolicyPaths

• どちらも配列、既定 []、要再起動。追加で読み込むポリシーファイル／ディレクトリ

mcpServers

• 発見された各ツールには mcp_ 接頭辞とサーバーのエイリアスが付いて FQN（mcp_serverAlias_actualToolName）になる
• 互換性のため、システムが MCP ツール定義から一部のスキーマプロパティを削ることがある
• command、url、httpUrl のうち少なくとも 1 つが必要。複数指定した場合の優先順位は httpUrl → url → command
• サーバーのエイリアスにアンダースコア（_）を使わない。 ポリシーエンジンは FQN を mcp_ 接頭辞の直後の最初のアンダースコアで分割するため、セキュリティポリシーが黙って機能しなくなりうる
• サーバーごとのキー: command、args、env、cwd、url（SSE）、httpUrl（streamable HTTP）、headers、timeout など

シェル履歴

• 場所: ~/.gemini/tmp/<project_hash>/shell_history
• <project_hash> はプロジェクトルートのパスから生成される一意な識別子。プロジェクト間の衝突を避けるためプロジェクト固有ディレクトリに保存される

環境変数と .env

.env の読み込み順:

1. 現在の作業ディレクトリの .env
2. 見つからなければ、.git フォルダで識別されるプロジェクトルートまたはホームディレクトリに達するまで親ディレクトリを遡る
3. それでも見つからなければ ~/.env

• 一部の環境変数（DEBUG、DEBUG_MODE）は、gemini-cli の挙動への干渉を防ぐためプロジェクトの .env から自動的に除外される。.gemini/.env の変数は決して除外されない。 この挙動は advanced.excludedEnvVars で変えられる

主な環境変数:

コマンドライン引数

設定

{
  "general": {
    "defaultApprovalMode": "auto_edit",
    "checkpointing": { "enabled": true }
  },
  "tools": {
    "allowed": ["run_shell_command(git status)"],
    "useRipgrep": true
  },
  "security": {
    "folderTrust": { "enabled": true },
    "disableYoloMode": true
  }
}

{
  "apiKey": "${MY_API_TOKEN:-default-token}"
}

制約・注意点

• このページは全設定の網羅ではない。網羅的な一覧は出典の configuration リファレンスを参照する
• 「要再起動」と記した設定は、変更後に CLI の再起動が必要

関連

• facts/gemini-cli/commands.md
• facts/gemini-cli/policy-engine.md
• facts/gemini-cli/sandbox.md
• facts/gemini-cli/tools.md
• facts/gemini-cli/mcp-server.md
• facts/gemini-cli/gemini-md.md
• facts/gemini-cli/trusted-folders.md
• facts/gemini-cli/model.md
• facts/gemini-cli/headless.md
• facts/gemini-cli/extensions.md
• facts/gemini-cli/hooks.md
• facts/gemini-cli/skills.md
• facts/gemini-cli/subagents.md
• facts/gemini-cli/checkpointing.md