要点速览
- 运行 gemini -s，整个会话——shell 命令、文件修改、网络请求——都会在隔离沙箱中执行；底部状态栏会出现沙箱标识，让你一眼确认它已生效。
- 三种启用方式按优先级依次生效：-s / --sandbox 命令行参数、GEMINI_SANDBOX 环境变量、settings.json 中 tools 对象里的 "sandbox": true。
- 后端按操作系统选择：macOS 用 Seatbelt 配置文件（默认 permissive-open），Linux 用 gVisor runsc 获得最强隔离，其余平台用 Docker 或 Podman 容器。
- YOLO 模式（--yolo）会跳过所有权限确认——请搭配沙箱一起用。v0.61.0（2026 年 9 月 23 日）加固了沙箱的文件系统边界并隔离了运行时状态。
Gemini CLI Essentials – Full Course (sandboxing chapter)
频道：freeCodeCamp.org3:49:40
Gemini CLI: Everything You Need To Know (Full Tutorial)
频道：lustoykov42:54
Sandboxing in Gemini CLI — official documentation
官方文档：google-gemini/gemini-cli (GitHub)
文中截图取自 freeCodeCamp 课程的沙箱章节；参数名、配置项和配置文件名称均已对照官方沙箱文档与 v0.61.0 发布说明逐一核实。
截图来源：freeCodeCamp.org 与 lustoykov——仅作视觉参考并注明出处；全部步骤文字为本站原创。
一步一步给 Gemini CLI 上沙箱
启动你的第一个沙箱会话
- 1
先搞清楚沙箱到底隔离什么
沙箱把 AI agent 最容易出事的操作——shell 命令、文件写入、网络访问——与你的主机系统隔离开。Gemini CLI v0.61.0（2026 年 9 月 23 日）加固了沙箱的文件系统边界并隔离了运行时状态，堵上了经由构建文件和不可信参数的间接提示注入通道。
沙箱的位置：每个平台各选一个操作系统级隔离库。在 140:00 观看 - 2
用参数直接进入沙箱启动
最快的方式是命令行参数：运行 gemini -s（完整形式 --sandbox）。首次启动可能要等一会儿，因为沙箱镜像需要拉取。单次任务可以直接带提示词：gemini -s -p "analyze the code structure"。
参数开启、底部标识出现——两秒钟的完整性检查。在 140:50 观看 - 3
弄清三种启用方式，以及谁优先
Gemini CLI 按优先级解析沙箱配置：先是 -s / --sandbox 命令行参数，其次是 GEMINI_SANDBOX 环境变量（可选 true、docker、podman、sandbox-exec、runsc、lxc），最后是 settings.json 中 tools 对象里的 "sandbox" 条目。
官方文档按优先级列出了全部三种启用方式。在 145:45 观看 - 4
在底部状态栏确认会话已沙箱
CLI 启动后，状态栏会出现带版本号的沙箱标识，紧挨着模型选择器。没有标识就意味着沙箱没开——回头检查你以为是启用开关的那个参数或配置。
一个真实的沙箱会话：标识就在 Auto (Gemini 3) 旁边。在 146:40 观看
按操作系统挑对后端
- 5
macOS：直接用内置的 Seatbelt
macOS 不需要容器：Gemini CLI 会用 Seatbelt（sandbox-exec）包裹进程。默认配置文件 permissive-open 把写入限制在项目目录内，读取和网络保持开放。需要更严格的安全姿态时，用 SEATBELT_PROFILE 环境变量切换：permissive-proxied、restrictive-open、restrictive-proxied、strict-open、strict-proxied。
- 6
Linux / WSL2：认识 gVisor runsc
Google 的 gVisor（即 runsc 运行时）提供目前最强的隔离：容器跑在一个用户态内核上，所有系统调用都会被拦截。用 GEMINI_SANDBOX=runsc 或 "sandbox": "runsc" 显式选择（它永远不会被自动探测），Gemini CLI 会替你执行 docker run --runtime=runsc。
官方文档把 runsc 定位为最强、仅限 Linux 的后端。在 141:20 观看 - 7
安装 runsc 运行时
在 Ubuntu（原生或 WSL2 内）只需一条 apt 命令即可装上 gVisor 运行时：sudo apt get install runsc。Docker 也要提前装好并保持运行，因为 Gemini CLI 是把 runsc 当作 Docker 运行时来驱动，而不是独立工具。
在 WSL2 Ubuntu 终端里输入安装命令。在 143:35 观看 - 8
确认安装到位
apt 会直接从 Ubuntu 的安全更新仓库解包 runsc，不需要额外的 PPA。跳过这一步的话，Linux 上之后的 gemini -s 要么失败、要么悄悄回落到容器后端——所以第一次沙箱运行前先确认包已就位。
apt 在 Ubuntu 24.04 上完成 runsc 的解包。在 144:15 观看 - 9
偏好容器？任何系统都能用 Docker 或 Podman
基于容器的沙箱在哪台机器都能跑，只要 Docker 或 Podman 已安装且正在运行——先运行一次 docker 确认命令行有响应。沙箱默认使用 ghcr.io/google/gemini-cli:latest 镜像，并把你的工作目录按完全相同的绝对路径挂载进容器。
先跑一次 docker，确认引擎有响应。在 145:30 观看
安心跑 YOLO 模式
- 10
让沙箱给 YOLO 模式护航
gemini --yolo（--approval-mode=yolo 的简写）会危险地跳过所有权限确认——这正是自动化运行需要的，也正是沙箱存在的意义。用沙箱参数启动 YOLO 会话，被跳过的确认就仍然落在隔离环境里。
一页看懂 YOLO 模式：零打断，全部权限直接放行。在 148:20 观看 - 11
核实自动化运行确实在沙箱里
YOLO 会话期间，状态栏会亮起蓝色的 YOLO Mode 徽标——这是在提醒你确认已被跳过。运行结束后，/stats 交互摘要会显示哪些工具被调用过，而沙箱标识始终是“工作发生在盒子之内”的凭证。
一次自动化会话结束后，状态栏里的 YOLO Mode 徽标。在 147:40 观看
自定义沙箱镜像与容器参数
默认容器镜像应付常规编码绰绰有余。当项目需要自己的工具链，或者容器环境跟你较劲时，Gemini CLI 给了你四个旋钮。
- 1指向任意镜像：设置 GEMINI_SANDBOX_IMAGE，或在 settings.json 里用对象写法——"sandbox": "command": "docker", "image": "..." (a JSON object)。任何带 bash 的 Docker / Podman 镜像都可以。
- 2自己构建：在项目根目录放一个 .gemini/sandbox.Dockerfile，再以 BUILD_SANDBOX=1 运行，Gemini CLI 会自动构建镜像。注意自动构建只在从源码运行 CLI 时可用；npm 安装的版本应引用预构建镜像。
- 3微调容器命令：SANDBOX_FLAGS 可以注入额外的 docker/podman 参数——比如 export SANDBOX_FLAGS="--security-opt label=disable" 可解决 Podman 上 SELinux 拒绝卷挂载的问题。
- 4修正 Linux 文件归属：沙箱会自动映射用户权限，但当生成的文件属主不对时，用 SANDBOX_SET_UID_GID=true 强制沿用主机的 UID/GID。
如果 Gemini CLI 本身就跑在容器里、还想再套沙箱：把 /var/run/docker.sock 挂进去，让 CLI 能通过宿主机守护进程拉起兄弟容器；同时让工作区路径与宿主机绝对路径完全一致——解析卷挂载的是宿主机守护进程，不是容器。
故障排查：报错、文件访问与关闭方法
绝大多数沙箱问题都能归入下面五种模式。动手之前先带上调试输出复现：DEBUG=1 gemini -s -p "your prompt"。
- 1“Operation not permitted”——命令需要沙箱之外的访问权限。换成更宽松的配置文件（macOS：SEATBELT_PROFILE），或者补上所需的挂载点。
- 2沙箱里缺命令——把工具烧进自定义镜像，或通过 sandbox.bashrc 安装。记住 BUILD_SANDBOX 自动构建只支持源码检出。
- 3网络不通——先确认当前配置文件是否允许联网，再核对代理设置；带 -proxied 的配置会把流量经沙箱代理转发。
- 4Linux 上生成的文件属主不对——切换 SANDBOX_SET_UID_GID（true 强制沿用主机 UID/GID，false 关闭映射）。
- 5Windows 上文件被标成 Low 完整级——原生沙箱用 icacls 标记可写路径；用 icacls "C:\path\to\dir" /setintegritylevel Medium 恢复。
想知道沙箱能看到什么，直接问 CLI：gemini -s -p "run shell command: env | grep SANDBOX" 列出沙箱环境变量，mount | grep workspace 显示挂载。文件不需要导出步骤——容器沙箱把项目按相同绝对路径挂载，改动直接落进你的目录。要关闭：去掉 -s 参数、unset GEMINI_SANDBOX，或删除 settings.json 里的 "sandbox" 条目；工具级沙箱另有开关，"security": "toolSandboxing": false（需要重启 CLI）。