面向企业的 Gemini CLI

¥Gemini CLI for the Enterprise

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

¥This document outlines configuration patterns and best practices for deploying and managing Gemini CLI in an enterprise environment. By leveraging system-level settings, administrators can enforce security policies, manage tool access, and ensure a consistent experience for all users.

安全注意事项：本文档中描述的模式旨在帮助管理员创建一个更可控、更安全的环境来使用 Gemini CLI。然而，它们并非万无一失的安全边界。在本地计算机上拥有足够权限的坚定用户仍有可能绕过这些配置。这些措施旨在防止意外滥用并在托管环境中执行公司策略，而非防御拥有本地管理权限的恶意行为者。

¥A Note on Security: The patterns described in this document are intended to help administrators create a more controlled and secure environment for using Gemini CLI. However, they should not be considered a foolproof security boundary. A determined user with sufficient privileges on their local machine may still be able to circumvent these configurations. These measures are designed to prevent accidental misuse and enforce corporate policy in a managed environment, not to defend against a malicious actor with local administrative rights.

集中配置：系统设置文件

¥Centralized Configuration: The System Settings File

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

¥The most powerful tools for enterprise administration are the system-wide settings files. These files allow you to define a baseline configuration (system-defaults.json) and a set of overrides (settings.json) that apply to all users on a machine. For a complete overview of configuration options, see the Configuration documentation.

设置由四个文件合并而成。单值设置的优先顺序（例如theme） 是：

¥Settings are merged from four files. The precedence order for single-value settings (like theme) is:

1. 系统默认值（system-defaults.json)

   ¥System Defaults (system-defaults.json)

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

   ¥User Settings (~/.gemini/settings.json)

3. 工作区设置 (<project>/.gemini/settings.json)

   ¥Workspace Settings (<project>/.gemini/settings.json)

4. 系统覆盖（settings.json)

   ¥System Overrides (settings.json)

这意味着系统覆盖文件拥有最终决定权。对于数组形式的设置（includeDirectories) 或对象 (mcpServers)，这些值就会合并。

¥This means the System Overrides file has the final say. For settings that are arrays (includeDirectories) or objects (mcpServers), the values are merged.

合并和优先顺序的示例：

¥Example of Merging and Precedence:

以下是不同级别的设置的组合方式。

¥Here is how settings from different levels are combined.

• 系统默认值system-defaults.json：

  ¥System Defaults system-defaults.json:

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

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

• 用户settings.json(~/.gemini/settings.json):

  ¥User settings.json (~/.gemini/settings.json):

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

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

• 工作区settings.json(<project>/.gemini/settings.json):

  ¥Workspace settings.json (<project>/.gemini/settings.json):

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

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

• 系统覆盖settings.json： json { "theme": "system-enforced-theme", "mcpServers": { "corp-server": { "command": "/usr/local/bin/corp-server-prod" } }, "includeDirectories": ["/etc/gemini-cli/global-context"] }

  ¥System Overrides settings.json:json { "theme": "system-enforced-theme", "mcpServers": { "corp-server": { "command": "/usr/local/bin/corp-server-prod" } }, "includeDirectories": ["/etc/gemini-cli/global-context"] }

这会产生以下合并配置：

¥This results in the following merged configuration:

• 最终合并配置： json { "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" } }, "includeDirectories": [ "/etc/gemini-cli/common-context", "~/gemini-context", "./project-context", "/etc/gemini-cli/global-context" ] }

  ¥Final Merged Configuration:json { "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" } }, "includeDirectories": [ "/etc/gemini-cli/common-context", "~/gemini-context", "./project-context", "/etc/gemini-cli/global-context" ] }

为什么：

¥Why:

• theme：系统值覆盖（system-enforced-theme) 被使用，因为它具有最高优先级。

  ¥theme: The value from the system overrides (system-enforced-theme) is used, as it has the highest precedence.

• mcpServers：对象已合并。corp-server系统覆盖的定义优先于用户定义。唯一的user-tool和project-tool都包括在内。

  ¥mcpServers: The objects are merged. The corp-server definition from the system overrides takes precedence over the user's definition. The unique user-tool and project-tool are included.

• includeDirectories：数组按照系统默认值、用户、工作区、系统覆盖的顺序连接。

  ¥includeDirectories: The arrays are concatenated in the order of System Defaults, User, Workspace, and then System Overrides.

• 地点：

  ¥Location:

• Linux：/etc/gemini-cli/settings.json

  ¥Linux: /etc/gemini-cli/settings.json

• 视窗：C:\ProgramData\gemini-cli\settings.json

  ¥Windows: C:\ProgramData\gemini-cli\settings.json

• macOS：/Library/Application Support/GeminiCli/settings.json

  ¥macOS: /Library/Application Support/GeminiCli/settings.json

• 可以使用以下方式覆盖路径GEMINI_CLI_SYSTEM_SETTINGS_PATH环境变量。

  ¥The path can be overridden using the GEMINI_CLI_SYSTEM_SETTINGS_PATH environment variable.

