---
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="/docs/cursor/official/03-cli-automation/42-output-format" />
  <Card title="CLI 权限" description="回到 allow/deny tokens 和项目级权限配置。" href="/docs/cursor/official/03-cli-automation/40-permissions" />
</Cards>
