企业级 Gemini CLI

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

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

集中式配置：系统设置文件

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

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

系统默认值（system-defaults.json）
用户设置（~/.gemini/settings.json）
工作空间设置（<project>/.gemini/settings.json）
系统覆盖（settings.json）

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

合并和优先级示例：

以下是不同级别的设置如何组合的示例。

系统默认值 system-defaults.json:

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

用户设置 settings.json (~/.gemini/settings.json):

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

工作空间 settings.json (<project>/.gemini/settings.json):

{
  "ui": {
    "theme": "project-specific-light-theme"
  },
  "mcpServers": {
    "project-tool": {
      "command": "npm start"
    }
  },
  "context": {
    "includeDirectories": ["./project-context"]
  }
}

系统覆盖 settings.json:

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

这将产生以下合并的配置：

最终合并配置：

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

原因：

theme：使用系统覆盖（system-enforced-theme）中的值，因为它具有最高优先级。
mcpServers：对象被合并。系统覆盖中的corp-server定义优先于用户的定义。唯一的user-tool和project-tool被包含。
includeDirectories：数组按系统默认值、用户、工作空间，然后是系统覆盖的顺序连接。
位置：
- 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_CLI_SYSTEM_SETTINGS_PATH环境变量提供了灵活性，但用户可能潜在地将其覆盖以指向不同的设置文件，绕过集中管理的配置。为了缓解这一问题，企业可以部署一个封装脚本或别名，确保环境变量始终设置为公司控制的路径。

这种方法确保无论用户如何调用gemini命令，企业设置始终以最高优先级加载。

封装脚本示例：

gemini

管理员可以创建一个名为 gemini 的脚本，并将其放置在用户的 PATH 中比实际的 Gemini CLI 可执行文件更早出现的目录中（例如，/usr/local/bin/gemini）。

#!/bin/bash

# Enforce the path to the corporate system settings file.
# This ensures that the company's configuration is always applied.
export GEMINI_CLI_SYSTEM_SETTINGS_PATH="/etc/gemini-cli/settings.json"

# Find the original gemini executable.
# This is a simple example; a more robust solution might be needed
# depending on the installation method.
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

# Pass all arguments to the real Gemini CLI executable.
exec "$REAL_GEMINI_PATH" "$@"

通过部署这个脚本，在脚本环境中设置了 GEMINI_CLI_SYSTEM_SETTINGS_PATH，并且 exec 命令将脚本进程替换为实际的 Gemini CLI 进程，该进程继承了环境变量。这使得用户绕过强制设置变得更加困难。

限制工具访问

通过控制 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 服务器）

如果您的组织通过模型上下文协议（MCP）服务器使用自定义工具，那么了解服务器配置如何管理对于有效应用安全策略至关重要。

MCP 服务器配置如何合并

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

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

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

实施工具目录

MCP 工具生态系统的安全性取决于定义规范服务器并将它们的名称添加到允许列表的组合。

在 MCP 服务器内限制工具

为了获得更高的安全性，特别是在处理第三方 MCP 服务器时，您可以限制服务器中哪些特定工具对模型开放。这是通过在服务器定义内的includeTools和excludeTools属性完成的。这使得您可以使用服务器中的一组工具，而不必允许可能存在危险的工具。

遵循最小权限原则，强烈建议使用includeTools创建只包含必要工具的允许列表。

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

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

更安全的模式：在系统设置中定义并添加到允许列表

为了创建一个安全、集中管理的工具目录，系统管理员必须在系统级别的settings.json文件中执行以下两项操作：

定义每个批准服务器的完整配置 在mcpServers对象中。这确保即使用户定义了同名的服务器，安全的系统级定义也将优先。
将那些服务器的名称 添加到使用mcp.allowed设置的允许列表中。这是一个关键的安全步骤，防止用户运行不在列表中的任何服务器。如果省略此设置，CLI将合并并允许用户定义的任何服务器。

示例系统settings.json：

将所有批准服务器的_name_添加到允许列表中。这将防止用户添加自己的服务器。
为允许列表中的每个服务器提供规范的_definition_。

{
  "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"
    }
  }
}

这种模式更安全，因为它同时使用定义和允许列表。用户定义的任何服务器要么被系统定义覆盖（如果它具有相同的名称），要么因为其名称不在mcp.allowed列表中而被阻止。

