Cursor CLI 的权限怎么配：允许清单与拒绝清单的优先级

2026-08-18

命令行里跑 agent，最烦的两件事一头一尾：一头是每条 git status 都要按一次 y，一头是某次手滑放行了一条不该跑的命令。Cursor CLI 把这两头交给同一份配置来管——permissions 里的 allow 与 deny。这篇只讲这一处：权限项长什么样、放在哪个文件、多条规则同时命中时谁说了算。

一、这个东西解决什么问题

Cursor 官方文档《Using Agent in CLI》页写明：在运行终端命令之前，CLI 会让你批准（y）或拒绝（n）。默认状态下这就是一条一条问。

权限配置的作用是把「问」这个动作提前固化成规则：把你反复批准的那几条写进 allow，把你绝不希望它碰的写进 deny。官方文档《Permissions》页的原话是「Configure what the agent is allowed to do using permission tokens in your CLI configuration」——注意是 permission tokens，一条规则就是一个字符串令牌，不是一段脚本。

二、前置条件

先确认 CLI 装好了。 官方文档《Installation》页给的验证命令是：

agent --version

安装命令按平台分开写，别混用：

# macOS、Linux 和 Windows (WSL)
curl https://cursor.com/install -fsS | bash

# Windows 原生，PowerShell
irm 'https://cursor.com/install?win32=true' | iex

再确认配置文件放哪。 《Configuration》页给了这张表，Windows 那一行的路径写法和另外两个平台不一样：

类型	平台	路径
全局	macOS/Linux	`~/.cursor/cli-config.json`
全局	Windows	`$env:USERPROFILE\.cursor\cli-config.json`
项目	全平台	`<project>/.cursor/cli.json`

这张表下面紧跟着一句很关键的限制：只有 permissions 可以在项目级配置，其它所有 CLI 设置都必须配在全局。 也就是说 <project>/.cursor/cli.json 这个文件天生就是为权限准备的，你别指望往里塞别的字段。

两个环境变量可以改这个落点：CURSOR_CONFIG_DIR 指定自定义目录；XDG_CONFIG_HOME（Linux/BSD）会让它去读 $XDG_CONFIG_HOME/cursor/cli-config.json。

至于「哪个版本起支持这些字段」，官方文档没有说明这一点。该产品迭代频繁，配置项与命令随版本变动，以官方文档最新内容为准。

三、五类权限令牌，逐个说清在管什么

《Permissions》页把权限项分成五类，格式各不相同。这五类是这一页 Permission types 一节下逐条列出的，不多不少。

Shell(commandBase) —— 管 shell 命令。文档写明 commandBase 是命令行里的第一个 token，支持 glob，也支持可选的 command:args 语法做更细的控制。文档给的例子里，Shell(git) 表示放行任意 git 子命令，Shell(curl:*) 表示允许 curl 带任意参数，Shell(rm) 则被标注为「通常放在 deny 里」。

Read(pathOrGlob) —— 管文件与目录的读取，支持 glob。文档的例子里 Read(src/**/*.ts) 是放行读 src 下的 TypeScript 文件，Read(.env*) 和 Read(/etc/passwd) 则是拒绝侧的例子。

Write(pathOrGlob) —— 管写入。这一段里夹了一句和脚本化直接相关的话：print 模式可以使用 write 和 shell 工具，用 permissions.allow、permissions.deny 和 --force 来控制哪些东西不弹提示就跑。

WebFetch(domainOrPattern) —— 管 web fetch 工具能抓哪些域名。文档写明：没有 allowlist 条目时，每次 fetch 都会提示批准。域名匹配规则文档单独列了三条：* 匹配所有域名；*.example.com 匹配子域名；example.com 只匹配这一个域名本身，不含子域名。

Mcp(server:tool) —— 管 MCP 工具。server 取自 mcp.json，tool 是工具名，两侧都可以用 * 通配。

