Cursor 使用：项目规则、执行模式与自带 Key

信息层级：【有据可查】= 附官方文档或可信来源链接；【社区共识】= 社区用户普遍经验，未经官方确认；【待考察/推测】= 推测或暂未能核实，请谨慎对待。

1. 定位

【有据可查】Cursor 是 AI 原生代码编辑器（基于 VS Code 生态），提供本地 Agent、Tab 补全、Cloud Agents、CLI 等；项目规则放在 .cursor/rules，也支持 AGENTS.md。来源：Cursor Docs、Rules

2. 订阅方案结构（价格以官网为准）

【有据可查】官方定价页列出 Hobby（免费，有限额度）、Pro、Pro+、Ultra 以及 Teams / Enterprise；付费档包含一定额度的第三方模型用量与 Cursor 自研模型用量，额度按月重置、不结转，超出可按需计费。来源：Pricing、Usage and limits

【社区共识】Cursor 计费规则历史上调整过多次，订阅前务必阅读当期官方说明。

2.1 自带 Key（BYOK）的边界【有据可查】

来源：Bring your own API key、OpenAI 帮助中心

Settings → Models 可填 OpenAI、Anthropic、Google、Azure、AWS Bedrock 的 Key；个人套餐下用自己的 Key 由厂商直接计费。
只对本地 Chat / Agent 生效；Tab 补全、Auto 模型选择、Cloud/Background Agents、Automations、Cursor CLI、Cursor API/SDK 不能使用你的 Key。
Key 不存储在 Cursor 服务器，但每次请求会经过 Cursor 后端（用于组装提示）。

3. 安装与首次配置

官网下载安装包：https://cursor.com（有 CLI，详见官方文档）【有据可查】
首次建议：
1. 打开项目 → 让 Agent 运行 /create-rule 生成项目规则；或直接写 AGENTS.md。
2. Settings → Agents → Approvals & Execution 确认运行模式（见下）。
3. 敏感文件加入 .cursorignore。

4. 权限 / 安全模型【有据可查】

来源：Run Modes、permissions.json、sandbox.json

4.1 三种运行模式

模式	自动运行什么	沙箱	分类器
Auto-review（3.6 起推荐默认）	白名单立即运行；其它 Shell 尽量放沙箱；不能进沙箱的交给分类器	是	是
Allowlist	仅白名单自动运行；可配合沙箱	可选	否
Run Everything	全部自动运行	否	否

【有据可查】3.5 起 "Ask Every Time" 已弃用；想要同等效果可用"空白名单的 Allowlist"。
【有据可查】官方明确：Auto-review 不是安全边界，分类器会出错。

4.2 沙箱默认行为

访问	默认
工作区文件	可读写（`.cursorignore` 可隐藏）
受保护路径	`.git/config`、`.git/hooks`、`.vscode`、`.cursorignore` 等受保护
网络	默认阻断，再按网络模式与 `sandbox.json` 放开（默认模式为"sandbox.json + 官方默认包管理域名"）
临时目录	可写（可在 sandbox.json 禁用）

平台实现：macOS 用 Seatbelt；Linux 用 Landlock + seccomp，需内核 6.2+（Landlock v3）与非特权 user namespace，不满足则回退为执行前询问。

4.3 读取边界（3.23 新增）

Read Access 可设为 Workspace：读工作区外的文件需审批，或加入 Read Allowlist。默认是 System（可读工作区外）。

4.4 其它保护

Browser Protection、File-Deletion Protection（含 rm）、External-File Protection（工作区外增删改）。

4.5 两个配置文件分工

文件	管什么
`permissions.json`（`~/.cursor/` 或项目 `.cursor/`）	终端/MCP 白名单 + Auto-review 自然语言指引（`allow_instructions` / `block_instructions`）
`sandbox.json`	沙箱可达的网络域名、额外读写路径、临时目录、读取边界

// .cursor/permissions.json 示例（改写自官方文档）
{
  "terminalAllowlist": ["git status", "npm test"],
  "autoRun": {
    "block_instructions": ["Every command that deploys to production should go through approval first."]
  }
}

Cloud Agents 不使用 Run Modes，在独立机器上运行、不会请求审批。【有据可查】

5. Rules：让 Agent 记住你的规矩【有据可查】

`alwaysApply`	`description`	`globs`	行为
true	—	—	总是包含
false	—	有	匹配文件在上下文时自动附加
false	有	无	Agent 按描述自行决定是否引用
false	无	无	仅在 `@` 提及时包含

规则必须是 .mdc；普通 .md 放在 .cursor/rules 会被忽略（想用纯 Markdown 就写 AGENTS.md）。
规则是"指导"，不是强制执行——强制要靠 permissions/sandbox。

6. 接入自定义模型

BYOK：见 2.1。
自定义 OpenAI 兼容 Base URL：OpenAI 帮助中心说明可在 Models 设置中填网关的 Base URL 与凭据，但"兼容性因网关而异，部分模型控制可能无法转发"。【有据可查】

7. 常见报错

现象	原因	处理	层级
Auto-review 灰色不可选	团队禁用了分类器所需模型	管理员在 Team Settings → Models 允许相关模型	有据可查
Linux 下每条命令都要审批	内核不满足沙箱要求，已回退	升级内核/启用 user namespace；远程/CLI 环境安装官方 AppArmor 包	有据可查
沙箱内 `id -u` 为 0	Linux 沙箱 UID 重映射	用 `CURSOR_ORIG_UID`	有据可查
`.md` 规则不生效	规则需 `.mdc`	改扩展名或用 AGENTS.md	有据可查
自带 Key 但 Tab/CLI 仍扣 Cursor 额度	BYOK 不覆盖这些功能	正常现象	有据可查

8. 适合人群

✅ 习惯 VS Code、想要 IDE 内一体化体验
✅ 想要"沙箱 + 分类器 + 白名单"多层自动化的团队
⚠️ 对数据经过第三方后端敏感的场景：BYOK 请求也经过 Cursor 后端

9. 本篇无法核实/需谨慎的点

各档具体额度与价格（变化快，未列）。
Cursor CLI 的完整命令集未逐条核对。
自定义 Base URL 与各类网关的实际兼容性。

小白练习：把本文流程逐项走通

练习目标：在 IDE 中看懂修改，并区分自带 Key 的使用范围。

上文已介绍概念、配置和操作示例。下面侧重第一次实际操作时的顺序、检查点和结果核对；需要查具体参数时回到对应小节。命令逐条输入，看到上一条的结果后再继续。

安装后用 Open Folder 打开练习项目，确认左侧文件树没有包含整个个人目录。
在 Agent 设置中查看当前执行模式。使用前读清楚自动运行和沙箱分别控制什么。
把测试命令、目录约定写入 AGENTS.md，或用 Rules 功能创建正确格式的规则文件。
需要 BYOK 时在模型设置里选择供应商、保存自己的 Key，再确认本次功能是否支持 BYOK。
先要求 Agent 只读分析，再提出一个小修改。用编辑器 diff 逐文件核对，随后运行原有测试。
遇到设置名称与原文不同，查看安装版本的官方说明；规则、读取范围与执行权限分开检查。

继续浏览制器坊返回顶部 ↑