CLI 許可權

Cursor CLI permissions 用 permission tokens 控制 Agent 能做什麼。它們可以寫在全域性 ~/.cursor/cli-config.json，也可以寫在專案級 <project>/.cursor/cli.json。

閱讀目標：讀完本章，你應該能寫出一份最小許可權配置，區分 shell、read、write、web fetch 和 MCP 工具許可權，並理解 deny 為什麼優先。

1. 配置位置

Scope	Path	用途
Global	`~/.cursor/cli-config.json`	當前使用者預設 CLI 配置
Project	`<project>/.cursor/cli.json`	當前專案許可權配置

專案級配置適合團隊儲存庫，因為它能把“這個專案裡 Agent 可以做什麼”寫進儲存庫邊界。

2. 五類 permission tokens

型別	格式	控制什麼
Shell	`Shell(commandBase)`	shell command base
Read	`Read(pathOrGlob)`	檔案和目錄讀取
Write	`Write(pathOrGlob)`	檔案和目錄寫入
WebFetch	`WebFetch(domainOrPattern)`	web fetch 可訪問域名
MCP	`Mcp(server:tool)`	MCP server tool 呼叫

核心規則：allow 只是允許，deny 是硬阻止。deny rules take precedence over allow rules。

3. Shell 許可權

Shell token 看命令列第一個 token，也支援 command:args 做更細控制。

示例	含義
`Shell(ls)`	允許 `ls`
`Shell(git)`	允許任意 git subcommand
`Shell(npm)`	允許 npm
`Shell(curl:*)`	允許 curl 及任意引數
`Shell(rm)`	常見 deny，用於阻止刪除

生產預設不要輕易 allow git、gh、rm、sudo、curl 和包管理器全量命令。它們要麼能改歷史，要麼能訪問外部網路，要麼能破壞檔案系統。

4. Read 和 Write 許可權

Read 控制可讀範圍：

示例	含義
`Read(src/*/.ts)`	允許讀 `src` 下 TypeScript
`Read(*/.md)`	允許讀任意 Markdown
`Read(.env*)`	常見 deny，阻止讀環境檔案
`Read(/etc/passwd)`	常見 deny，阻止讀系統檔案

Write 控制可寫範圍。官方提醒：print mode 中寫檔案需要 --force。

示例	含義
`Write(src/**)`	允許寫 `src`
`Write(package.json)`	允許改 package.json
`Write(*/.key)`	常見 deny，阻止寫私鑰檔案
`Write(*/.env)`	常見 deny，阻止寫環境檔案

商業專案裡，Write 的範圍應該比 Read 更窄。能讀全倉不等於能寫全倉。

5. WebFetch 和 MCP

WebFetch 控制網頁讀取域名：

示例	含義
`WebFetch(docs.github.com)`	允許 GitHub docs
`WebFetch(*.example.com)`	允許 example.com 子域名
`WebFetch(*)`	允許任意域名，高風險

MCP token 使用 server:tool：

示例	含義
`Mcp(datadog:*)`	允許 Datadog MCP 所有工具
`Mcp(*:search)`	允許任意 server 的 search 工具
`Mcp(:)`	允許所有 MCP 工具，高風險

WebFetch(*) 和 Mcp(*:*) 都不適合預設生產配置。它們方便，但審計邊界太寬。

6. 最小配置示例

{
  "permissions": {
    "allow": [
      "Shell(ls)",
      "Shell(grep)",
      "Read(src/**/*.ts)",
      "Read(**/*.md)",
      "Write(docs/**/*)",
      "WebFetch(docs.github.com)"
    ],
    "deny": [
      "Shell(rm)",
      "Shell(git)",
      "Shell(gh)",
      "Read(.env*)",
      "Write(**/*.key)",
      "WebFetch(*)"
    ]
  }
}

這不是通用答案，而是思路：先只開放任務需要的讀、寫、命令和域名；再用 deny 鎖住高風險區域。

7. Pattern matching

官方規則：

glob 支援 **、*、?。
relative paths 以當前 workspace 為作用域。
absolute paths 可以指向專案外檔案。
deny 優先於 allow。
command:args 可對命令和引數做 glob 匹配。

這意味著 <project>/.cursor/cli.json 裡的相對路徑要結合 workspace 理解。CI 中最好顯式設定 workspace，避免路徑作用域誤判。

深讀：為什麼 deny 要寫得比 allow 更保守

allow 定義任務能力，deny 定義事故邊界。任務變化時，allow 可能需要擴充套件；但 .env*、private key、刪除命令、系統檔案、生產憑據這類邊界通常長期穩定。

把穩定紅線寫進 deny，可以減少因為臨時任務擴權導致的洩露或破壞。

本章自檢

完成本章後，用這 3 個問題檢查自己是否真正理解：

為什麼 Write 範圍通常應該小於 Read 範圍？
WebFetch(*) 和 Mcp(*:*) 為什麼不適合預設生產配置？
deny 和 allow 同時命中時誰優先？

透過標準：你能為 docs-only CI workflow 寫出 permissions，並解釋每條 allow / deny 的業務原因。

官方來源

Cursor CLI Permissions —— 官方 permission tokens、配置示例和 pattern matching。
Cursor CLI Configuration —— 官方配置檔案位置和 schema。
Cursor GitHub Actions —— 官方 CI permissions 示例。