Gemini CLI 为企业环境提供完整的集中管控机制：通过系统级 settings.json（优先级最高的 System Overrides 层）统一推送配置，结合 Policy Engine（TOML 规则文件）实现工具级精细授权，支持禁用 YOLO 模式、强制 Docker 沙箱、限制 MCP 服务器白名单和企业 Google Workspace 域名登录。这些措施防止意外滥用，但不构成抵御本地 root 用户的安全边界。

Gemini CLI 企业级部署指南

注意：本文档所述方案旨在防止意外误操作和执行企业合规政策，不能作为防范具有本机管理员权限恶意用户的安全边界。

配置层级与优先级

Gemini CLI 从四个文件合并配置，单值设置（如 theme）的优先级由低到高：

优先级	层级	文件路径
1（最低）	System Defaults	系统默认值文件（`system-defaults.json`）
2	User Settings	`~/.gemini/settings.json`
3	Workspace Settings	`<项目目录>/.gemini/settings.json`
4（最高）	System Overrides	系统覆盖文件（`settings.json`）

数组和对象类型（如 mcpServers、includeDirectories）采用合并策略，而非覆盖。

配置文件路径

系统级 System Overrides 文件的默认位置：

操作系统	路径
Linux	`/etc/gemini-cli/settings.json`
macOS	`/Library/Application Support/GeminiCli/settings.json`
Windows	`C:\ProgramData\gemini-cli\settings.json`

可通过环境变量覆盖路径：

bash

export GEMINI_CLI_SYSTEM_SETTINGS_PATH="/etc/gemini-cli/settings.json"

合并示例

以下示例展示四层配置如何合并为最终配置：

System Defaults（system-defaults.json）

json

{
  "ui": { "theme": "default-corporate-theme" },
  "context": { "includeDirectories": ["/etc/gemini-cli/common-context"] }
}

User Settings（~/.gemini/settings.json）

json

{
  "ui": { "theme": "user-preferred-dark-theme" },
  "mcpServers": {
    "user-tool": { "command": "npm start --prefix ~/tools/my-tool" }
  },
  "context": { "includeDirectories": ["~/gemini-context"] }
}

System Overrides（最终推送）

json

{
  "ui": { "theme": "system-enforced-theme" },
  "mcpServers": {
    "corp-server": { "command": "/usr/local/bin/corp-server-prod" }
  },
  "context": { "includeDirectories": ["/etc/gemini-cli/global-context"] }
}

合并结果

json

{
  "ui": { "theme": "system-enforced-theme" },
  "mcpServers": {
    "corp-server": { "command": "/usr/local/bin/corp-server-prod" },
    "user-tool": { "command": "npm start --prefix ~/tools/my-tool" }
  },
  "context": {
    "includeDirectories": [
      "/etc/gemini-cli/common-context",
      "~/gemini-context",
      "/etc/gemini-cli/global-context"
    ]
  }
}

theme：System Overrides 优先级最高，最终使用 system-enforced-theme
mcpServers：对象合并，同名服务器以高优先级层定义为准
includeDirectories：按 System Defaults → User → Workspace → System Overrides 顺序拼接

防止用户绕过配置

用户可以通过修改 GEMINI_CLI_SYSTEM_SETTINGS_PATH 环境变量绕过系统配置。对此，企业可以部署包装脚本强制固定路径：

Linux/macOS 示例（/usr/local/bin/gemini 包装脚本）

bash

#!/bin/bash
export GEMINI_CLI_SYSTEM_SETTINGS_PATH="/etc/gemini-cli/settings.json"

REAL_GEMINI_PATH=$(type -aP gemini | grep -v "^$(type -P gemini)$" | head -n 1)
if [ -z "$REAL_GEMINI_PATH" ]; then
  echo "Error: The original 'gemini' executable was not found." >&2
  exit 1
fi

exec "$REAL_GEMINI_PATH" "$@"

Windows（PowerShell Profile）

powershell

Add-Content -Path $PROFILE -Value '$env:GEMINI_CLI_SYSTEM_SETTINGS_PATH="C:\ProgramData\gemini-cli\settings.json"'

