Gemini CLI Docs

简体中文

English

简体中文

English

主题

Gemini CLI for the Enterprise ​

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 创建一个更受控和更安全的环境。但是，它们不应被视为万无一失的安全边界。在本地机器上拥有足够权限的决心坚定的用户仍然可能绕过这些配置。这些措施旨在防止意外误用并在托管环境中强制执行公司策略，而不是防御具有本地管理权限的恶意行为者。

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

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

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

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

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

合并和优先级的示例：

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

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

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

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

    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)：

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

  • 系统覆盖设置 settings.json：

    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"
    },
    "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 模型可以使用的工具，可以显著增强安全性。这通过 tools.core 和 tools.exclude 设置来实现。有关可用工具的列表，请参阅工具文档。

使用 coreTools 进行允许列表 ​

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

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

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

使用 excludeTools 进行阻止列表 ​

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

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

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

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

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

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

MCP 服务器配置的合并方式 ​

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

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

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

强制执行工具目录 ​

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

限制 MCP 服务器内的工具 ​

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

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

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

json
{
  "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 文件中执行以下两项操作：

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

系统 settings.json 示例：

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

  2. 为允许列表中的每个服务器提供_定义_。

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

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

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

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

系统 settings.json 示例：

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

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

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

强制执行沙箱以提高安全性 ​

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

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

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

您还可以通过 --sandbox-image 命令行参数或构建自定义 sandbox.Dockerfile（如沙箱文档中所述）来指定用于沙箱的自定义、加固的 Docker 镜像。

通过代理控制网络访问 ​

在具有严格网络策略的公司环境中，您可以配置 Gemini CLI 将所有出站流量通过公司代理进行路由。这可以通过环境变量设置，但也可以通过 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"
      }
    }
  }
}

遥测和审计 ​

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

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

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

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

身份验证 ​

您可以通过在系统级 settings.json 文件中设置 enforcedAuthType 来强制所有用户使用特定的身份验证方法。这可以防止用户选择其他身份验证方法。有关更多详细信息，请参阅身份验证文档。

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

json
{
  "enforcedAuthType": "oauth-personal"
}

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

整合：系统 settings.json 示例 ​

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

json
{
  "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 命令重定向到内部服务台系统。
  • 禁用常规使用统计信息收集。

基于 MIT 许可证发布

版权所有 © 2025-至今