Gemini CLI 的配置体系分为七层，从硬编码默认值到命令行参数依次覆盖。核心配置通过 settings.json 文件管理（4个文件位置），支持通过环境变量（30+个）和命令行参数按会话覆盖。本文是所有配置项的完整中文参考，包括所有分类字段定义、默认值和生效范围。

Gemini CLI 配置完整参考 #

配置优先级（从低到高） #

配置文件路径 #

可通过 GEMINI_CLI_SYSTEM_SETTINGS_PATH 环境变量覆盖系统覆盖文件路径。

settings.json 中的环境变量引用：字符串值可使用 $VAR_NAME、${VAR_NAME} 或 ${VAR_NAME:-DEFAULT} 语法引用环境变量，会在加载时自动解析。

settings.json 配置项详解 #

用 /settings 命令直接在 CLI 内打开设置界面，也可手动编辑文件。

policyPaths / adminPolicyPaths #

general — 通用设置 #

output — 输出格式 #

ui — 界面显示 #

ide — IDE 集成 #

privacy — 隐私 #

billing — 计费 #

model — 模型设置 #

agents — 代理配置 #

context — 上下文与文件过滤 #

tools — 工具控制 #

mcp — MCP 服务器管控 #

security — 安全设置 #

admin — 管理员专用设置 #

这些设置通常放在系统级 settings.json 中由管理员配置：

advanced — 高级设置 #

experimental — 实验性功能 #

skills — Skills 功能 #

hooksConfig — Hooks 系统控制 #

hooks — Hook 事件绑定 #

每个字段都是一个命令数组（Hook 处理器列表）：

mcpServers — MCP 服务器配置 #

每个服务器用名称作为 key，值为服务器参数对象。服务器名不能包含下划线（使用连字符，如 my-server）：

{
  "mcpServers": {
    "my-server": {
      "command": "bin/mcp_server.py",
      "args": ["--verbose"],
      "env": { "API_KEY": "$MY_API_KEY" },
      "timeout": 5000,
      "trust": false,
      "includeTools": ["tool-a", "tool-b"],
      "excludeTools": ["dangerous-tool"]
    },
    "remote-server": {
      "httpUrl": "https://mcp-server.example.com",
      "headers": { "Authorization": "Bearer $TOKEN" }
    }
  }
}

telemetry — 遥测配置 #

完整示例 settings.json #

{
  "general": {
    "vimMode": true,
    "preferredEditor": "code",
    "sessionRetention": {
      "enabled": true,
      "maxAge": "30d"
    }
  },
  "ui": {
    "theme": "GitHub",
    "hideBanner": true,
    "loadingPhrases": "witty"
  },
  "model": {
    "name": "gemini-2.5-pro",
    "maxSessionTurns": 50
  },
  "tools": {
    "sandbox": "docker",
    "allowed": ["run_shell_command(git)"],
    "exclude": []
  },
  "mcpServers": {
    "my-jira": {
      "command": "node",
      "args": ["jira-mcp.js"],
      "timeout": 10000
    }
  },
  "telemetry": {
    "enabled": true,
    "target": "local",
    "outfile": "~/.gemini/telemetry.json",
    "logPrompts": false
  },
  "privacy": {
    "usageStatisticsEnabled": false
  }
}

环境变量速查 #

命令行参数速查 #

# 基础启动
gemini [提示词]                    # 交互模式，可直接附带初始提示词
gemini -p "提示词"                 # 无头模式（单次提示，已废弃，推荐用 gemini "提示词"）
gemini -i "提示词"                 # 交互模式，提示词作为初始输入

# 模型与模式
gemini --model gemini-2.5-pro     # 指定模型（最高优先级）
gemini --approval-mode auto_edit  # 设置批准模式（default/auto_edit/yolo/plan）
gemini --yolo                     # YOLO 模式（自动批准所有工具）
gemini --sandbox / -s             # 启用沙箱