• 控制：此文件应由系统管理员管理并使用适当的文件权限进行保护，以防止用户未经授权的修改。

  ¥Control: This file should be managed by system administrators and protected with appropriate file permissions to prevent unauthorized modification by users.

通过使用系统设置文件，您可以强制执行下面描述的安全和配置模式。

¥By using the system settings file, you can enforce the security and configuration patterns described below.

限制工具访问

¥Restricting Tool Access

通过控制 Gemini 模型可以使用的工具，可以显著增强安全性。这是通过以下方式实现的：coreTools和excludeTools设置。有关可用工具的列表，请参阅工具文档。

¥You can significantly enhance security by controlling which tools the Gemini model can use. This is achieved through the coreTools and excludeTools settings. For a list of available tools, see the Tools documentation.

列入许可名单coreTools

¥Allowlisting with coreTools

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

¥The most secure approach is to explicitly add the tools and commands that users are permitted to execute to an allowlist. This prevents the use of any tool not on the approved list.

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

¥Example: Allow only safe, read-only file operations and listing files.

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

列入黑名单excludeTools

¥Blocklisting with excludeTools

或者，您可以将在您的环境中被视为危险的特定工具添加到阻止列表中。

¥Alternatively, you can add specific tools that are considered dangerous in your environment to a blocklist.

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

¥Example: Prevent the use of the shell tool for removing files.

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

安全说明：列入黑名单excludeTools安全性不如允许列表coreTools，因为它依赖于阻止已知的恶意命令，而聪明的用户可能会找到绕过简单的基于字符串的阻止的方法。允许列表是推荐的方法。

¥Security Note: Blocklisting with excludeTools is less secure than allowlisting with coreTools, as it relies on blocking known-bad commands, and clever users may find ways to bypass simple string-based blocks. Allowlisting is the recommended approach.

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

¥Managing Custom Tools (MCP Servers)

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

¥If your organization uses custom tools via Model-Context Protocol (MCP) servers, it is crucial to understand how server configurations are managed to apply security policies effectively.

MCP 服务器配置如何合并

¥How MCP Server Configurations are Merged

Gemini CLI 加载settings.json三个级别的文件：系统、工作区和用户。当涉及到mcpServers对象，这些配置是合并：

¥Gemini CLI loads settings.json files from three levels: System, Workspace, and User. When it comes to the mcpServers object, these configurations are merged:

1. 合并：所有三个级别的服务器列表合并为一个列表。

   ¥Merging: The lists of servers from all three levels are combined into a single list.

2. 优先级：如果服务器同名在多个级别上定义（例如，名为corp-api如果在系统设置和用户设置中都存在，则使用优先级最高的定义。优先级顺序如下：系统 > 工作区 > 用户。

   ¥Precedence: If a server with the same name is defined at multiple levels (e.g., a server named corp-api exists in both system and user settings), the definition from the highest-precedence level is used. The order of precedence is: System > Workspace > User.

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

¥This means a user cannot override the definition of a server that is already defined in the system-level settings. However, they can add new servers with unique names.

强制执行工具目录

¥Enforcing a Catalog of Tools

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

¥The security of your MCP tool ecosystem depends on a combination of defining the canonical servers and adding their names to an allowlist.

限制 MCP 服务器内的工具

¥Restricting Tools Within an MCP Server

为了提高安全性，尤其是在处理第三方 MCP 服务器时，您可以限制服务器中哪些特定工具可以暴露给模型。这可以通过使用includeTools和excludeTools服务器定义中的属性。这允许您使用服务器中的部分工具，而不必担心使用存在潜在危险的工具。

¥For even greater security, especially when dealing with third-party MCP servers, you can restrict which specific tools from a server are exposed to the model. This is done using the includeTools and excludeTools properties within a server's definition. This allows you to use a subset of tools from a server without allowing potentially dangerous ones.

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

¥Following the principle of least privilege, it is highly recommended to use includeTools to create an allowlist of only the necessary tools.

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

¥Example: Only allow the code-search and get-ticket-details tools from a third-party MCP server, even if the server offers other tools like delete-ticket.

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

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

¥More Secure Pattern: Define and Add to Allowlist in System Settings

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

¥To create a secure, centrally-managed catalog of tools, the system administrator must do both of the following in the system-level settings.json file:

1. 定义完整配置对于每个已批准的服务器mcpServers对象。这确保即使用户定义了同名的服务器，安全的系统级定义也将优先。

   ¥Define the full configuration for every approved server in the mcpServers object. This ensures that even if a user defines a server with the same name, the secure system-level definition will take precedence.

2. 添加名称将这些服务器添加到允许列表中，使用allowMCPServers设置。这是一个关键的安全步骤，可防止用户运行任何不在此列表上的服务器。如果省略此设置，CLI 将合并并允许用户定义的任何服务器。

   ¥Add the names of those servers to an allowlist using the allowMCPServers setting. This is a critical security step that prevents users from running any servers that are not on this list. If this setting is omitted, the CLI will merge and allow any server defined by the user.

