---
title: "Shell Mode"
description: "基於 Cursor 官方 Shell Mode 文件解釋命令執行、輸出截斷、30 秒超時、許可權審批、適用場景和排障方式。"
verifiedAt: "2026-05-09"
---

Shell Mode 讓你在 Cursor CLI 會話中直接執行 shell 命令，並把輸出帶回對話。它適合短命令，不適合長期服務、互動式程式或需要人工輸入的流程。

> [!NOTE]
> **閱讀目標**：讀完本章，你應該能判斷什麼命令適合 Shell Mode，為什麼 `cd` 不會跨命令保留，以及如何處理超時、截斷和許可權審批。

## 1. Shell Mode 的定位

Shell Mode 解決的是“對話中快速跑一個命令”。它不是完整終端替代品。

| 適合 | 不適合 |
| --- | --- |
| `git status`、`npm test -- --runInBand`、`ls`、`pwd` | 長時間執行的 dev server |
| 環境檢查、檔案檢視、短構建 | `vim`、`top`、互動式 prompts |
| 一次性目錄內命令 | 需要持續保持 shell state 的流程 |
| 需要把輸出給 Agent 分析的命令 | 會輸出大量日誌且無法收斂的命令 |

一個商業級判斷：命令能在 30 秒內結束、無需輸入、輸出可解釋，就適合 Shell Mode。

## 2. 命令如何執行

官方文件說明，命令會在你的 login shell 中執行，使用 CLI 當前 working directory 和 environment。

```bash
pwd
git status --short
```

每條命令彼此獨立。`cd` 不會保留到下一次執行，所以要用鏈式命令進入目錄：

```bash
cd packages/web && npm test
```

這點很容易誤判。你在上一條命令裡 `cd subdir`，下一條不會自動留在 `subdir`。

## 3. 輸出和超時

Shell Mode 有兩條重要限制：

| 限制 | 官方行為 | 實戰處理 |
| --- | --- | --- |
| 大輸出 | 自動截斷 | 縮小命令範圍，必要時用 Ctrl+O 展開 |
| 長命令 | 30 秒超時 | 用短測試、focused build 或指令碼外部執行 |

示例：

```bash
# 更适合 Shell Mode
npm test -- checkout.test.ts

# 不适合 Shell Mode
npm run dev
```

如果你需要啟動伺服器、持續 tail 日誌或等待互動輸入，應該回到真實終端，不要硬塞進 Shell Mode。

## 4. 許可權和團隊策略

命令執行前會受 CLI permissions 和 team settings 檢查。管理員策略可能阻止某些命令。

```mermaid
flowchart TD
  Cmd["Shell command"] --> Policy["CLI permissions + team settings"]
  Policy --> Allowed["Allowed"]
  Policy --> Prompt["Permission prompt"]
  Policy --> Blocked["Blocked by policy"]
  Prompt --> Once["Approve once"]
  Prompt --> Allowlist["Allowlist with Tab"]
  Prompt --> Reject["Reject"]
```

官方還提醒：帶 redirection 的命令不能 inline allowlist。也就是說，涉及 `>`、`>>` 這類重定向時，不要假設可以順手加入允許列表。

商業級團隊策略通常這樣定：

- 預設允許只讀狀態檢查命令。
- 對寫檔案、刪檔案、網路下載、許可權變更命令單獨審批。
- 對 `sudo`、刪除、全域性安裝、憑據讀取類命令預設阻止。
- 允許列表只收穩定、可解釋、低風險的命令。

## 5. 推薦用法

狀態檢查：

```bash
git status --short
git diff --stat
```

短測試：

```bash
npm test -- auth.test.ts
pnpm lint
```

環境檢查：

```bash
node --version
which agent
echo "$SHELL"
```

跨目錄執行：

```bash
cd apps/docs && pnpm build
```

不要把 Shell Mode 當作“萬能 bash”。它更像 Agent loop 裡的短命令工具。

## 6. 排障方式

命令卡住：

- 用 `Ctrl+C` 取消。
- 增加 non-interactive flags。
- 避免啟動 server、watch mode、interactive prompt。

輸出被截斷：

- 用 `Ctrl+O` 展開。
- 改成更小範圍命令。
- 讓命令輸出摘要，而不是全量日誌。

目錄不對：

- 每次用 `pwd` 確認。
- 用 `cd <dir> && ...` 寫成單條命令。

許可權彈出視窗頻繁：

- 先判斷命令是否真的應該被允許。
- 低風險命令可用 Tab 加入 allowlist。
- 高風險命令不要為省事加入 allowlist。

<details>
<summary>深讀：為什麼 Shell Mode 不適合跑 dev server</summary>

dev server 的價值是持續執行，但 Shell Mode 的設計是短命令執行。把 server 放進 Shell Mode，會碰到超時、輸出截斷、埠占用和無法互動關閉的問題。

更穩的做法是：在真實終端啟動 server，在 Cursor CLI 裡只執行短驗證命令，例如 `curl`、focused test、lint 或讀取日誌片段。
</details>

## 本章自檢

完成本章後，用這 3 個問題檢查自己是否真正理解：

1. 為什麼 `cd subdir` 不會影響下一條 Shell Mode 命令？
2. 哪些命令應該回到真實終端執行，而不是放進 Shell Mode？
3. 為什麼帶重定向的命令不能按普通命令加入 inline allowlist？

透過標準：你能寫出一組團隊 Shell Mode allowlist，並解釋每條命令的風險等級和驗收用途。

## 官方來源

- [Cursor Shell Mode](https://cursor.com/docs/cli/shell-mode.md) —— 官方說明命令執行、輸出截斷、30 秒超時、許可權、使用建議、排障和 FAQ。
- [Cursor CLI Permissions](https://cursor.com/docs/cli/reference/permissions.md) —— 官方 CLI permissions 配置入口。
- [Using Agent in CLI](https://cursor.com/docs/cli/using.md) —— 官方 CLI command approval 和工作流上下文。

## 接下來去哪

<Cards>
  <Card title="Agent Client Protocol" description="繼續學習透過 stdio JSON-RPC 把 Cursor Agent 接進自定義客戶端。" href="/zh-Hant/docs/cursor/official/03-cli-automation/34-acp" />
  <Card title="CLI 使用方式" description="回到 modes、review、context 和 worktree 的完整使用鏈路。" href="/zh-Hant/docs/cursor/official/03-cli-automation/32-cli-using" />
</Cards>
