Skip to content

Gemini CLI 中的沙盒

¥Sandboxing in the Gemini CLI

本文档提供了 Gemini CLI 中沙盒的指南，包括先决条件、快速入门和配置。

¥This document provides a guide to sandboxing in the Gemini CLI, including prerequisites, quickstart, and configuration.

先决条件

¥Prerequisites

在使用沙盒之前，您需要安装并设置 Gemini CLI：

¥Before using sandboxing, you need to install and set up the Gemini CLI:

npm install -g @google/gemini-cli

验证安装

¥To verify the installation

gemini --version

沙盒概述

¥Overview of sandboxing

沙盒将潜在的危险操作（例如 shell 命令或文件修改）与主机系统隔离，从而在 AI 操作和您的环境之间提供安全屏障。

¥Sandboxing isolates potentially dangerous operations (such as shell commands or file modifications) from your host system, providing a security barrier between AI operations and your environment.

沙盒的好处包括：

¥The benefits of sandboxing include:

  • 安全：防止意外的系统损坏或数据丢失。

    ¥Security: Prevent accidental system damage or data loss.

  • 隔离：限制文件系统对项目目录的访问。

    ¥Isolation: Limit file system access to project directory.

  • 一致性：确保不同系统之间的可重现环境。

    ¥Consistency: Ensure reproducible environments across different systems.

  • 安全：使用不受信任的代码或实验命令时降低风险。

    ¥Safety: Reduce risk when working with untrusted code or experimental commands.

沙盒方法

¥Sandboxing methods

您的理想沙盒方法可能因您的平台和首选的容器解决方案而异。

¥Your ideal method of sandboxing may differ depending on your platform and your preferred container solution.

1. macOS 安全带（仅限 macOS）

¥1. macOS Seatbelt (macOS only)

轻量级内置沙盒使用sandbox-exec。

¥Lightweight, built-in sandboxing using sandbox-exec.

默认配置文件：permissive-open- 限制项目目录之外的写入但允许大多数其他操作。

¥Default profile: permissive-open - restricts writes outside project directory but allows most other operations.

2.基于容器（Docker/Podman）

¥2. Container-based (Docker/Podman)

跨平台沙盒，具有完全的进程隔离。

¥Cross-platform sandboxing with complete process isolation.

笔记：需要在本地构建沙盒图像或使用来自组织注册表的已发布图像。

¥Note: Requires building the sandbox image locally or using a published image from your organization's registry.

快速入门

¥Quickstart

# Enable sandboxing with command flag
gemini -s -p "analyze the code structure"

# Use environment variable
export GEMINI_SANDBOX=true
gemini -p "run the test suite"

# Configure in settings.json
{
  "sandbox": "docker"
}

配置

¥Configuration

启用沙盒（按优先顺序）

¥Enable sandboxing (in order of precedence)

  1. 命令标志：-s或者--sandbox

    ¥Command flag: -s or --sandbox

  2. 环境变量：GEMINI_SANDBOX=true|docker|podman|sandbox-exec

    ¥Environment variable: GEMINI_SANDBOX=true|docker|podman|sandbox-exec

  3. 设置文件："sandbox": true在settings.json

    ¥Settings file: "sandbox": true in settings.json

macOS 安全带配置文件

¥macOS Seatbelt profiles

内置配置文件（通过SEATBELT_PROFILE环境变量):

¥Built-in profiles (set via SEATBELT_PROFILE env var):

  • permissive-open（默认）：写入限制，网络允许

    ¥permissive-open (default): Write restrictions, network allowed

  • permissive-closed：写入限制，无网络

    ¥permissive-closed: Write restrictions, no network

  • permissive-proxied：写入限制，通过代理网络

    ¥permissive-proxied: Write restrictions, network via proxy

  • restrictive-open：严格限制，网络允许

    ¥restrictive-open: Strict restrictions, network allowed

  • restrictive-closed：最大限制

    ¥restrictive-closed: Maximum restrictions

自定义沙盒标志

¥Custom Sandbox Flags

对于基于容器的沙盒，您可以将自定义标志注入docker或者podman命令使用SANDBOX_FLAGS环境变量。这对于高级配置很有用，例如针对特定用例禁用安全功能。

¥For container-based sandboxing, you can inject custom flags into the docker or podman command using the SANDBOX_FLAGS environment variable. This is useful for advanced configurations, such as disabling security features for specific use cases.

示例（Podman）：

¥Example (Podman):

要禁用卷挂载的 SELinux 标签，您可以设置以下内容：

¥To disable SELinux labeling for volume mounts, you can set the following:

export SANDBOX_FLAGS="--security-opt label=disable"

可以将多个标志作为空格分隔的字符串提供：

¥Multiple flags can be provided as a space-separated string:

export SANDBOX_FLAGS="--flag1 --flag2=value"

Linux UID/GID 处理

¥Linux UID/GID handling

沙盒会自动处理 Linux 上的用户权限。您可以使用以下命令覆盖这些权限：

¥The sandbox automatically handles user permissions on Linux. Override these permissions with:

export SANDBOX_SET_UID_GID=true   # Force host UID/GID
export SANDBOX_SET_UID_GID=false  # Disable UID/GID mapping

故障排除

¥Troubleshooting

常见问题

¥Common issues

“操作不允许”

¥"Operation not permitted"

  • 操作需要访问沙箱外部。

    ¥Operation requires access outside sandbox.

  • 尝试更宽松的配置文件或添加挂载点。

    ¥Try more permissive profile or add mount points.

缺少命令

¥Missing commands

  • 添加到自定义 Dockerfile。

    ¥Add to custom Dockerfile.

  • 通过安装sandbox.bashrc。

    ¥Install via sandbox.bashrc.

网络问题

¥Network issues

  • 检查沙盒配置文件是否允许网络。

    ¥Check sandbox profile allows network.

  • 验证代理配置。

    ¥Verify proxy configuration.

调试模式

¥Debug mode

DEBUG=1 gemini -s -p "debug command"

笔记：如果你有DEBUG=true在一个项目中.env文件，由于自动排除，它不会影响 gemini-cli。使用.gemini/.envgemini-cli 特定调试设置的文件。

¥Note: If you have DEBUG=true in a project's .env file, it won't affect gemini-cli due to automatic exclusion. Use .gemini/.env files for gemini-cli specific debug settings.

检查沙盒

¥Inspect sandbox

# Check environment
gemini -s -p "run shell command: env | grep SANDBOX"

# List mounts
gemini -s -p "run shell command: mount | grep workspace"

安全说明

¥Security notes

  • 沙盒可以减少但不能消除所有风险。

    ¥Sandboxing reduces but doesn't eliminate all risks.

  • 使用允许您工作的最严格的配置文件。

    ¥Use the most restrictive profile that allows your work.

  • 首次构建后，容器开销很小。

    ¥Container overhead is minimal after first build.

  • GUI 应用程序可能无法在沙箱中运行。

    ¥GUI applications may not work in sandboxes.

¥Related documentation