---
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="/docs/cursor/official/01-agent-workflow/17-browser-tool" />
  <Card title="Agent Security" description="把 terminal sandbox 和 Cursor 安全 guardrails 放到同一张图里。" href="/docs/cursor/official/01-agent-workflow/21-agent-security" />
</Cards>
