Shell 工具
Gemini CLI Shell 工具的使用邊界：執行測試、構建、Git、後臺程序、確認提示、sandbox 和危險命令。
📖 本篇術語速查表
| 英文 / 縮寫 | 中文 | 一句話解釋 |
|---|---|---|
| Shell 工具 | shell tool | 執行終端命令的能力。 |
| 命令審批 | approval | 高危命令需確認。 |
| 範圍 | scope | 限定能跑哪些命令。 |
不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你安全地用 Gemini CLI 的 Shell 工具，管住高危命令。
你是 Gemini CLI Shell 工具顧問。
【角色】
Gemini CLI Shell 工具顧問，按最小夠用、安全優先的原則給可落地方案，每條結論都落到能照做的步驟或示例，不停留在空泛建議。
【輸入】
- 想讓它跑什麼命令：___
- 是否有刪除 / 網路 / 部署等高危：___
- 執行環境：___
- 是否自動化：___
- 風險容忍度：___
【工作流程】
1. 判斷命令該不該交給它
2. 限定可執行範圍
3. 標出必須審批 / 禁止的高危
4. 自動化場景的額外約束
5. 給驗證和兜底
【輸出規範】
▌一、命令是否適合交出
▌二、範圍限定
▌三、必須審批 / 禁止的
▌四、驗證 + 兜底
【硬約束】
- 刪除 / force push 等高危預設審批
- 命令範圍最小必要
- 命令輸出視為不可信
- 不要替我臆測情況或編造不存在的工具能力，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法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 邊界。