# 会话管理
gemini --list-sessions            # 列出所有可用会话
gemini --resume [session_id]      # 恢复会话（session_id 可为序号、UUID 或 latest）
gemini --delete-session <id>      # 删除指定会话

# 输出格式
gemini --output-format json       # JSON 输出（适合脚本）
gemini --output-format stream-json # 流式 JSON 输出

# 工具与 MCP
gemini --allowed-tools "run_shell_command(git)"  # 指定绕过确认的工具
gemini --allowed-mcp-server-names "my-server"   # 允许的 MCP 服务器名

# 扩展
gemini -e my-extension            # 使用指定扩展
gemini -e none                    # 禁用所有扩展
gemini --list-extensions          # 列出所有可用扩展

# 目录
gemini --include-directories /path1,/path2  # 包含额外目录（最多 5 个）

# 调试与帮助
gemini --debug / -d               # 启用调试模式
gemini --screen-reader            # 屏幕阅读器模式
gemini --version                  # 显示版本
gemini --help / -h                # 显示帮助

# 高级
gemini --acp                      # 以 ACP 模式启动（IDE 集成）

环境变量脱敏 #

Gemini CLI 在执行工具时自动脱敏可能包含敏感信息的环境变量。

默认脱敏规则（按名称）：名称包含 TOKEN、SECRET、PASSWORD、KEY、AUTH、CREDENTIAL、PRIVATE、CERT 的变量。

默认脱敏规则（按值）：RSA/OpenSSH/PGP 私钥、证书、包含凭据的 URL、GitHub/Google/AWS/Stripe/Slack 等平台的 API Token。

始终不脱敏：系统变量（PATH、HOME 等）、以 GEMINI_CLI_ 开头的变量、GitHub Actions 变量。

自定义配置：

{
  "security": {
    "allowedEnvironmentVariables": ["MY_PUBLIC_KEY"],
    "blockedEnvironmentVariables": ["INTERNAL_IP_ADDRESS"]
  }
}

GEMINI.md 上下文文件层级 #

上下文文件（默认名 GEMINI.md，可通过 context.fileName 配置）按以下顺序加载：

1. 全局上下文：~/.gemini/GEMINI.md（对所有项目生效）
2. 项目根及父目录：从当前目录向上查找，到 .git 目录或 home 目录为止
3. 子目录上下文：当前目录下的子目录（最多 200 个，可通过 context.discoveryMaxDirs 配置）

所有找到的文件内容拼接后（附带文件路径标记）作为系统提示词传给模型。使用 /memory show 查看当前加载的完整上下文，用 /memory refresh 强制重新扫描。

沙箱配置 #

Gemini CLI 可以在沙箱中执行工具，防止意外操作影响系统。默认不启用，可通过以下方式开启：

• --sandbox 或 -s 命令行标志
• GEMINI_SANDBOX=true 环境变量
• --yolo 模式默认启用沙箱

默认使用预置的 gemini-cli-sandbox Docker 镜像。创建项目级自定义 Dockerfile（.gemini/sandbox.Dockerfile）可定制沙箱环境：

FROM gemini-cli-sandbox

# 安装自定义依赖
USER root
RUN apt-get update && apt-get install -y some-package
USER node

常见问题 #

Q: settings.json 修改后需要重启 CLI 吗？

A: 部分设置标注了"需重启"，修改后需要退出并重新启动 CLI 才能生效。未标注的设置大多可以通过 /settings 命令实时生效，或等下一轮对话时生效。

Q: 如何查看当前所有生效的配置？

A: 使用 /settings 命令可以打开交互式设置界面，查看和修改所有配置项。/memory show 可以查看当前加载的 GEMINI.md 内容。

Q: 项目 settings.json 和用户 settings.json 冲突时以哪个为准？

A: 项目配置（.gemini/settings.json）优先级高于用户配置（~/.gemini/settings.json）。单值字段（如 theme）以更高优先级层为准；数组和对象字段（如 mcpServers）会合并。系统覆盖文件（/etc/gemini-cli/settings.json）优先级最高，覆盖所有其他文件。