上面这些具体的域名、路径、命令名都是官方文档里用来讲解语义的示例值，照抄语义即可，别当成推荐清单。

四、怎么写进配置文件

《Permissions》页给的配置形态是这样的（原文示例）：

{
  "permissions": {
    "allow": [
      "Shell(ls)",
      "Shell(git)",
      "Read(src/**/*.ts)",
      "Write(package.json)",
      "WebFetch(docs.github.com)",
      "WebFetch(*.github.com)",
      "Mcp(datadog:*)"
    ],
    "deny": [
      "Shell(rm)",
      "Read(.env*)",
      "Write(**/*.key)",
      "WebFetch(malicious-site.com)"
    ]
  }
}

但《Configuration》页的 Required fields 表里把 version、editor.vimMode、permissions.allow、permissions.deny 四项都列为必填，所以一份完整的全局配置是这个样子（原文的 Minimal config 示例）：

{
  "version": 1,
  "editor": { "vimMode": false },
  "permissions": { "allow": ["Shell(ls)"], "deny": [] }
}

这里有个容易踩的点：《Configuration》页的 Notes 一节写明配置是纯 JSON、不支持注释，权限条目是精确字符串（exact strings）。你想在 allow 列表里写注释说明「这条是给 CI 用的」，只能写在版本管理的提交信息里。

五、匹配优先级：`deny` 赢

《Permissions》页末尾的 Pattern matching 一节是这篇最该记住的部分，五条规则原文照录一遍：

glob 模式使用 **、*、? 通配符
相对路径的作用域限定在当前 workspace
绝对路径可以指向项目之外的文件
deny 规则的优先级高于 allow 规则
用 command:args（例如 curl:*）同时对命令和参数做 glob 匹配

第四条是整套权限模型的地基。它意味着你不需要小心翼翼地把 allow 写得刚好不覆盖危险命令——写宽一点也没关系，只要 deny 里钉死的那几条一定会赢。反过来说也成立：如果你发现某条命令死活跑不起来，先去 deny 里找，别在 allow 里加。

这条优先级还延伸到了命令行参数上。《Parameters》页对 -f, --force 的描述是「Force allow commands unless explicitly denied」——强制放行，除非被显式拒绝。--yolo 是 --force 的别名。也就是说 deny 不会被 --force 掀翻，这是文档白纸黑字写的语义。

配合 headless 场景看会更清楚。《Using Headless CLI》页写明，--print 单用时改动只是被提议、不会落盘；要在脚本里真正改文件，得把 --print 和 --force（或 --yolo）组合起来：

# 官方文档示例：在 print 模式下允许修改文件
agent -p --force "Refactor this code to use modern ES6+ syntax"

# 不加 --force，改动只被提议，不会写入
agent -p "Add JSDoc comments to this file"

而《Using Agent in CLI》页在 Non-interactive mode 一节里另有一句：Cursor 在非交互模式下拥有完整写权限。这句和上面那句「不加 --force 不会改文件」放在一起看，口径并不完全一致，官方文档没有进一步说明两者的适用条件差异——遇到这种地方，最稳的做法是把不该动的路径写进 deny，而不是指望默认行为。

六、边界：这些地方文档划了线

cli-config.json 里的 permissions 和 permissions.json 不是同一个东西。 《Run Modes》页里的 permissions.json（位于 ~/.cursor/permissions.json 或 <project-dir>/.cursor/permissions.json）装的是 autoRun.allow_instructions 与 block_instructions，内容是自然语言句子，用来给 Auto-review 的分类器提供倾向性指导；而本文讲的 permissions.allow / permissions.deny 装的是结构化令牌。CLI 更新日志在 2026 年 3 月那条里写了「The CLI reads the same terminal/MCP allowlist file as the IDE」，指的是 CLI 也读 permissions.json。两套东西同时存在时谁覆盖谁，官方文档没有说明这一点。

