---
title: "Shell 工具"
description: "Gemini CLI Shell 工具的使用邊界：執行測試、構建、Git、後臺程序、確認提示、sandbox 和危險命令。"
verifiedAt: "2026-05-09"
---

Shell 工具讓 Gemini CLI 能跑測試、構建、指令碼和 Git 命令。它是最有用也最危險的工具之一。

> [!WARNING]
> Shell 工具一旦授權過寬，風險會從“回答錯”變成“真實執行錯”。

官方工具名是 `run_shell_command`。在 Windows 上透過 `cmd.exe /c` 執行，在 macOS / Linux 上透過 `bash -c` 執行。返回結果會包含 command、directory、stdout、stderr、error、exit code、signal，以及後臺程序 PID。

## 適合執行

- `git status`
- `npm test`
- `pnpm run build`
- `pytest`
- `rg "keyword"`
- 專案已有隻讀診斷指令碼

## 謹慎執行

- `rm`
- `mv`
- `chmod`
- 資料庫遷移。
- 部署指令碼。
- 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

```text
先列出你准备执行的命令、原因和风险。不要直接运行。
```

後臺程序要額外約束：

```text
如果需要启动 dev server，请说明端口、退出方式和任务结束后是否保留进程。
```

長任務裡不要讓 Shell 工具無限重試。失敗後應先分析 stderr、環境、依賴和路徑，再決定下一條命令。

## 失敗處理邊界

Shell 失敗時，先判斷失敗型別：

- 命令不存在：檢查專案指令碼、PATH 和執行環境。
- 許可權不足：確認是否應該提升許可權，不要預設加 `sudo`。
- 測試失敗：讀失敗用例，不要直接改實現。
- 網路失敗：區分臨時網路、代理、認證和服務端錯誤。
- 目錄錯誤：重新確認 cwd，而不是在多個目錄裡盲跑。

真正危險的是“為了讓命令過而改命令”。例如跳過測試、加 `--force`、刪除 lockfile、清空快取、擴大許可權，都必須單獨解釋風險並等待確認。

## 驗收方式

每條命令都看三件事：執行目錄是否正確，exit code 是否為 0，stderr 是否包含真實錯誤。啟動 dev server、watcher 或後臺任務後，還要記錄 PID 或埠，任務結束時明確是否需要保留。

## 接下來去哪

<Cards>
  <Card title="Web 工具" description="繼續看 google_web_search 和 web_fetch 的來源核驗邊界。" href="/zh-Hant/docs/gemini-cli/official/03-tools-mcp/33-web-tools" />
  <Card title="Sandbox" description="命令執行需要和 sandbox、approval、policy 一起控制。" href="/zh-Hant/docs/gemini-cli/official/06-security-enterprise/60-sandbox" />
  <Card title="Automation" description="把 shell 放進自動化前，繼續看 headless 和 CI 邊界。" href="/zh-Hant/docs/gemini-cli/official/07-integrations-automation/73-automation" />
</Cards>

## 官方來源

- [Google Developers Gemini CLI](https://developers.google.com/gemini-code-assist/docs/gemini-cli?hl=zh-cn)
- [Gemini CLI GitHub](https://github.com/google-gemini/gemini-cli)
