面向企业的 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"]
  }
}

用户设置 ~/.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"]
  }
}

工作区设置 <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/global-context",
      "~/gemini-context",
      "./project-context"
    ]
  }
}

系统目录结构

Linux/macOS

系统默认配置：/etc/opt/gemini-cli/system-defaults.json
系统覆盖配置：/etc/opt/gemini-cli/settings.json

Windows

系统默认配置：C:\ProgramData\Gemini CLI\system-defaults.json
系统覆盖配置：C:\ProgramData\Gemini CLI\settings.json

用户目录（跨平台）

用户设置：~/.gemini/settings.json
用户命令：~/.gemini/commands/
用户记忆：~/.gemini/memory/
用户扩展：~/.gemini/extensions/

工作区目录

工作区设置：<workspace>/.gemini/settings.json
工作区命令：<workspace>/.gemini/commands/
工作区记忆：<workspace>/.gemini/memory/

强制执行工具安全策略

通过系统覆盖文件，管理员可以严格限制工具调用。常见策略：

{
  "tools": {
    "core": [
      "ReadFileTool",
      "GlobTool",
      "ShellTool(ls)",
      "ShellTool(cat)",
      "ShellTool(grep)"
    ],
    "sandbox": "docker"
  }
}

仅允许读取/搜索类工具及白名单 shell 命令。
所有工具调用都在 Docker 沙箱内执行。

默认情况下，Gemini CLI 包含多个内置工具（读写文件、执行命令、网络访问等），管理员可根据需要保留或禁止。

配置沙箱执行环境

在企业环境中，建议强制使用沙箱。例如：

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

这样 CLI 将通过 Docker 容器执行敏感操作。如果企业使用自定义沙箱镜像，可通过命令行 --sandbox-image 参数或自定义 sandbox.Dockerfile（详情见沙箱文档）进行配置。

控制网络访问（代理）

在网络管控严格的环境中，可以让 Gemini CLI 经由企业代理访问外部网络。可通过环境变量设置，也可在 mcpServers 中为自定义工具强制指定：

{
  "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": {
    "enabled": true,
    "target": "gcp",
    "logPrompts": false
  }
}

注意： 在企业环境中务必将 logPrompts 设为 false，避免收集可能敏感的用户输入。

认证策略

可通过系统级 settings.json 强制指定所有用户的认证方式，避免自由切换。示例：

{
  "enforcedAuthType": "oauth-personal"
}

若用户当前配置的认证方式与强制策略不符，CLI 会提示切换；在非交互模式下则直接报错退出。更多信息见认证文档。

综合示例：系统级 `settings.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 server。
启用遥测用于审计，同时不记录 Prompt 内容。
将 /bug 命令重定向至内部工单系统。
禁用通用使用统计。

通过这些策略，管理员可以在企业环境下为 Gemini CLI 提供稳健、安全、可控的使用体验。