示例系统settings.json：

¥Example System settings.json:

1. 添加名字将所有已批准的服务器添加到允许列表中。这将阻止用户添加自己的服务器。

   ¥Add the names of all approved servers to an allowlist. This will prevent users from adding their own servers.

2. 提供规范定义对于允许列表中的每个服务器。

   ¥Provide the canonical definition for each server on the allowlist.

{
  "allowMCPServers": ["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"
    }
  }
}

此模式更安全，因为它同时使用定义和允许列表。用户定义的任何服务器要么会被系统定义覆盖（如果名称相同），要么会被阻止，因为其名称不在allowMCPServers列表。

¥This pattern is more secure because it uses both definition and an allowlist. Any server a user defines will either be overridden by the system definition (if it has the same name) or blocked because its name is not in the allowMCPServers list.

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

¥Less Secure Pattern: Omitting the Allowlist

如果管理员定义mcpServers对象，但未能指定allowMCPServers允许名单，用户可以添加自己的服务器。

¥If the administrator defines the mcpServers object but fails to also specify the allowMCPServers allowlist, users may add their own servers.

示例系统settings.json：

¥Example System settings.json:

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

¥This configuration defines servers but does not enforce the allowlist. The administrator has NOT included the "allowMCPServers" setting.

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

在这种情况下，用户可以在本地添加自己的服务器settings.json. 因为没有allowMCPServers列表来过滤合并的结果，用户的服务器将被添加到可用工具列表中并允许运行。

¥In this scenario, a user can add their own server in their local settings.json. Because there is no allowMCPServers list to filter the merged results, the user's server will be added to the list of available tools and allowed to run.

强制沙盒安全

¥Enforcing Sandboxing for Security

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

¥To mitigate the risk of potentially harmful operations, you can enforce the use of sandboxing for all tool execution. The sandbox isolates tool execution in a containerized environment.

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

¥Example: Force all tool execution to happen within a Docker sandbox.

{
  "sandbox": "docker"
}

您还可以使用--sandbox-image命令行参数或通过构建自定义sandbox.Dockerfile如上所述沙盒文档。

¥You can also specify a custom, hardened Docker image for the sandbox using the --sandbox-image command-line argument or by building a custom sandbox.Dockerfile as described in the Sandboxing documentation.

通过代理控制网络访问

¥Controlling Network Access via Proxy

在具有严格网络策略的公司环境中，您可以配置 Gemini CLI，将所有出站流量路由到公司代理。这可以通过环境变量设置，也可以通过以下方式强制自定义工具使用：mcpServers配置。

¥In corporate environments with strict network policies, you can configure Gemini CLI to route all outbound traffic through a corporate proxy. This can be set via an environment variable, but it can also be enforced for custom tools via the mcpServers configuration.

示例（针对 MCP 服务器）：

¥Example (for an MCP Server):

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

遥测和审计

¥Telemetry and Auditing

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

¥For auditing and monitoring purposes, you can configure Gemini CLI to send telemetry data to a central location. This allows you to track tool usage and other events. For more information, see the telemetry documentation.

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

¥Example: Enable telemetry and send it to a local OTLP collector. If otlpEndpoint is not specified, it defaults to http://localhost:4317.

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

笔记：确保logPrompts设置为false在企业环境中避免从用户提示中收集潜在的敏感信息。

¥Note: Ensure that logPrompts is set to false in an enterprise setting to avoid collecting potentially sensitive information from user prompts.

整合：示例系统settings.json

¥Putting It All Together: Example System settings.json

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

¥Here is an example of a system settings.json file that combines several of the patterns discussed above to create a secure, controlled environment for Gemini CLI.

{
  "sandbox": "docker",

  "coreTools": [
    "ReadFileTool",
    "GlobTool",
    "ShellTool(ls)",
    "ShellTool(cat)",
    "ShellTool(grep)"
  ],

  "mcpServers": {
    "corp-tools": {
      "command": "/opt/gemini-tools/start.sh",
      "timeout": 5000
    }
  },
  "allowMCPServers": ["corp-tools"],

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

  "bugCommand": {
    "urlTemplate": "https://servicedesk.example.com/new-ticket?title={title}&details={info}"
  },

  "usageStatisticsEnabled": false
}

此配置：

¥This configuration:

• 强制所有工具执行到 Docker 沙箱中。

  ¥Forces all tool execution into a Docker sandbox.

• 严格使用允许列表来保护一小部分安全的 shell 命令和文件工具。

  ¥Strictly uses an allowlist for a small set of safe shell commands and file tools.

• 定义并允许单个企业 MCP 服务器用于自定义工具。

  ¥Defines and allows a single corporate MCP server for custom tools.

• 启用遥测进行审计，但不记录提示内容。

  ¥Enables telemetry for auditing, without logging prompt content.

• 重定向/bug命令至内部票务系统。

  ¥Redirects the /bug command to an internal ticketing system.

• 禁用一般使用情况统计信息收集。

  ¥Disables general usage statistics collection.