较不安全的模式：省略允许列表

如果管理员定义了mcpServers对象，但未能同时指定mcp.allowed允许列表，用户可能会添加自己的服务器。

示例系统settings.json：

此配置定义了服务器，但未强制执行允许列表。管理员未包含“mcp.allowed”设置。

{
  "mcpServers": {
    "corp-data-api": {
      "command": "/usr/local/bin/start-corp-api.sh"
    }
  }
}

【译文】

在此场景中，用户可以在本地添加自己的服务器settings.json。由于没有mcp.allowed列表来过滤合并的结果，用户的服务器将被添加到可用工具列表中，并允许运行。

加强沙箱机制以保障安全

为了减轻潜在有害操作的风险，您可以强制所有工具执行时使用沙箱机制。沙箱将在容器化环境中隔离工具执行。

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

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

您还可以通过构建定制的sandbox.Dockerfile来为沙箱指定一个加固的Docker镜像，具体方法请参阅Sandboxing documentation。

通过代理控制网络访问

在严格网络政策的公司环境中，您可以配置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将遥测数据发送到中央位置。这允许您跟踪工具使用和其他事件。更多信息请参阅telemetry documentation。

示例： 启用遥测并将数据发送到本地OTLP收集器。如果otlpEndpoint未指定，默认为http://localhost:4317。

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

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

认证

您可以通过在系统级settings.json文件中设置enforcedAuthType，为所有用户强制实施特定的认证方法。这防止用户选择不同的认证方法。更多详情请参阅Authentication docs。

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

如果用户配置了不同的认证方法，他们将被提示切换到强制的方法。在非交互模式下，如果配置的认证方法与强制的方法不匹配，CLI 将会以错误退出。

限制登录到企业域

对于使用Google Workspace的企业，您可以强制用户只能使用其企业Google 账户进行认证。这是一种网络级别的控制，配置在代理服务器上，而不是在 Gemini CLI 内部。它通过拦截对Google的认证请求并添加一个特殊的 HTTP 头部来工作。

此策略防止用户使用个人 Gmail 账户或其他非企业Google 账户登录。

有关详细说明，请参阅Google Workspace管理员帮助文章中关于阻止访问消费者账户的内容。

大致步骤如下：

拦截请求：配置您的网络代理以拦截所有到 google.com 的请求。
添加 HTTP 头部：对于每个被拦截的请求，添加 X-GoogApps-Allowed-Domains HTTP 头部。
指定域：头部的值应该是您批准的Google Workspace域名逗号分隔列表。

示例头部：

X-GoogApps-Allowed-Domains: my-corporate-domain.com, secondary-domain.com

当此头部存在时，Google的认证服务将只允许来自指定域的账户登录。

将所有内容整合在一起：示例系统 `settings.json`

以下是一个系统 settings.json 文件的示例，它结合了上述几种模式，为 Gemini CLI 创建了一个安全、受控的环境。

{
  "tools": {
    "sandbox": "docker",
    "core": [
      "ReadFileTool",
      "GlobTool",
      "ShellTool(ls)",
      "ShellTool(cat)",
      "ShellTool(grep)"
    ]
  },
  "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 命令和文件工具。
定义并允许单个企业级 MCP 服务器用于自定义工具。
启用遥测功能进行审计，但不记录提示内容。
将 /bug 命令重定向到内部工单系统。
禁用一般使用情况统计收集。

企业级 Gemini CLI

企业级 Gemini CLI

集中式配置：系统设置文件

使用封装脚本强制执行系统设置

限制工具访问

使用 coreTools 进行白名单设置

使用 excludeTools 进行黑名单设置

禁用 YOLO 模式

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

MCP 服务器配置如何合并

实施工具目录

在 MCP 服务器内限制工具

更安全的模式：在系统设置中定义并添加到允许列表

较不安全的模式：省略允许列表

加强沙箱机制以保障安全

通过代理控制网络访问

遥测与审计

认证

限制登录到企业域

将所有内容整合在一起：示例系统 settings.json

使用 `coreTools` 进行白名单设置

使用 `excludeTools` 进行黑名单设置

将所有内容整合在一起：示例系统 `settings.json`