共享环境下的用户隔离

在共享计算节点（如 ML 实验平台、共享构建服务器）上，可以通过 GEMINI_CLI_HOME 环境变量为每个任务/用户隔离 Gemini CLI 的配置和历史数据：

bash

# Linux/macOS
export GEMINI_CLI_HOME="/tmp/gemini-job-123"
gemini

powershell

# Windows PowerShell
$env:GEMINI_CLI_HOME="C:\temp\gemini-job-123"
gemini

CLI 会在指定目录下创建 .gemini 文件夹，实现完全隔离的状态存储。

工具访问控制

白名单（推荐）：`coreTools`

最安全的方式是显式列出允许使用的工具，未在列表中的工具一律禁止：

json

{
  "tools": {
    "core": ["ReadFileTool", "GlobTool", "ShellTool(ls)"]
  }
}

黑名单（已废弃）：`excludeTools`

已废弃：请改用 Policy Engine 的 deny 规则，安全性更高。

json

{
  "tools": {
    "exclude": ["ShellTool(rm -rf)"]
  }
}

黑名单依赖字符串匹配，存在绕过风险，不推荐在企业环境中使用。

禁用 YOLO 模式

YOLO 模式允许模型不经用户确认直接执行所有工具。企业环境中强烈建议禁用：

json

{
  "security": {
    "disableYoloMode": true
  }
}

MCP 服务器管控

合并规则

三层设置（System / Workspace / User）中的 mcpServers 对象会合并。同名服务器按 System > Workspace > User 优先级取最高层的定义，用户无法覆盖系统层定义的服务器。

安全做法：白名单 + 显式定义

要完全控制 MCP 工具生态，需要同时做两件事：

在 mcp.allowed 中列出所有允许的服务器名（未在列表中的服务器不会加载）
在 mcpServers 中提供每个服务器的规范定义（防止用户用同名服务器替换）

json

{
  "mcp": {
    "allowed": ["corp-data-api", "source-code-analyzer"]
  },
  "mcpServers": {
    "corp-data-api": {
      "command": "/usr/local/bin/start-corp-api.sh",
      "timeout": 5000
    },
    "source-code-analyzer": {
      "command": "/usr/local/bin/start-analyzer.sh"
    }
  }
}

如果只配置 mcpServers 而不设置 mcp.allowed，用户仍可以添加自己的服务器。

限制单个 MCP 服务器的工具范围

使用 includeTools（白名单）限制第三方服务器只暴露必要工具：

json

{
  "mcpServers": {
    "third-party-analyzer": {
      "command": "/usr/local/bin/start-3p-analyzer.sh",
      "includeTools": ["code-search", "get-ticket-details"]
    }
  }
}

强制沙箱执行

在企业环境中，可以强制所有工具调用在 Docker 沙箱中运行：

json

{
  "tools": {
    "sandbox": "docker"
  }
}

如需使用加固的自定义镜像，可以创建自定义 sandbox.Dockerfile，详见沙箱安全隔离文档。

企业代理配置

通过 mcpServers 配置将代理注入 MCP 服务器环境：

json

{
  "mcpServers": {
    "proxied-server": {
      "command": "node",
      "args": ["mcp_server.js"],
      "env": {
        "HTTP_PROXY": "http://proxy.example.com:8080",
        "HTTPS_PROXY": "http://proxy.example.com:8080"
      }
    }
  }
}

遥测与审计

启用遥测将工具使用数据发送到集中日志系统（OTLP/GCP）。注意：在企业环境中，务必将 logPrompts 设为 false，避免记录用户敏感 Prompt 内容：

json

{
  "telemetry": {
    "enabled": true,
    "target": "gcp",
    "otlpEndpoint": "https://telemetry.example.com:4317",
    "logPrompts": false
  }
}

认证控制

强制认证方式

通过系统级配置锁定认证方式，防止用户切换：

json

{
  "security": {
    "auth": {
      "enforcedType": "oauth-personal"
    }
  }
}

限制企业域名登录（Google Workspace）

通过企业代理在 Google 认证请求中注入 X-GoogApps-Allowed-Domains 头部，只允许企业域名账号登录：

