Shell 工具
Gemini CLI Shell 工具的使用邊界：執行測試、構建、Git、後臺程序、確認提示、sandbox 和危險命令。
Shell 工具讓 Gemini CLI 能跑測試、構建、指令碼和 Git 命令。它是最有用也最危險的工具之一。
Shell 工具一旦授權過寬，風險會從“回答錯”變成“真實執行錯”。
官方工具名是 run_shell_command。在 Windows 上透過 cmd.exe /c 執行，在 macOS / Linux 上透過 bash -c 執行。返回結果會包含 command、directory、stdout、stderr、error、exit code、signal，以及後臺程序 PID。
適合執行
git statusnpm testpnpm run buildpytestrg "keyword"- 專案已有隻讀診斷指令碼
謹慎執行
rmmvchmod- 資料庫遷移。
- 部署指令碼。
- Git push / release。
- 任何帶 token 的命令。
| 命令型別 | 預設策略 | 說明 |
|---|---|---|
| 只讀診斷 | 可執行但要看目錄 | git status、rg、ls |
| 測試 / 構建 | 可執行 | 要記錄失敗原因和 exit code |
| 安裝依賴 | 謹慎 | 可能改 lockfile 或下載大量包 |
| 刪除 / 移動 | 高風險 | 必須人工確認具體路徑 |
| 釋出 / push / 部署 | 高風險 | 不應讓模型連續試錯 |
配置項
Shell 工具可以透過 settings.json 調整：
tools.shell.enableInteractiveShell：啟用互動式 shell，適合需要 pty 的命令。tools.shell.showColor：保留彩色輸出，通常依賴 interactive shell。tools.shell.pager：設定輸出 pager，預設類似cat。tools.shell.inactivityTimeout：長時間無輸出時終止程序。
互動式 shell 能跑 vim、nano、htop、git rebase -i 這類命令，但也更容易讓 session 卡住。教程和新手任務裡，優先使用非互動命令。
命令如果以 & 結尾，可以啟動後臺程序。教程裡啟動 dev server 時，要要求 agent 記錄埠、PID 和停止方式；不要讓後臺程序默默留在系統裡。
Policy 控制
不要用 prompt 管 shell 許可權。官方更推薦用 policy engine。針對 shell，可以用 commandPrefix 或 commandRegex 寫規則，例如讓 git 需要確認，讓 rm -rf 直接拒絕。
tools.core 是所有內建工具的 allowlist，不只是 shell。誤設 tools.core 可能連 read_file、glob、replace 這類工具一起禁掉，所以團隊配置前要單獨測試。
也可以用 tools.exclude 做 blocklist，但官方文件提醒命令級字串匹配不是安全邊界，命令鏈和 shell 包裝容易繞過。企業或團隊教程裡，優先展示 allowlist 和 policy，而不是展示一堆看似完整的停用命令。
Gemini CLI 執行 shell 時會設定 GEMINI_CLI=1。指令碼可以利用這個環境變數識別是否由 CLI 啟動，但不要因此降低安全校驗。
推薦 prompt
先列出你准备执行的命令、原因和风险。不要直接运行。後臺程序要額外約束：
如果需要启动 dev server，请说明端口、退出方式和任务结束后是否保留进程。長任務裡不要讓 Shell 工具無限重試。失敗後應先分析 stderr、環境、依賴和路徑，再決定下一條命令。
失敗處理邊界
Shell 失敗時，先判斷失敗型別：
- 命令不存在：檢查專案指令碼、PATH 和執行環境。
- 許可權不足：確認是否應該提升許可權，不要預設加
sudo。 - 測試失敗：讀失敗用例，不要直接改實現。
- 網路失敗：區分臨時網路、代理、認證和服務端錯誤。
- 目錄錯誤：重新確認 cwd，而不是在多個目錄裡盲跑。
真正危險的是“為了讓命令過而改命令”。例如跳過測試、加 --force、刪除 lockfile、清空快取、擴大許可權，都必須單獨解釋風險並等待確認。
驗收方式
每條命令都看三件事：執行目錄是否正確，exit code 是否為 0，stderr 是否包含真實錯誤。啟動 dev server、watcher 或後臺任務後，還要記錄 PID 或埠，任務結束時明確是否需要保留。
接下來去哪
Web 工具
繼續看 google_web_search 和 web_fetch 的來源核驗邊界。
Sandbox
命令執行需要和 sandbox、approval、policy 一起控制。
Automation
把 shell 放進自動化前，繼續看 headless 和 CI 邊界。