模式名在两处对不齐。 《Configuration》页的可选字段 approvalMode 取值是 allowlist、auto-review、unrestricted 三档；《Run Modes》页列的三种模式叫 Auto-review、Allowlist、Run Everything。数量对得上，命名对不上，文档没有明确写出两者的对应关系，这里只陈述，不替它推断。

Auto-review 文档自述不是安全边界。 《Run Modes》页有一节标题就是「Auto-review is not a security boundary」，正文写明分类器会出错，可能放行你本想拦的调用，也可能拦掉你本想放的。这是文档自己的说法，不是我们的评价。

团队配置优先级更高。 《Run Modes》页写明团队设置优先于个人与项目配置；当团队定义了全局的 Auto-review 配置时，Cursor 会忽略用户级与项目级文件。所以在有团队策略的环境里，你本地那份 deny 未必是最终生效的全部规则。

已弃用项要认。 《Run Modes》页的 changelog 表里写明，Ask Every Time 在 3.5 中被弃用，新用户无法选择，官方给的替代做法是用空 allowlist 的 Allowlist 模式。

Windows 侧的沙箱。 《Run Modes》页的「How sandboxing works on your platform」一节只写了 macOS（Seatbelt / sandbox-exec）和 Linux（Landlock + seccomp，要求内核 6.2 及以上并启用非特权用户命名空间），没有 Windows 一节。另外 AppArmor 那一段明确标注适用于「remote environments and CLI only」，因为独立 CLI 不随包分发该 profile。Windows 原生环境下沙箱如何工作，官方文档没有说明这一点——所以 Windows 用户更应该把 deny 当成主要的兜底手段，而不是指望沙箱。

Cloud Agent 不走这套。 《Run Modes》页最后写明 Run Modes 只适用于本地 agent，Cloud Agent 跑在自己的专属机器里，从不向你请求批准。

七、怎么验证配对了

官方文档没有提供一条专门校验权限配置的 dry-run 命令，这一点得说清楚。能用上的验证手段是这几样：

先确认文件本身是合法的。 《Configuration》页的 Troubleshooting 一节写明，配置出错时把文件挪走再重启：
```
mv ~/.cursor/cli-config.json ~/.cursor/cli-config.json.bad
```
Windows 下对应的路径是 $env:USERPROFILE\.cursor\cli-config.json，用 PowerShell 的移动命令即可，官方文档只给了 Unix 侧的示例。Notes 一节还写明 CLI 会对缺失字段做自我修复，损坏文件会被备份成 .bad 并重建——所以如果你写的字段莫名其妙消失了，文档给的解释是「部分字段由 CLI 托管，可能被覆盖」。
用交互式的配置命令复核。 《Slash commands》页列出了 /config（交互式配置 CLI 设置）与 /sandbox（配置沙箱模式与网络访问）。
在沙箱里单跑一条命令。 《Parameters》页的 sandbox 子命令里有 agent sandbox run <cmd> [args...]，文档描述是以工作区读写策略运行一条命令，还有 --sb-debug 把沙箱调试日志写进临时目录并打印路径。
看日志。 /logs 会显示调试日志路径并复制到剪贴板。

一条通用建议（这属于常规做法，不是 Cursor 官方文档的内容）：项目级的 .cursor/cli.json 既然可以提交进仓库，就应该只放团队都认可的 deny，个人的 allow 留在全局文件里，免得一个人的方便变成所有人的默认。

以上命令与配置片段均按官方文档中的参数语义组合，未经实测，以官方文档与 --help 的实际输出为准。

本文依据 Cursor 官方文档（cursor.com/docs 与 cursor.com/help）于 2026-08-18 的公开内容整理。该产品闭源，本文只复述官方文档写明的机制，不推断其内部实现； 我们没有对文中涉及的功能做过实测，因此不涉及界面外观、操作手感与运行速度的任何描述。该产品迭代频繁，文中涉及的设置项与命令随版本变动，请以官方文档最新内容为准。本文不涉及订阅价格、额度与模型清单，相关信息请以官方定价与模型说明页为准。

安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。