---
title: "CLI 配置"
description: "基於 Cursor 官方 Configuration 文件解釋 cli-config.json、專案配置限制、schema、Vim mode、permissions、proxy、HTTP/1.1 fallback 和排障。"
verifiedAt: "2026-05-09"
---

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

> [!NOTE]
> **閱讀目標**：讀完本章，你應該能找到配置檔案、判斷哪些欄位能放專案級、修復損壞配置，並知道企業代理環境下如何啟用 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 | 禁止操作 |

最小配置：

```json
{
  "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：

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

配置 permissions：

```json
{
  "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 選擇。

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

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

## 6. Proxy 和企業網路

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

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

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

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

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

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

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

## 7. 配置排障

配置報錯：

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

然後重啟 CLI，讓它重新生成配置。

修改不生效：

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

配置損壞：

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

<details>
<summary>深讀：為什麼專案級配置只放 permissions 是好事</summary>

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

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

## 本章自檢

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

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

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

## 官方來源

- [Cursor CLI Configuration](https://cursor.com/docs/cli/reference/configuration.md) —— 官方配置路徑、schema、示例、排障、模型和 proxy 配置。
- [Cursor CLI Permissions](https://cursor.com/docs/cli/reference/permissions.md) —— 官方 project-level permissions 背景。
- [Cursor Slash Commands](https://cursor.com/docs/cli/reference/slash-commands.md) —— 官方 `/model` 等會話命令。
- [Cursor Network Configuration](https://cursor.com/docs/enterprise/network-configuration.md) —— 官方 proxy testing 和 troubleshooting。

## 接下來去哪

<Cards>
  <Card title="輸出格式" description="繼續學習 text、json、stream-json 和 partial output。" href="/zh-Hant/docs/cursor/official/03-cli-automation/42-output-format" />
  <Card title="CLI 許可權" description="回到 allow/deny tokens 和專案級許可權配置。" href="/zh-Hant/docs/cursor/official/03-cli-automation/40-permissions" />
</Cards>
