---
title: "Sandbox"
description: "Gemini CLI sandbox 的用途：隔離工具執行、降低不可信程式碼風險、Docker sandbox 和 --sandbox 使用邊界。"
verifiedAt: "2026-05-09"
---

Sandbox 用來隔離工具執行，尤其適合不可信程式碼、新專案、陌生儲存庫和可能有副作用的命令。

> [!WARNING]
> Sandbox 降低本機執行風險，但不能替你判斷命令是否應該訪問遠端服務、賬號、賬單或生產資料。

```bash
gemini --sandbox
```

也可以用短引數 `-s`，或者透過環境變數 `GEMINI_SANDBOX` 和 `settings.json` 固化配置。實際優先順序是：命令列引數最高，其次是環境變數，最後是配置檔案。

官方頁面給出的環境變數形式包括 `GEMINI_SANDBOX=true`、`docker`、`podman`、`sandbox-exec`。`settings.json` 裡則放在 `tools.sandbox`。教程裡要把命令列臨時啟用和配置檔案長期啟用分開寫。

## 適合場景

- 下載來的陌生程式碼。
- 需要跑未知指令碼。
- 需要探索依賴和測試。
- 想降低檔案系統副作用。

## 支援方式

官方文件把 sandbox 分成幾類：

- macOS Seatbelt：macOS 內建，輕量，適合限制專案外寫入。
- Docker / Podman：跨平臺容器隔離，適合需要完整程序隔離的專案。
- Windows native sandbox：使用 Windows 許可權機制，注意完整性級別可能持久化。
- gVisor / runsc：Linux 上更強隔離，適合高風險命令。
- LXC / LXD：實驗能力，適合標準 Docker 不適配的完整系統容器。

macOS Seatbelt 常見 profile 包括 `permissive-open`、`permissive-closed`、`permissive-proxied`、`restrictive-open`、`restrictive-closed`，可用 `SEATBELT_PROFILE` 指定。預設 profile 不等於最嚴格 profile，真實專案要按風險選擇。

選擇方式時先看你的平臺，再看風險級別。普通本地探索可以從預設 sandbox 開始；陌生儲存庫、未知指令碼或供應鏈風險更高時，優先使用容器隔離。

| 風險場景 | 推薦控制 |
| --- | --- |
| 陌生儲存庫跑測試 | 開 sandbox，先只讀掃描 |
| 需要安裝依賴 | 容器 sandbox，確認網路和快取 |
| 可能寫專案外路徑 | sandbox + policy 雙重限制 |
| 涉及生產憑據 | 不注入 sandbox，單獨人工確認 |
| 需要部署 / 刪除遠端資源 | sandbox 不足夠，必須審批和回復方案 |

## 使用前檢查

- Docker 或 Podman 是否已啟動。
- 當前目錄是否就是要分析的專案根目錄。
- sandbox 內是否能訪問專案需要的依賴、測試命令和包管理器。
- 是否需要網路訪問；如果需要，profile 或容器網路要允許。
- 是否會寫到專案外路徑；sandbox 可能阻斷這類操作。

## 邊界

Sandbox 降低風險，但不是萬能保險。生產金鑰、賬單、部署、資料刪除仍然需要人工確認。

不要在 sandbox 裡注入生產金鑰。sandbox 隔離的是執行環境，不是替你判斷命令是否應該執行。涉及遠端刪除、部署、付款、發訊息、改許可權這類外部副作用時，必須單獨確認。

## 驗收方式

第一次啟用 sandbox 後，不要直接跑複雜任務。先讓 Gemini CLI 執行只讀專案分析，再跑一個最小測試命令。確認檔案寫入、網路訪問和依賴路徑都符合預期後，再擴大任務範圍。

如果需要 Docker sandbox，還要先確認映象來源、網路策略和快取目錄。容器隔離能限制程序環境，但如果你把生產憑據作為環境變數注入進去，風險仍然存在。

## 常見排錯

如果 sandbox 後測試失敗，先判斷失敗是不是隔離導致的：依賴無法訪問、網路被阻斷、寫入專案外路徑失敗、GUI 或瀏覽器無法啟動、快取目錄不可寫。不要為了讓測試透過直接關閉 sandbox。

正確路徑是先收窄任務，再調整 profile 或容器配置。只有確認失敗與隔離無關，才回到程式碼和測試本身。

教程裡要保留關閉 sandbox 的回退說明，但不能把關閉當成預設修復，也不能把它當成安全策略或上線方案。上線前必須複測。

## 接下來去哪

<Cards>
  <Card title="Policy engine" description="sandbox 管執行環境，policy 管工具能不能執行。" href="/zh-Hant/docs/gemini-cli/official/06-security-enterprise/61-policy-engine" />
  <Card title="Shell 工具" description="回看 shell 命令、後臺程序和失敗處理邊界。" href="/zh-Hant/docs/gemini-cli/official/03-tools-mcp/32-shell-tool" />
  <Card title="Trusted folders" description="sandbox 前還要判斷 workspace 是否可信。" href="/zh-Hant/docs/gemini-cli/official/02-context-config/28-trusted-folders" />
</Cards>

## 官方來源

- [Gemini CLI sandboxing](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/sandbox.md)
- [Gemini CLI configuration reference](https://github.com/google-gemini/gemini-cli/blob/main/docs/reference/configuration.md)
