借助后台代理,可在远程环境中启动异步代理来编辑和运行代码。随时查看它们的状态、发送后续指令,或随时接管。

使用方法

你可以通过两种方式访问后台代理:
  1. 后台代理侧边栏:在原生 Cursor 侧边栏中使用“后台代理”标签页,查看与你账号关联的所有后台代理、搜索现有代理,并新建代理。
  2. 后台代理模式:按下 ,在 UI 中触发后台代理模式。
提交提示词后,从列表中选择你的代理以查看状态并进入该机器。

后台代理需要保留数据数天。

设置

后台代理默认在隔离的 Ubuntu 基础环境中运行。代理可联网并安装软件包。

连接 GitHub

后台智能体会从 GitHub 克隆你的仓库,在单独的分支上工作,并推送到你的仓库,方便交接。 请为你的仓库(以及任何依赖的仓库或子模块)授予读写权限。我们未来也会支持其他提供商(GitLab、Bitbucket 等)。
IP 允许列表配置
如果你的组织启用了 GitHub 的 IP 允许列表功能,需要为后台代理配置访问权限。完整的设置步骤(包含联系方式和 IP 地址)请查看 GitHub 集成文档

基础环境设置

在更高级的场景中,自己配置环境。先获取一个连接远程机器的 IDE 实例。配置你的机器、安装工具和包,然后创建快照。接着配置运行时设置:
  • Install 命令会在代理启动前运行,用于安装运行时依赖,比如执行 npm installbazel build
  • Terminals 会在代理工作期间运行后台进程——例如启动 Web 服务器或编译 protobuf 文件。
在最复杂的场景下,用 Dockerfile 来进行机器配置。Dockerfile 允许你设置系统级依赖:安装特定版本的编译器、调试器,或切换基础 OS 镜像。不要 COPY 整个项目——我们会管理工作区并检出正确的提交。依赖安装仍然放在 install 脚本中处理。 输入开发环境所需的任意密钥(secrets)——它们会以静态加密(使用 KMS)的方式存储在我们的数据库中,并在后台代理的环境中提供。 机器配置保存在 .cursor/environment.json 中,可以提交到你的仓库(推荐)或私下存储。设置流程会引导你创建 environment.json

维护命令

在设置新机器时,我们从基础环境开始,然后运行你在 environment.json 中的 install 命令。这个命令等同于开发者在切换分支时会运行的操作——用于安装新增依赖。 对大多数人来说,install 命令是 npm installbazel build 为确保机器能快速启动,我们会在 install 命令运行完成后缓存磁盘状态。把它设计成可重复运行。只有由 install 命令产生的磁盘状态会被保留——在这里启动的进程在代理启动时不会继续存在。

启动命令

运行 install 之后,机器会启动,我们会先运行 start 命令,再启动所有 terminals。这会拉起在代理运行期间需要常驻的进程。 start 命令通常可以省略。如果你的开发环境依赖 Docker,可以在 start 命令里加上 sudo service docker start terminals 用于应用代码。这些终端会在一个你和代理都能访问的 tmux 会话中运行。比如,很多网站仓库会把 npm run watch 配成一个 terminal。

environment.json 规范

environment.json 文件可能如下:
{
  "snapshot": "POPULATED_FROM_SETTINGS",
  "install": "npm install",
  "terminals": [
    {
      "name": "运行 Next.js",
      "command": "npm run dev"
    }
  ]
}
严格来说,规范定义在这里

模型

只有与 Max Mode 兼容的模型才能用于后台代理。

定价

进一步了解 Background Agent 的定价

安全性

Background Agents 可在隐私模式下使用。我们绝不会用你的代码进行训练,只会在运行 agent 时临时保留代码。了解更多隐私模式 你需要知道:
  1. 为你想编辑的仓库授予我们 GitHub 应用的读写权限。我们会用它来克隆仓库并进行更改。
  2. 你的代码会在我们基于 AWS 的隔离 VM 中运行,并在 agent 可用期间存储在 VM 磁盘上。
  3. agent 可以访问互联网。
  4. agent 会自动执行所有终端命令,方便它循环运行测试。这和前台 agent 不同,前台每条命令都需要用户批准。自动执行会带来数据外泄风险:攻击者可能通过提示注入攻击,诱使 agent 将代码上传到恶意网站。参见 OpenAI 关于后台 agent 提示注入风险的说明
  5. 如果关闭隐私模式,我们会收集提示词和开发环境信息,用于改进产品。
  6. 如果在启动后台 agent 时禁用隐私模式,且在其运行过程中再启用,agent 会在完成前一直以禁用的隐私模式继续运行。

仪表板设置

Workspace 管理员可以在仪表板的 Background Agents 选项卡中配置更多设置。

默认设置

  • 默认模型 – 运行未指定模型时使用的模型。选择任一支持 Max Mode 的模型。
  • 默认仓库 – 留空时,agent 会让你选择仓库。在这里填上仓库就能跳过这一步。
  • 基础分支 – agent 在创建拉取请求时进行 fork 的源分支。留空则使用仓库的默认分支。

安全设置

所有安全选项都需要管理员权限。
  • 用户限制 – 选择 None(所有成员都可以启动后台 agent)或 Allow list。当设置为 Allow list 时,你需要明确指定哪些队友可以创建 agent。
  • 团队跟进 – 开启后,工作区内的任何人都可以给他人启动的 agent 添加跟进消息。关闭后,跟进仅限该 agent 的所有者和管理员。
  • 显示 agent 摘要 – 控制 Cursor 是否显示该 agent 的文件差异图和代码片段。如果不想在侧边栏暴露文件路径或代码,就把它关掉。
  • 在外部渠道显示 agent 摘要 – 将上一个开关扩展到 Slack 或你已连接的任何外部渠道。
更改会即时保存,并立即作用于新创建的 agent。