Gemini CLI全局配置：环境变量和设置文件的完整指南

【免费下载链接】gemini-cli An open-source AI agent that brings the power of Gemini directly into your terminal. 项目地址: https://gitcode.com/gh_mirrors/gemi/gemini-cli

在使用Gemini CLI（命令行界面）时，全局配置是提升工作效率和定制化体验的关键。本文将深入探讨Gemini CLI的环境变量和设置文件配置方法，帮助用户从入门到精通，全面掌握配置技巧，解决实际使用中的痛点问题。读完本文，你将能够：掌握环境变量的设置与优先级、理解配置文件的结构与内容、学会自定义主题和工具行为、解决常见的配置冲突问题。

配置优先级与层级结构

Gemini CLI的配置体系采用层级结构，不同来源的配置按特定优先级生效。了解这一结构有助于你更好地管理和调试配置。

配置优先级顺序

配置从低到高的优先级如下：

1. 默认值：应用程序内置的硬编码默认值。
2. 系统默认文件：系统级别的默认设置，可被其他设置文件覆盖。
3. 用户设置文件：当前用户的全局设置。
4. 项目设置文件：特定项目的设置，仅在该项目中生效。
5. 系统设置文件：系统级别的覆盖设置，优先级高于用户和项目设置。
6. 环境变量：系统或会话级别的环境变量，可能从.env文件加载。
7. 命令行参数：启动CLI时传递的参数，优先级最高。

配置文件位置

Gemini CLI使用JSON格式的设置文件进行持久化配置，主要有以下几个位置：

• 系统默认文件

  • Linux: /etc/gemini-cli/system-defaults.json
  • Windows: C:\ProgramData\gemini-cli\system-defaults.json
  • macOS: /Library/Application Support/GeminiCli/system-defaults.json
  • 可通过GEMINI_CLI_SYSTEM_DEFAULTS_PATH环境变量覆盖路径。

• 用户设置文件

  • 位置：~/.gemini/settings.json（~表示用户主目录）
  • 作用：应用于当前用户的所有Gemini CLI会话。

• 项目设置文件

  • 位置：项目根目录下的.gemini/settings.json
  • 作用：仅在运行Gemini CLI的特定项目中生效。

• 系统设置文件

  • Linux: /etc/gemini-cli/settings.json
  • Windows: C:\ProgramData\gemini-cli\settings.json
  • macOS: /Library/Application Support/GeminiCli/settings.json
  • 可通过GEMINI_CLI_SYSTEM_SETTINGS_PATH环境变量覆盖路径。

官方文档：docs/cli/configuration.md

环境变量配置详解

环境变量是配置应用程序的常用方式，尤其适用于敏感信息（如API密钥）或环境特定的设置。Gemini CLI会自动从.env文件加载环境变量。

环境变量加载顺序

1. 当前工作目录下的.env文件。
2. 如果未找到，向上搜索父目录，直到找到.env文件或到达项目根目录（通过.git文件夹识别）或用户主目录。
3. 如果仍未找到，查找用户主目录下的~/.env文件。

常用环境变量

以下是Gemini CLI中常用的环境变量及其说明：

环境变量	描述	示例
GEMINI_API_KEY	Gemini API的密钥，用于身份验证	export GEMINI_API_KEY="your_api_key"
GEMINI_MODEL	指定默认使用的Gemini模型	export GEMINI_MODEL="gemini-2.5-flash"
GOOGLE_API_KEY	Google Cloud API密钥，用于Vertex AI的快速模式	export GOOGLE_API_KEY="your_google_api_key"
GOOGLE_CLOUD_PROJECT	Google Cloud项目ID，用于Code Assist或Vertex AI	export GOOGLE_CLOUD_PROJECT="your_project_id"
GOOGLE_APPLICATION_CREDENTIALS	Google应用凭据JSON文件的路径	export GOOGLE_APPLICATION_CREDENTIALS="/path/to/credentials.json"
GEMINI_SANDBOX	控制沙箱模式，可选值：true、false、docker、podman或自定义命令字符串	export GEMINI_SANDBOX="docker"
DEBUG 或 DEBUG_MODE	启用详细的调试日志，有助于故障排除	export DEBUG="true"
NO_COLOR	禁用CLI中的彩色输出	export NO_COLOR=1