配置 Web 代理拦截对 google.com 的所有请求
为每个被拦截的请求添加头部：X-GoogApps-Allowed-Domains: my-corporate-domain.com

这样 Google 认证服务只接受指定域名的账号登录，拒绝个人 Gmail 账号。

完整配置示例

以下是一个综合了上述所有安全策略的系统 settings.json 示例：

json

{
  "tools": {
    "sandbox": "docker",
    "core": [
      "ReadFileTool",
      "GlobTool",
      "ShellTool(ls)",
      "ShellTool(cat)",
      "ShellTool(grep)"
    ]
  },
  "security": {
    "disableYoloMode": true,
    "auth": {
      "enforcedType": "oauth-personal"
    }
  },
  "mcp": {
    "allowed": ["corp-tools"]
  },
  "mcpServers": {
    "corp-tools": {
      "command": "/opt/gemini-tools/start.sh",
      "timeout": 5000
    }
  },
  "telemetry": {
    "enabled": true,
    "target": "gcp",
    "otlpEndpoint": "https://telemetry-prod.example.com:4317",
    "logPrompts": false
  },
  "advanced": {
    "bugCommand": {
      "urlTemplate": "https://servicedesk.example.com/new-ticket?title={title}&details={info}"
    }
  },
  "privacy": {
    "usageStatisticsEnabled": false
  }
}

此配置实现了：

所有工具执行强制走 Docker 沙箱
使用白名单限制允许的 Shell 命令和文件工具
禁用 YOLO 模式，要求所有工具调用经过用户确认
定义并白名单化企业 MCP 工具服务器
启用遥测审计，不记录 Prompt 内容
将 /bug 命令重定向到内部工单系统
关闭通用使用统计收集

常见问题

Q: system-defaults.json 和 settings.json（System Overrides）的区别是什么？

A: system-defaults.json 提供基准默认值，优先级最低，用户设置可以覆盖它；settings.json（System Overrides）优先级最高，会覆盖所有用户和项目设置。管理员应将必须执行的策略放入 System Overrides，将可选的默认值放入 system-defaults.json。

Q: 用户能绕过 mcp.allowed 白名单吗？

A: 如果系统 settings.json 设置了 mcp.allowed，该白名单会与最终合并结果一起应用，用户自定义的服务器如果不在白名单中将被拒绝加载。但如果系统层没有设置 mcp.allowed，用户仍可自由添加服务器。因此，白名单必须在系统层显式配置才有效。

Q: Policy Engine 和 tools.core 白名单有什么区别？

A: tools.core 是简单的工具级允许/拒绝，配置简单但粒度较粗；Policy Engine 支持基于参数模式（正则）、运行模式（YOLO/autoEdit/plan）、交互性等条件的细粒度规则，并支持管理员（Admin）层级策略，更适合复杂企业场景。

Gemini CLI 企业级部署指南 ​

配置层级与优先级 ​

配置文件路径 ​

合并示例 ​

防止用户绕过配置 ​

共享环境下的用户隔离 ​

工具访问控制 ​

白名单（推荐）：coreTools ​

黑名单（已废弃）：excludeTools ​

禁用 YOLO 模式 ​

MCP 服务器管控 ​

合并规则 ​

安全做法：白名单 + 显式定义 ​

限制单个 MCP 服务器的工具范围 ​

强制沙箱执行 ​

企业代理配置 ​

遥测与审计 ​

认证控制 ​

强制认证方式 ​

限制企业域名登录（Google Workspace） ​

完整配置示例 ​

常见问题 ​

Gemini CLI 企业级部署指南

配置层级与优先级

配置文件路径

合并示例

防止用户绕过配置

共享环境下的用户隔离

工具访问控制

白名单（推荐）：`coreTools`

黑名单（已废弃）：`excludeTools`

禁用 YOLO 模式

MCP 服务器管控

合并规则

安全做法：白名单 + 显式定义

限制单个 MCP 服务器的工具范围

强制沙箱执行

企业代理配置

遥测与审计

认证控制

强制认证方式

限制企业域名登录（Google Workspace）

完整配置示例

常见问题