后台代理

Cursor 的异步远程代理

使用 background agents，在远程环境中启动异步代理来编辑并运行代码。你可以随时查看它们的状态、发送后续指令，或在任何时候接管。

如何使用

你可以通过两种方式使用后台代理：

1. 后台代理侧边栏：在原生 Cursor 侧边栏的后台代理选项卡中，查看与你账户关联的所有后台代理、搜索现有代理，并新建代理。
2. 后台代理模式：按下 Ctrl+E 在界面中触发后台代理模式。

提交提示后，从列表中选择你的代理以查看状态并进入该机器。

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

设置

默认情况下，Background agents 会在一台隔离的、基于 Ubuntu 的机器上运行。Agents 可以访问互联网并安装软件包。

GitHub 连接

后台代理会从 GitHub 克隆你的仓库，在独立分支上工作，并推送回你的仓库，便于交接。

为你的仓库（以及任何依赖的仓库或子模块）授予读写权限。未来我们还会支持其他提供商（GitLab、Bitbucket 等）。

IP 允许列表配置

如果你的组织启用了 GitHub 的 IP 允许列表功能，你需要为后台代理配置访问权限。查看 GitHub 集成文档 获取完整的设置说明，其中包括联系方式和 IP 地址。

基础环境设置

对于更高级的用例，可以自己搭环境。先拿一个连接到远程机器的 IDE 实例。把你的机器配置好，安装工具和依赖包，然后创建一个快照。再配置运行时设置：

• Install 命令会在代理启动前运行，用来安装运行时依赖。这可能就是执行 npm install 或 bazel build。
• Terminals 会在代理工作时运行后台进程——比如启动 Web 服务器或编译 protobuf 文件。

在更高级的场景里，用 Dockerfile 来完成机器初始化。Dockerfile 让你配置系统级依赖：安装特定版本的编译器、调试器，或切换基础 OS 镜像。不要 COPY 整个项目——我们会管理工作区并检出正确的提交。依赖安装仍然放在 install 脚本里处理。

把开发环境需要的密钥填上——我们会用 KMS 做静态加密存储在数据库里，并在后台代理的环境中提供它们。

机器设置位于 .cursor/environment.json，可以提交到你的仓库（推荐）或私下存储。设置流程会引导你创建 environment.json。

维护命令

在设置新机器时，我们会从基础环境开始，然后运行你在 environment.json 里的 install 命令。这个命令相当于开发者切分支时会执行的步骤——用于安装任何新增依赖。

对大多数人来说，install 命令就是 npm install 或 bazel build。

为确保机器能快速启动，我们会在 install 命令执行后缓存磁盘状态。把它设计成可重复执行。只有 install 命令产生的磁盘状态会被持久化——在这里启动的进程，在代理启动时并不会保留。

启动命令

运行 install 之后，机器会启动，我们会运行 start 命令，随后启动所有 terminals。这会启动在代理运行时应保持存活的进程。

start 命令通常可以跳过。如果你的开发环境依赖 Docker，请把 sudo service docker start 放在 start 命令里。

terminals 用于应用代码。这些终端会在一个 tmux 会话中运行，你和代理都可以使用。比如，很多网站仓库会把 npm run watch 配置成一个 terminal。

environment.json 规范

environment.json 文件可能是这样的：

{
  "snapshot": "POPULATED_FROM_SETTINGS",
  "install": "npm install",
  "terminals": [
    {
      "name": "Run Next.js",
      "command": "npm run dev"
    }
  ]
}

该规范的正式定义见此处。

模型

后台代理仅支持与 Max Mode 兼容的模型。

定价

了解更多关于 Background Agent 定价 的信息。

安全性

Background Agents 可在隐私模式下使用。我们从不使用你的代码进行训练，且只在运行代理时临时保留代码。进一步了解隐私模式。

你需要知道：

1. 为你想编辑的仓库向我们的 GitHub 应用授予读写权限。我们用它来克隆仓库并进行修改。
2. 你的代码会在我们的 AWS 基础设施内、隔离的虚拟机中运行，并在代理可用期间存储在虚拟机磁盘上。
3. 代理可以访问互联网。
4. 代理会自动运行所有终端命令，方便其迭代测试。这与前台代理不同：前台代理对每条命令都需要你的批准。自动运行会带来数据外泄风险：攻击者可能通过提示注入诱使代理将代码上传到恶意网站。参见 OpenAI 对后台代理提示注入风险的说明。
5. 如果关闭了隐私模式，我们会收集提示和开发环境信息以改进产品。
6. 如果你在启动后台代理时关闭了隐私模式，随后在代理运行过程中又开启它，代理会在完成前一直按关闭隐私模式的状态继续运行。

仪表板设置

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

默认设置

• 默认模型 – 在运行未指定模型时使用的模型。选择任意支持 Max Mode 的模型。
• 默认仓库 – 留空时，agents 会让你选择一个仓库。在这里填写仓库就能跳过这一步。
• 基础分支 – agents 在创建 pull request 时进行分叉的基线分支。留空则使用仓库的默认分支。

安全设置

所有安全选项都需要管理员权限。

• 用户限制 – 选择 None（所有成员都可以启动后台代理）或 Allow list。当设置为 Allow list 时，你可以精确指定哪些队友可以创建代理。
• 团队跟进 – 开启后，工作区中的任何人都可以给他人启动的代理添加跟进消息。关闭后，只有代理所有者和管理员可以跟进。
• 显示代理摘要 – 控制 Cursor 是否展示代理的文件差异图和代码片段。如果你不想在侧边栏暴露文件路径或代码，请关闭此项。
• 在外部频道显示代理摘要 – 将上一项的开关扩展到 Slack 或你已连接的任何外部频道。

更改会即时保存，并立即作用于新建的代理。