---
title: "Terminal Tool"
description: "基於 Cursor 官方 Terminal 文件解釋 Agent 執行 shell commands、sandbox、allowlist、平臺要求和 sandbox.json。"
verifiedAt: "2026-05-09"
---

Terminal Tool 是 Agent 最有用、也最需要謹慎的能力。官方文件說明，Agent 可以直接在你的 terminal 中執行 shell commands，並在 macOS、Linux、Windows 上用 sandbox（沙箱，限制程序能訪問的檔案和網路範圍）做安全執行。

> [!NOTE]
> **閱讀目標**：讀完本章，你應該能判斷哪些命令可以讓 Agent 執行，哪些必須人工確認，以及 sandbox 失敗時怎麼處理。

## 1. 預設 sandbox 心智模型

官方 Terminal 文件說明，Agent 預設在 restricted environment 中執行 terminal commands，阻止未授權檔案訪問和網路活動。命令可以自動執行，但會被限制在 workspace 內。

| 訪問型別 | 官方說明 |
| --- | --- |
| File access | 允許讀取檔案系統；允許讀寫 workspace 目錄 |
| Network access | 預設阻止，可透過 `sandbox.json` 或設定配置 |
| Temporary files | 允許訪問 `/tmp/` 或系統臨時目錄 |
| `.cursor` 目錄 | 無論 allowlist 如何，都保持受保護 |

```mermaid
flowchart TD
  Command["Agent shell command"] --> Sandbox["Sandbox"]
  Sandbox --> Workspace["Workspace read/write"]
  Sandbox --> Temp["Temp files"]
  Sandbox --> Block["Block unauthorized files / network"]
  Block --> Prompt["Ask user: Skip / Run / Add to allowlist"]
```

## 2. 平臺要求

官方文件列出平臺要求：

| 平臺 | 要求 |
| --- | --- |
| macOS | Cursor v2.0 或更高，開箱即用 |
| Windows | 必須安裝並配置 WSL2，sandbox 在 WSL2 內執行 |
| Linux | Kernel 6.2+ 且支援 Landlock v3（Linux 核心程序級沙箱機制）；啟用 unprivileged user namespaces |

如果 Linux kernel 不滿足要求，Agent 會回退到執行命令前請求 approval。

## 3. Sandbox 失敗時的三種選擇

當 sandboxed command 因限制失敗，官方給出三個選項：

| 選項 | 含義 |
| --- | --- |
| Skip | 取消該命令，讓 Agent 嘗試其他方式 |
| Run | 不帶 sandbox 限制執行這一次 |
| Add to allowlist | 不帶限制執行，並以後自動批准該命令（allowlist = 白名單，明確允許的命令清單）|

建議順序：

1. 先看命令要做什麼。
2. 如果只是誤選命令，選 Skip。
3. 如果確實需要一次性系統訪問，選 Run。
4. 只有低風險、重複、可解釋命令才加入 allowlist。

> [!WARNING]
> `Add to allowlist` 是長期放權。不要把 `rm`、部署、資料庫遷移、上傳、付款、真實後臺操作相關命令加入 allowlist。

## 4. sandbox.json 配置

官方文件說明，可以用 `sandbox.json` 自定義 sandbox 行為：

| 位置 | 範圍 |
| --- | --- |
| `~/.cursor/sandbox.json` | per-user |
| `<workspace>/.cursor/sandbox.json` | per-repo |

可控制 network access、filesystem paths、build caches 等。團隊專案優先用 workspace 配置，並納入 review。

## 5. 環境變數和 Docker 注意點

官方文件說明，Cursor 會向 sandboxed child process 注入環境變數。Linux 下 sandbox 會建立 user namespace，並把程序 UID 對映成 0；如果指令碼或 Docker 需要真實 host user，要使用：

- `CURSOR_ORIG_UID`
- `CURSOR_ORIG_GID`

官方給出的 Docker 模式是優先讀這些變數，再 fallback 到 `id -u` / `id -g`。

<details>
<summary>深讀：為什麼 terminal output 也要作為驗收證據</summary>

Agent 執行 terminal 命令後，真正有價值的不是“命令跑過”，而是命令輸出證明了什麼。測試透過、型別檢查失敗、構建缺依賴、sandbox 攔截、網路被拒，這些輸出都應該進入任務判斷。

所以讓 Agent 跑命令時，要要求它保留關鍵輸出、解釋失敗層級，並給最小下一步。不要讓它在錯誤上無限重試。
</details>

## 本章自檢

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

1. Cursor Terminal sandbox 預設限制哪些訪問？
2. `Run` 和 `Add to allowlist` 的風險差異是什麼？
3. Linux 下為什麼 Docker 指令碼可能需要 `CURSOR_ORIG_UID` 和 `CURSOR_ORIG_GID`？

透過標準：你能審查 Agent 準備執行的一條 shell command，並判斷是否 Skip、Run、Add to allowlist 或要求改命令。

## 官方來源

- [Cursor Terminal Tool](https://cursor.com/docs/agent/tools/terminal.md) —— 官方說明 terminal sandbox、平臺要求、allowlist、sandbox.json、環境變數和 Docker 注意點。
- [Cursor Terminal Help](https://cursor.com/help/ai-features/terminal.md) —— Help Center terminal 功能入口。

## 接下來去哪

<Cards>
  <Card title="Browser Tool" description="繼續理解瀏覽器測試、截圖、console、network 和 approval 設定。" href="/zh-Hant/docs/cursor/official/01-agent-workflow/17-browser-tool" />
  <Card title="Agent Security" description="把 terminal sandbox 和 Cursor 安全 guardrails 放到同一張圖裡。" href="/zh-Hant/docs/cursor/official/01-agent-workflow/21-agent-security" />
</Cards>
