---
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="/docs/cursor/official/03-cli-automation/34-acp" />
  <Card title="CLI 使用方式" description="回到 modes、review、context 和 worktree 的完整使用链路。" href="/docs/cursor/official/03-cli-automation/32-cli-using" />
</Cards>
