Terminal Tool
基于 Cursor 官方 Terminal 文档解释 Agent 运行 shell commands、sandbox、allowlist、平台要求和 sandbox.json。
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 功能入口。