注意：DEBUG和DEBUG_MODE变量默认会从项目.env文件中排除，以避免干扰Gemini CLI的行为。如果需要为Gemini CLI设置这些变量，请使用.gemini/.env文件。

.env文件示例

# .env文件示例
GEMINI_API_KEY=your_gemini_api_key_here
GEMINI_MODEL=gemini-2.5-flash
GOOGLE_CLOUD_PROJECT=my-gcp-project
GEMINI_SANDBOX=docker

设置文件详解

设置文件（settings.json）是Gemini CLI的核心配置方式，支持丰富的定制选项。自v0.3.0起，设置文件采用新的嵌套结构，更加组织化。

设置文件结构

设置文件使用JSON格式，按功能分为多个顶级类别。以下是主要的类别及其用途：

• general: 通用设置，如编辑器偏好、Vim模式、自动更新等。
• ui: 用户界面设置，如主题、界面元素显示/隐藏等。
• model: 模型相关设置，如模型名称、会话轮次限制等。
• context: 上下文相关设置，如上下文文件名、文件过滤选项等。
• tools: 工具相关设置，如沙箱配置、工具允许列表等。
• mcp: MCP（Model-Context Protocol）服务器相关设置。
• mcpServers: MCP服务器的详细配置。
• security: 安全相关设置，如文件夹信任等。
• telemetry: 遥测和日志配置。
• advanced: 高级设置，如环境变量排除列表等。

关键设置详解

通用设置（general）

{
  "general": {
    "preferredEditor": "code",  // 首选编辑器，如"vscode"、"vim"等
    "vimMode": true,            // 启用Vim模式进行输入编辑
    "disableAutoUpdate": false, // 禁用自动更新
    "disableUpdateNag": false,  // 禁用更新通知提示
    "checkpointing": {
      "enabled": true           // 启用会话检查点，用于恢复
    }
  }
}

用户界面设置（ui）

{
  "ui": {
    "theme": "GitHub",          // 界面主题，如"Default"、"Dracula"、"GitHub Light"等
    "hideBanner": true,         // 隐藏启动横幅（ASCII艺术标志）
    "hideTips": false,          // 隐藏界面中的提示信息
    "showMemoryUsage": true,    // 在界面中显示内存使用信息
    "showLineNumbers": true,    // 在聊天中显示行号
    "accessibility": {
      "disableLoadingPhrases": false  // 为辅助功能禁用加载短语
    }
  }
}

Gemini CLI提供了多种内置主题，包括深色和浅色主题。你可以通过/theme命令在CLI中交互式地选择主题，或在设置文件中直接指定主题名称。

工具设置（tools）

{
  "tools": {
    "sandbox": "docker",        // 启用Docker沙箱
    "allowed": ["run_shell_command(git)", "run_shell_command(npm test)"],  // 无需确认即可运行的工具列表
    "exclude": ["write_file"],  // 排除的工具名称列表
    "core": ["ReadFileTool", "GlobTool", "ShellTool(ls)"]  // 限制可用的核心工具
  }
}

• sandbox: 控制工具执行的沙箱环境。设置为true时使用预构建的gemini-cli-sandbox Docker镜像。
• allowed: 绕过确认对话框的工具列表，例如允许git和npm test命令无需确认即可执行。
• core: 用于限制内置工具的集合，实现工具的允许列表。

模型设置（model）

{
  "model": {
    "name": "gemini-1.5-pro-latest",  // 使用的Gemini模型名称
    "maxSessionTurns": 20,            // 会话的最大轮次，-1表示无限制
    "summarizeToolOutput": {          // 启用工具输出的摘要
      "run_shell_command": {
        "tokenBudget": 2000           // 摘要的令牌预算
      }
    }
  }
}

