---
title: "Shell 命令"
description: "Gemini CLI Shell 命令使用方式：! 字首、Shell mode、執行測試、後臺程序、確認提示和 sandbox。"
verifiedAt: "2026-05-09"
---

Gemini CLI 可以執行 Shell 命令。這個能力讓它能跑測試、構建、Git、指令碼和系統任務，也帶來最直接的風險。你要把 shell 當成真實終端，不要當成“AI 沙盒裡的玩具命令”。

> [!WARNING]
> **Shell 是高風險能力**：凡是刪除、覆蓋、釋出、部署、改許可權、動金鑰、動生產資料，都必須人工確認。

## 1. 直接執行命令

```text
!ls -la
!git status
!npm test
```

`!` 會把命令直接交給 shell 執行，並把輸出記錄到當前 session 上下文。

官方 commands reference 說明，`!` 命令在 Linux/macOS 上走 shell，在 Windows 上走 PowerShell 相關執行路徑；執行時還會設定 `GEMINI_CLI=1`，方便指令碼識別它是在 Gemini CLI 內部執行。

Shell tool 的返回會包含命令、目錄、stdout、stderr、error、exit code、signal 和後臺 PID。教程裡不要只看自然語言總結；排錯時先看 exit code 和 stderr，再判斷是否需要改程式碼。

## 2. Shell mode

如果連續執行很多命令，可以輸入 `!` 後Enter進入 Shell mode。之後輸入會直接傳送到 shell，直到你退出。

這個模式適合手動排查，不適合交給 agent 長時間失控執行。

## 3. 讓 Gemini 跑測試並修復

```text
Run the unit tests. If any fail, analyze the error and propose a fix before editing.
```

推薦要求它先提出修復計劃，再授權編輯。不要讓它在失敗後無限迴圈嘗試。

一個合格的測試任務應該包含停止條件：

- 最多執行哪些命令。
- 失敗後先分析，不自動連續改。
- 修改前先列出要改的檔案。
- 修改後只跑最小驗證。
- 如果測試依賴外部服務，先說明依賴。

## 4. 後臺程序

Gemini CLI 可以啟動 dev server 或 watcher。檢視後臺程序可用：

```text
/shells
```

如果服務跑飛，應及時檢視日誌並停止。

> [!IMPORTANT]
> **後臺程序要收尾**：啟動 dev server、watcher、資料庫、本地佇列或瀏覽器除錯程序後，要記錄埠和用途。任務結束前確認是否保留，不要讓後臺程序長期佔埠。

## 5. sandbox

官方 shell tutorial 建議處理不可信程式碼或新專案時啟用 sandbox：

```bash
gemini --sandbox
```

sandbox 能降低風險，但不能替代人工判斷。

官方 sandbox 文件也提醒：sandbox 減少風險，不消除風險。新專案、下載程式碼和不可信指令碼可以先開 sandbox，但刪除、釋出、資料庫遷移這類動作仍然需要人工確認。

## 6. 命令風險分級

| 命令型別 | 例子 | 預設策略 |
| --- | --- | --- |
| 只讀狀態 | `git status`、`pwd`、`ls` | 可以低風險執行 |
| 專案驗證 | `npm test`、`pnpm typecheck` | 先確認目錄和耗時 |
| 寫入生成 | formatter、codegen、build cache | 先說明生成物和 diff |
| 外部影響 | deploy、database migration、cloud CLI | 必須人工確認 |
| 破壞性命令 | delete、reset、permission change | 預設拒絕，除非明確授權 |

## 7. 命令驗收

讓 Gemini CLI 執行 shell 前，檢查三件事：命令是否在正確目錄，是否只讀或低風險，失敗後是否有停止條件。執行後要求它總結退出碼、關鍵輸出和下一步，而不是把長日誌原樣甩給使用者。

涉及後臺 dev server 時，記錄埠和 session，任務結束前確認是否還需要保留程序。CI、釋出、部署、刪除檔案這類命令，不應讓模型自己連續試錯。

如果命令失敗，不要馬上讓 Gemini CLI 改實現。先讓它解釋失敗來自命令不存在、依賴缺失、許可權問題、測試斷言、網路問題還是目錄錯誤。分類清楚後再決定下一步。

## 8. 接下來去哪

<Cards>
  <Card title="Web search / fetch" description="繼續看聯網查資料、讀取 URL 和官方事實核驗邊界。" href="/zh-Hant/docs/gemini-cli/official/01-cli-workflow/15-web-search-fetch" />
  <Card title="Sandbox" description="繼續看 sandbox、approval mode、folder trust 和 policy 的安全組合。" href="/zh-Hant/docs/gemini-cli/official/06-security-enterprise/60-sandbox" />
  <Card title="Shell tool" description="需要更細工具語義時，繼續看官方 shell tool reference。" href="/zh-Hant/docs/gemini-cli/official/03-tools-mcp/32-shell-tool" />
</Cards>

## 官方來源

- [Gemini CLI shell commands tutorial](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/tutorials/shell-commands.md)
- [Gemini CLI shell tool](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/shell.md)
- [Gemini CLI Commands Reference](https://github.com/google-gemini/gemini-cli/blob/main/docs/reference/commands.md)
