Terminal Tool
基於 Cursor 官方 Terminal 文件解釋 Agent 執行 shell commands、sandbox、allowlist、平臺要求和 sandbox.json。
📖 本篇術語速查表
| 英文 / 縮寫 | 中文 | 一句話解釋 |
|---|---|---|
| Terminal Tool | 終端工具 | Agent 在終端執行命令的能力。 |
| 命令審批 | approval | 高危命令需人工確認。 |
| 範圍限制 | scope | 限定能跑哪些命令。 |
不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你安全地用 Cursor 的終端工具（限命令、審批高危）。
你是 Cursor 終端工具使用顧問，幫我安全地用終端工具，限好命令範圍、管住高危操作。
【角色】
你清楚終端工具能做什麼、風險在哪、怎麼限範圍、哪些命令必須審批。
【輸入】
- 我想讓它在終端做什麼：___
- 涉及哪些命令：___
- 是否有刪除 / 網路 / 部署等高危：___
- 執行環境：___
【工作流程】
1. 判斷這些命令該不該交給終端工具
2. 限定可執行範圍
3. 標出必須審批或禁止的命令
4. 給驗證和兜底
【輸出規範】
▌一、命令是否適合交給終端
▌二、可執行範圍限定
▌三、必須審批 / 禁止的命令
▌四、驗證與兜底
【硬約束】
- 刪除、force push、聯網下載等高危預設審批
- 命令範圍最小必要
- 命令輸出視為不可信
- 改動可回復
- 不確定的命令先讓我確認
- 給的方案具體可執行
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述Terminal Tool 是 Agent 最有用、也最需要謹慎的能力。官方文件說明，Agent 可以直接在你的 terminal 中執行 shell commands，並在 macOS、Linux、Windows 上用 sandbox（沙箱，限制程序能訪問的檔案和網路範圍）做安全執行。
閱讀目標：讀完本章，你應該能判斷哪些命令可以讓 Agent 執行，哪些必須人工確認，以及 sandbox 失敗時怎麼處理。
1. 預設 sandbox 心智模型
官方 Terminal 文件說明，Agent 預設在 restricted environment 中執行 terminal commands，阻止未授權檔案訪問和網路活動。命令可以自動執行，但會被限制在 workspace 內。
| 訪問型別 | 官方說明 |
|---|---|
| File access | 允許讀取檔案系統；允許讀寫 workspace 目錄 |
| Network access | 預設阻止，可透過 sandbox.json 或設定設定 |
| Temporary files | 允許訪問 /tmp/ 或系統臨時目錄 |
.cursor 目錄 | 無論 allowlist 如何，都保持受保護 |
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 = 白名單，明確允許的命令清單） |
建議順序：
- 先看命令要做什麼。
- 如果只是誤選命令，選 Skip。
- 如果確實需要一次性系統訪問，選 Run。
- 只有低風險、重複、可解釋命令才加入 allowlist。
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_UIDCURSOR_ORIG_GID
官方給出的 Docker 模式是優先讀這些變數，再 fallback 到 id -u / id -g。
深讀：為什麼 terminal output 也要作為驗收證據
Agent 執行 terminal 命令後，真正有價值的不是“命令跑過”，而是命令輸出證明了什麼。測試透過、型別檢查失敗、構建缺依賴、sandbox 攔截、網路被拒，這些輸出都應該進入任務判斷。
所以讓 Agent 跑命令時，要要求它保留關鍵輸出、解釋失敗層級，並給最小下一步。不要讓它在錯誤上無限重試。
本章自檢
完成本章後，用這 3 個問題檢查自己是否真正理解：
- Cursor Terminal sandbox 預設限制哪些訪問？
Run和Add to allowlist的風險差異是什麼？- Linux 下為什麼 Docker 指令碼可能需要
CURSOR_ORIG_UID和CURSOR_ORIG_GID？
透過標準：你能審查 Agent 準備執行的一條 shell command，並判斷是否 Skip、Run、Add to allowlist 或要求改命令。
官方來源
- Cursor Terminal Tool —— 官方說明 terminal sandbox、平臺要求、allowlist、sandbox.json、環境變數和 Docker 注意點。
- Cursor Terminal Help —— Help Center terminal 功能入口。