MCP服务器设置（mcpServers）

MCP（Model-Context Protocol）服务器用于发现和使用自定义工具。可以在设置文件中配置多个MCP服务器。

{
  "mcpServers": {
    "mainServer": {
      "command": "bin/mcp_server.py",  // 启动MCP服务器的命令
      "args": ["--port", "8080"],      // 传递给命令的参数
      "cwd": "./mcp_servers/main",     // 命令的工作目录
      "timeout": 5000                  // 服务器请求的超时时间（毫秒）
    },
    "sseServer": {
      "url": "http://localhost:8081/events",  // 使用SSE（Server-Sent Events）的MCP服务器URL
      "headers": {
        "Authorization": "Bearer $MY_SSE_TOKEN"  // 请求头，可包含环境变量
      }
    }
  }
}

完整设置文件示例

以下是一个包含多个配置类别的settings.json示例：

{
  "general": {
    "vimMode": true,
    "preferredEditor": "code",
    "checkpointing": {
      "enabled": true
    }
  },
  "ui": {
    "theme": "GitHub",
    "hideBanner": true,
    "showMemoryUsage": true
  },
  "model": {
    "name": "gemini-1.5-pro-latest",
    "maxSessionTurns": 15,
    "summarizeToolOutput": {
      "run_shell_command": {
        "tokenBudget": 1500
      }
    }
  },
  "context": {
    "fileName": ["GEMINI.md", "CONTEXT.md"],
    "includeDirectories": ["./docs", "~/common-context"],
    "fileFiltering": {
      "respectGitIgnore": true,
      "respectGeminiIgnore": true
    }
  },
  "tools": {
    "sandbox": "docker",
    "allowed": ["run_shell_command(git status)", "run_shell_command(npm test)"],
    "core": ["ReadFileTool", "GlobTool", "ShellTool(ls)", "ShellTool(cat)"]
  },
  "mcpServers": {
    "corpTools": {
      "command": "/opt/corp-mcp-server/start.sh",
      "timeout": 5000
    }
  },
  "telemetry": {
    "enabled": true,
    "target": "local",
    "outfile": "~/.gemini/telemetry.log"
  },
  "advanced": {
    "excludedEnvVars": ["DEBUG", "DEBUG_MODE", "NODE_ENV"]
  }
}

命令行参数配置

命令行参数是临时覆盖配置的便捷方式，优先级高于其他配置来源。以下是常用的命令行参数：

参数	别名	描述	示例
--model <model_name>	-m	指定本次会话使用的Gemini模型	gemini --model gemini-1.5-pro-latest
--prompt <prompt>	-p	非交互式模式下的提示文本	gemini --prompt "Explain quantum computing"
--prompt-interactive <prompt>	-i	以交互模式启动并提供初始提示	gemini -i "Analyze this code"
--sandbox	-s	启用沙箱模式	gemini --sandbox
--debug	-d	启用调试模式，显示详细日志	gemini --debug
--output-format <format>	-o	指定输出格式，可选text或json	gemini --output-format json
--yolo		自动批准所有工具调用	gemini --yolo
--approval-mode <mode>		设置工具调用的批准模式，可选default、auto_edit、yolo	gemini --approval-mode auto_edit
--allowed-tools <tool1,tool2>		绕过确认对话框的工具列表	gemini --allowed-tools "run_shell_command(git),read_file"
--help	-h	显示帮助信息	gemini --help

命令行参数示例

1. 非交互式模式运行，输出JSON格式结果：

   gemini --prompt "List files in current directory" --output-format json
   

2. 启用沙箱模式并使用特定模型：

   gemini --sandbox --model gemini-2.5-flash -i "Run 'ls -la' in sandbox"
   

