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。