企业版 Gemini CLI

本文档概述了在企业环境中部署和管理 Gemini CLI 的配置模式和最佳实践。通过利用系统级设置，管理员可以强制执行安全策略、管理工具访问并确保所有用户获得一致的体验。

安全说明： 本文档中描述的模式旨在帮助管理员为使用 Gemini CLI 创建更受控和安全的环境。但是，它们不应被视为万无一失的安全边界。在本地机器上具有足够权限的坚定用户仍然可能绕过这些配置。这些措施旨在防止意外误用并在受管环境中强制执行公司政策，而不是防御具有本地管理权限的恶意行为者。

集中配置：系统设置文件

企业管理最强大的工具是系统范围的设置文件。这些文件允许你定义基线配置（system-defaults.json）和一组覆盖（settings.json），适用于机器上的所有用户。有关配置选项的完整概述，请参阅配置文档。有关认证选项，请参阅认证文档。

设置从四个文件合并。单值设置（如 theme）的优先级顺序是：

1. 系统默认值（system-defaults.json）
2. 用户设置（~/.gemini/settings.json）
3. 工作区设置（<project>/.gemini/settings.json）
4. 系统覆盖（settings.json）

这意味着系统覆盖文件具有最终决定权。对于数组（includeDirectories）或对象（mcpServers）的设置，值会被合并。

• 位置：
  • 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 环境变量覆盖路径。
• 控制：此文件应由系统管理员管理，并使用适当的文件权限保护，以防止用户未经授权的修改。

限制工具访问

你可以通过控制 Gemini 模型可以使用哪些工具来显著增强安全性。这是通过 tools.core 和 tools.exclude 设置实现的。有关可用工具的列表，请参阅工具文档。

使用 coreTools 进行白名单

最安全的方法是明确将用户允许执行的工具和命令添加到白名单。这可以防止使用任何不在批准列表中的工具。

示例： 只允许安全的只读文件操作和列出文件。

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

使用 excludeTools 进行黑名单

或者，你可以将环境中被认为危险的特定工具添加到黑名单。

示例： 防止使用 shell 工具删除文件。

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

安全说明： 使用 excludeTools 进行黑名单不如使用 coreTools 进行白名单安全，因为它依赖于阻止已知的坏命令，聪明的用户可能会找到绕过简单字符串阻止的方法。推荐使用白名单方法。

禁用 YOLO 模式

为确保用户无法绕过工具执行的确认提示，你可以在策略级别禁用 YOLO 模式。这增加了关键的安全层，因为它防止模型在没有明确用户批准的情况下执行工具。

示例： 强制所有工具执行需要用户确认。

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

强烈建议在企业环境中使用此设置，以防止意外的工具执行。

管理自定义工具（MCP 服务器）

如果你的组织通过 Model-Context Protocol (MCP) 服务器使用自定义工具，了解服务器配置如何管理以有效应用安全策略至关重要。

MCP 服务器配置如何合并

Gemini CLI 从三个级别加载 settings.json 文件：系统、工作区和用户。对于 mcpServers 对象，这些配置会被合并：

1. 合并： 来自所有三个级别的服务器列表合并为一个列表。
2. 优先级： 如果在多个级别定义了同名的服务器（例如，名为 corp-api 的服务器同时存在于系统和用户设置中），则使用最高优先级级别的定义。优先级顺序是：系统 > 工作区 > 用户。

这意味着用户无法覆盖系统级设置中已定义的服务器的定义。但是，他们可以添加具有唯一名称的新服务器。

强制执行工具目录

MCP 工具生态系统的安全性取决于定义规范服务器和将其名称添加到白名单的组合。

限制 MCP 服务器中的工具

为了获得更高的安全性，特别是在处理第三方 MCP 服务器时，你可以限制服务器中哪些特定工具暴露给模型。这是通过服务器定义中的 includeTools 和 excludeTools 属性完成的。这允许你使用服务器的工具子集，而不允许潜在危险的工具。

遵循最小权限原则，强烈建议使用 includeTools 创建仅包含必要工具的白名单。

示例： 只允许第三方 MCP 服务器的 code-search 和 get-ticket-details 工具，即使服务器提供其他工具如 delete-ticket。

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

强制沙盒以确保安全

为了降低潜在有害操作的风险，你可以强制所有工具执行使用沙盒。沙盒在容器化环境中隔离工具执行。

示例： 强制所有工具执行在 Docker 沙盒中进行。

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

你还可以通过构建自定义 sandbox.Dockerfile 为沙盒指定自定义的加固 Docker 镜像，如沙盒文档中所述。

通过代理控制网络访问

在具有严格网络策略的企业环境中，你可以配置 Gemini CLI 通过企业代理路由所有出站流量。这可以通过环境变量设置，但也可以通过 mcpServers 配置为自定义工具强制执行。

示例（用于 MCP 服务器）：

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

遥测和审计

出于审计和监控目的，你可以配置 Gemini CLI 将遥测数据发送到中央位置。这允许你跟踪工具使用和其他事件。有关更多信息，请参阅遥测文档。

示例： 启用遥测并将其发送到本地 OTLP 收集器。

{
  "telemetry": {
    "enabled": true,
    "target": "gcp",
    "logPrompts": false
  }
}

注意： 确保在企业设置中将 logPrompts 设置为 false，以避免从用户提示中收集潜在敏感信息。

身份验证

你可以通过在系统级 settings.json 文件中设置 enforcedAuthType 来为所有用户强制执行特定的身份验证方法。这可以防止用户选择不同的身份验证方法。有关更多详情，请参阅身份验证文档。

示例： 强制所有用户使用 Google 登录。

{
  "enforcedAuthType": "oauth-personal"
}