3. 自动批准编辑工具，提示其他工具：

   gemini --approval-mode auto_edit "Refactor the UserService class"
   

配置管理最佳实践

1. 分层管理配置

• 系统级配置：由管理员设置，定义组织范围内的策略和默认值。
• 用户级配置：个人偏好设置，如编辑器选择、主题等。
• 项目级配置：特定项目的设置，如MCP服务器、上下文文件等。
• 环境变量：敏感信息或环境特定设置，不提交到版本控制。
• 命令行参数：临时覆盖，用于单次会话的特殊需求。

2. 敏感信息处理

• 避免在设置文件中硬编码敏感信息（如API密钥），应使用环境变量或.env文件。
• .env文件应添加到.gitignore中，防止泄露。
• 使用GOOGLE_APPLICATION_CREDENTIALS环境变量指定凭据文件路径，而非直接嵌入凭据。

3. 配置冲突解决

当不同来源的配置发生冲突时，记住以下原则：

• 高优先级的配置覆盖低优先级的配置。
• 数组类型的配置（如includeDirectories）会合并，而非覆盖。
• 对象类型的配置（如mcpServers）会合并，同名键会被高优先级配置覆盖。

4. 版本控制与共享配置

• 用户级和项目级的settings.json可以提交到版本控制，便于团队共享一致的配置。
• 敏感信息或环境特定的配置应通过环境变量或.env文件处理，不纳入版本控制。

常见配置问题与解决方案

问题1：设置文件修改后不生效

可能原因：

• 配置文件路径不正确。
• 配置文件格式错误（如JSON语法错误）。
• 存在更高优先级的配置（如环境变量或命令行参数）覆盖了设置。

解决方案：

• 验证配置文件路径是否正确（如~/.gemini/settings.json或项目.gemini/settings.json）。
• 使用jsonlint等工具检查JSON语法。
• 运行gemini --debug查看实际加载的配置值，确定是否被覆盖。

问题2：主题设置不生效

可能原因：

• settings.json中定义了theme设置，导致无法通过/theme命令更改。
• 主题名称拼写错误或不存在。

解决方案：

• 从settings.json中移除"ui": { "theme": ... }设置，然后使用/theme命令选择主题。
• 检查主题名称是否正确，可通过/theme命令查看可用主题列表。

问题3：工具调用被拒绝或未执行

可能原因：

• 工具不在允许列表中，且未启用自动批准。
• 沙箱模式限制了某些操作。
• 配置了tools.core或tools.exclude限制了工具访问。

解决方案：

• 使用--yolo或--approval-mode yolo临时允许所有工具调用。
• 检查settings.json中的tools.allowed、tools.core和tools.exclude配置。
• 运行gemini /tools desc查看当前可用的工具列表。

问题4：环境变量未被加载

可能原因：

• .env文件位置不正确。
• 环境变量名称拼写错误。
• 变量被advanced.excludedEnvVars排除。

解决方案：

• 确保.env文件位于当前工作目录、项目根目录或用户主目录。
• 检查变量名称拼写是否正确。
• 查看settings.json中的advanced.excludedEnvVars，确保变量未被排除。

总结

Gemini CLI的配置系统提供了灵活而强大的方式来定制和控制其行为。通过环境变量、设置文件和命令行参数的组合，用户可以根据个人偏好和项目需求进行精细调整。本文详细介绍了配置的层级结构、常用配置选项、最佳实践和常见问题解决方案，帮助用户从入门到精通，充分发挥Gemini CLI的潜力。

无论是个人开发者定制工作流，还是企业管理员实施安全策略，掌握Gemini CLI的配置技巧都是提升效率和保障安全的关键。建议定期查阅官方文档，了解新的配置选项和最佳实践。

官方文档：docs/cli/configuration.md

【免费下载链接】gemini-cli An open-source AI agent that brings the power of Gemini directly into your terminal. 项目地址: https://gitcode.com/gh_mirrors/gemi/gemini-cli