Gemini CLI 的沙箱機制

# 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
{
  "tools": {
    "sandbox": "docker"
  }
}

設定

啟用沙箱機制（依優先順序）

命令旗標 (flags)：-s 或 --sandbox
環境變數：GEMINI_SANDBOX=true|docker|podman|sandbox-exec
設定檔：在你的 settings.json 檔案中的 tools 物件下設定 "sandbox": true（例如：{"tools": {"sandbox": true}}）。

macOS Seatbelt profiles

內建 profiles（可透過 SEATBELT_PROFILE 環境變數設定）：

permissive-open（預設）：限制寫入，允許網路
permissive-closed：限制寫入，不允許網路
permissive-proxied：限制寫入，僅允許透過 proxy 的網路
restrictive-open：嚴格限制，允許網路
restrictive-closed：最大限制

自訂沙箱旗標 (flags)

針對基於容器的沙箱機制，你可以透過 SANDBOX_FLAGS 環境變數，將自訂旗標 (flags) 注入到 docker 或 podman 指令中。這對於進階設定很有用，例如針對特定情境停用某些安全功能。

範例（Podman）：

若要在掛載 volume 時停用 SELinux 標記，可以這樣設定：

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

可以將多個旗標 (flags) 以空格分隔的字串方式提供：

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

Linux UID/GID 處理

sandbox 會自動處理 Linux 上的使用者權限。你可以透過以下方式覆寫這些權限：

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

疑難排解

常見問題

"Operation not permitted"（不允許的操作）

操作需要存取 sandbox 容器外部的資源。
請嘗試使用更寬鬆的設定檔（profile）或新增掛載點（mount points）。

缺少指令

請加入自訂的 Dockerfile。
可透過 sandbox.bashrc 安裝。

網路相關問題

請確認 sandbox 設定檔允許網路存取。
檢查 proxy（代理伺服器）設定是否正確。

除錯模式

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

注意： 如果你在專案的 .env 檔案中有 DEBUG=true，由於會自動排除，這不會影響 Gemini CLI。請使用 .gemini/.env 檔案來設定 Gemini CLI 專屬的除錯設定。

檢查 sandbox

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

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

安全性注意事項

沙箱機制（sandboxing）能降低但無法完全消除所有風險。
請使用允許您工作所需的最嚴格設定檔（profile）。
在首次建置後，sandbox 容器的額外負擔極小。
GUI 應用程式在沙箱機制下可能無法運作。