AI Coding Tools 文档

简体中文

English

简体中文

English

主题

企业级 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），值会被合并。

合并和优先级示例：

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

  • 系统默认值 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 Servers） ​

如果您的组织通过模型上下文协议(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。

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-至今