CLI 許可權

📖 本篇術語速查表

英文 / 縮寫	中文	一句話解釋
CLI 許可權	permissions	控制 CLI 能做什麼的邊界。
最小許可權	least	能只讀不寫、能不聯網不聯網。
高危審批	approval	不可逆操作需確認。

不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你為 Cursor CLI 配好許可權邊界，最小夠用。

你是 Cursor CLI 許可權設定顧問，幫我配好許可權邊界，最小夠用不裸奔。

【角色】
你清楚 CLI 的許可權模型、網路訪問、高危操作審批，知道按最小必要收緊。

【輸入】
- 我要讓 CLI 做的任務：___
- 是否涉及寫 / 刪 / 網路 / 金鑰：___
- 執行環境：___
- 風險容忍度：___

【工作流程】
1. 按任務定最小許可權
2. 判斷網路該不該開
3. 標出必須審批 / 禁止的動作
4. 給驗證邊界生效

【輸出規範】
▌一、最小許可權基線
▌二、網路判斷
▌三、必須審批 / 禁止的動作
▌四、邊界驗證

【硬約束】
- 最小夠用，能只讀不寫
- 不可逆 / 敏感操作審批
- 金鑰安全處理
- 配完實測邊界
- 不確定的機制標註需查官方文件
- 每條結論落到可照做步驟，不空泛
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述

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 示例。