CLI 設定

📖 本篇術語速查表

英文 / 縮寫	中文	一句話解釋
CLI 設定	config	CLI 的設定項和檔案。
優先順序	precedence	多來源設定誰生效。
Profile	設定檔	按場景切換的設定組。

不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你配好 Cursor CLI 的設定（優先順序、Profile）。

你是 Cursor CLI 設定顧問，幫我配好 CLI 設定，理清優先順序、用 Profile 切場景。

【角色】
你清楚 CLI 設定來源、優先順序、關鍵項、Profile 用法。

【輸入】
- 我的使用場景：___
- 想調整的行為：___
- 是否多場景切換：___
- 涉及安全項嗎：___

【工作流程】
1. 說明設定來源和優先順序
2. 給最該先調的項
3. 多場景用 Profile
4. 安全項單獨提醒

【輸出規範】
▌一、設定來源與優先順序
▌二、關鍵設定項
▌三、Profile 設計
▌四、安全項提醒

【硬約束】
- 先調關鍵項，不全量改
- 安全項單獨慎調
- 改前備份
- 不確定的項標註需查官方文件
- 給的值可直接用
- 每條結論落到可照做步驟，不空泛
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述
- 不確定的引數、設定或格式一律以官方文件為準，給的示例標註適用版本，避免照搬過時寫法誤導

Cursor CLI 使用 cli-config.json 設定。全域設定管使用者預設行為；專案設定只允許設定 permissions，不能把所有 CLI 設定都塞進儲存庫。

閱讀目標：讀完本章，你應該能找到設定檔、判斷哪些欄位能放專案級、修復損壞設定，並知道企業代理環境下如何啟用 HTTP/1.1 fallback。

1. 設定檔位置

Type	Platform	Path
Global	macOS / Linux	`~/.cursor/cli-config.json`
Global	Windows	`$env:USERPROFILE\\.cursor\\cli-config.json`
Project	All	`<project>/.cursor/cli.json`

官方限制：只有 permissions 可以設定在 project level。其他 CLI settings 必須放 global config。

環境變數覆蓋：

Env	用途
`CURSOR_CONFIG_DIR`	自定義設定目錄
`XDG_CONFIG_HOME`	Linux / BSD 下使用 `$XDG_CONFIG_HOME/cursor/cli-config.json`

2. 必填欄位

Field	Type	說明
`version`	number	schema version，目前為 `1`
`editor.vimMode`	boolean	是否啟用 Vim keybindings，預設 `false`
`permissions.allow`	string array	允許操作
`permissions.deny`	string array	禁止操作

最小設定：

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

設定檔是純 JSON，不支援 comments。不要按 JSONC 寫註釋。

3. 可選欄位

Field	說明
`model`	selected model configuration
`hasChangedDefaultModel`	CLI-managed model override flag
`network.useHttp1ForAgent`	使用 HTTP/1.1 代替 HTTP/2 agent connection，預設 `false`
`attribution.attributeCommitsToAgent`	Agent commit 新增 "Made with Cursor" trailer，預設 `true`
`attribution.attributePRsToAgent`	Agent PR 新增 "Made with Cursor" footer，預設 `true`

一些欄位是 CLI-managed，可能被 CLI 覆蓋。需要團隊統一的內容，優先寫進 rules、permissions 或 CI workflow，而不是依賴使用者全域設定。

4. Vim mode 和 permissions

啟用 Vim mode：

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

設定 permissions：

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

許可權細節回到 Permissions 章節。這裡要記住：專案級 <project>/.cursor/cli.json 只適合放 permissions。

5. 模型選擇

官方說明 CLI 模型可用 /model slash command 選擇。

/model auto
/model gpt-5.2
/model sonnet-4.5-thinking

模型可用性、團隊限制和價格都會變化。教學裡不要把某個模型寫成永久預設，實際以目前 Cursor Models & Pricing 和團隊後臺為準。

6. Proxy 和企業網路

如果網路需要代理，先設定環境變數：

export HTTP_PROXY=http://your-proxy:port
export HTTPS_PROXY=http://your-proxy:port
export NODE_USE_ENV_PROXY=1

如果代理做 SSL inspection，還要信任組織 CA：

export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca-cert.pem

部分企業代理不支援 HTTP/2 bidirectional streaming。此時可以啟用 HTTP/1.1 fallback：

{
  "version": 1,
  "editor": { "vimMode": false },
  "permissions": { "allow": [], "deny": [] },
  "network": {
    "useHttp1ForAgent": true
  }
}

官方說明該模式會把 agent connections 切到 HTTP/1.1 with Server-Sent Events，適配多數企業代理。

7. 設定排障

設定報錯：

mv ~/.cursor/cli-config.json ~/.cursor/cli-config.json.bad

然後重啟 CLI，讓它重新生成設定。

修改不生效：

檢查 JSON 是否有效。
檢查檔案寫許可權。
區分 global config 和 project permissions。
記住某些欄位由 CLI 管理，可能被覆蓋。

設定損壞：

官方說明 corrupted files 會備份為 .bad 並重新建立。
缺失欄位 CLI 會嘗試 self-repair。

深讀：為什麼專案級設定只放 permissions 是好事

專案儲存庫應該定義安全邊界，而不是接管每個開發者的編輯習慣、模型選擇和個人網路設定。

把 project config 限定為 permissions，可以讓儲存庫表達“這個專案允許 Agent 做什麼”，同時保留使用者本機的模型、Vim、代理和 attribution 偏好。

本章自檢

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

哪些設定能放 <project>/.cursor/cli.json？
為什麼企業代理環境可能需要 network.useHttp1ForAgent？
設定損壞時為什麼先移動檔案而不是手動亂改？

透過標準：你能定位目前機器的 CLI config，寫出最小 JSON 設定，並解釋 global 與 project config 的職責邊界。

官方來源

Cursor CLI Configuration —— 官方設定路徑、schema、示例、排障、模型和 proxy 設定。
Cursor CLI Permissions —— 官方 project-level permissions 背景。
Cursor Slash Commands —— 官方 /model 等會話命令。
Cursor Network Configuration —— 官方 proxy testing 和 troubleshooting。