Cursor Cloud Agent 怎么配起来：环境、构建与设置三处

2026-08-18

很多人对 Cloud Agent 的第一印象是「开个云端会话让它改代码」，然后卡在同一处：它能写，但跑不了测试，连不上内网服务，装依赖每次都要等。Cursor 官方文档《Cloud Environment Setup》页把这层说得很直白——agent 的能力上限就是它所在环境的上限，一个能写代码却没法跑测试、查服务、访问 API 的 agent，没办法把一件事做完。

所以真正要配的不是「agent」，是它脚下那台机器。链路分三处：环境怎么定义、Build 怎么把环境准备好、仪表盘上的设置项决定谁能改什么。Cloud Agent 本身的形态与用法我们另有一篇专门讲，这里只走配置。

一、前置条件：先确认你在哪个端、有没有那个权限

这一段最容易被跳过，但跳过了后面每一步都会卡。

运行环境是 Ubuntu。 文档写明 cloud agent 跑在隔离的 Ubuntu 机器上。这条对本站读者尤其要紧：不管你本地是 Windows 还是 macOS，写进配置里的 install、start 命令都是给那台 Linux 机器执行的，PowerShell 的写法在这里不成立。Windows 侧另有一处小麻烦——配置文件在仓库的 .cursor/ 目录下，这种以 . 起头的目录用资源管理器新建比较别扭，在编辑器里或用命令行创建更省事（这句是通用做法，非官方文档内容）。

入口有两个：Cloud Agents 仪表盘的 environments 区块；引导式设置也可以从 Cursor 桌面端的 Agents Window 里发起。文档写明引导式设置会让你连接 GitHub、GitLab、Azure DevOps 或 Bitbucket 账号，并选择一个或多个仓库。

权限分层要看清。 《Cloud Agents settings》页写明：Cloud Agents 由 workspace 管理员在仪表盘上配置，安全相关选项全部需要管理员权限，团队功能开关由 team admin 控制。你要是团队里的普通成员，本文后半段的一些开关你打不开。

有两项文档明确划了范围：computer use 只对 enterprise 团队开放；由 Cursor 替你生成 Dockerfile 的那条路径处于 private beta，且面向 Enterprise 团队，文档说要通过客户代表或邮件申请。别把这两条当成现成能用的能力。

二、第一处：环境从哪里来，解析顺序决定一切

配置之前先搞清楚一件事——同一个仓库可能同时存在好几份环境配置，到底哪份生效。文档给了明确的解析顺序，按仓库或仓库组匹配，取第一个命中的，一共三级：

优先级	来源
1	仓库里的 `.cursor/environment.json`
2	个人保存的环境
3	团队保存的环境

文档自述了这么排的理由：团队层面给出可预测的默认值，同时在仓库里没有 .cursor/environment.json 时允许个人用自己的环境覆盖，方便在推给全团队之前先试新配置。

顺序带来一个直接后果（把文档里两句话摆在一起就能看出来，不是猜的）：一旦 .cursor/environment.json 进了仓库，个人和团队环境就都不生效了。 改了个人环境却不见效，第一件事就是去仓库里看有没有那个文件。

配置方式官方给了两条路：让 Cursor 的 agent 自己搭（文档标注为 recommended，它会装依赖、验证环境、创建第一个 Build），或者自己写 Dockerfile。两条路都支持指定 install 脚本。走 Dockerfile 时文档列了几条硬约束：不要 COPY 整个项目（工作区由 Cursor 管理，它会检出正确的 commit）；你只能通过 Dockerfile 配置环境，拿不到远程机器的直接访问权限；Dockerfile 构建走层缓存，改了只重建变化的层。

多仓场景也在这一层配：创建环境时选多个仓库，Cursor 把每个选中的仓库都克隆进 agent 机器，后续用同一仓库组的 agent 运行与 automation 复用这个环境。

三、第二处：`.cursor/environment.json` 的字段与那个反直觉的路径规则

官方文档给的第一份样例，是引用 .cursor/Dockerfile（相对路径）加一个 custom_script.sh 安装脚本的写法：

{
  "build": {
    "dockerfile": "Dockerfile",
    "context": ".."
  },
  "install": "pnpm install && ./custom_script.sh"
}

第二份样例是基于 snapshot 的配置，文档说 snapshot ID 可以在仪表盘的 environments 页面拿到：

{
  "snapshot": "snapshot-20260212-00000000-0000-0000-0000-000000000000",
  "install": "npm install"
}

路径行为这一段建议读两遍，是整页里最容易踩的地方。文档写明：build 里的 dockerfile 和 context 都相对于 .cursor 目录；省略 context 时它默认为 .cursor；而 .、./、.. 这三个值被特殊处理为仓库根目录。所以要 COPY 那些放在 .cursor 里、写裸文件名的文件，反而应该省略 context。另外 install 是从项目根目录执行的——context 的相对基准和 install 的工作目录不是同一个地方。完整 schema 挂在 www.cursor.com/schemas/environment.schema.json。

install 之外的两个运行期命令，文档在《Cloud Agent Builds》页给了一张分工表：

命令	什么时候跑	用来做什么
`install`	每次 Build 期间	装依赖、生成代码、编译产物、预热磁盘缓存
`start`	每次 agent 运行开始时	启动 Docker、数据库、隧道等服务
`terminals`	每次 agent 运行开始时	在与 agent 共享的 `tmux` 终端里跑应用进程

分工的判据文档写死了：Build 只保留磁盘状态。运行中的进程、导出的 shell 变量、内存里的缓存，在 Cursor 快照机器时就停了，不会延续到 agent 运行。所以「装东西」放 install，「起服务」放 start 或 terminals。环境依赖 Docker 时，文档给的写法就是在 start 里加 sudo service docker start；很多仓库其实可以不写 start。

两条关于 install 的规定不能漏：它必须幂等（每次 Build 都跑，且可能跑在之前准备好的磁盘状态上），还要能跑到结束。文档另提到 install 脚本可以读取 agent metadata，并从 agent 使用的同一个本地 socket 申请 OIDC token。另外，install 脚本以前在仪表盘和文档里叫 update script，看到旧称不用慌。

四、第三处：Build 的触发、密钥可见性与仪表盘开关

Build 是「一个已准备好的 Cloud Agent 环境的可启动快照」，生命周期文档列了五步：触发、准备（从基础镜像起、克隆环境里每个仓库的默认分支、把 install 跑完）、快照（连同环境版本和每个仓库的确切 commit SHA 一起存盘）、激活、新 agent 从活跃 Build 启动。

触发方式列了四类，Builds 标签页会标出每条记录属于哪一类：定期（Recurring）、配置变更、手动（选 Trigger build）、agent 主动请求。有个容易误读的状态：定期检查发现「所有仓库默认分支没有新 commit、配置和密钥也没变」时，这次记为 Skipped，几秒完成、不跑 install、活跃 Build 原样保留。文档说 Recurring 记录里 Skipped 与 Success 交替出现正是健康环境的常态。只有定期 Build 会被跳过，其余三类一定会跑。

密钥在这里有条明确的可见性分界，踩了不好查：team 密钥和 environment 密钥在 Build 期间可用（私有包仓库、制品库这类 install 需要的凭据靠它），而 user 密钥只在 agent 启动时注入，Build 期间拿不到，也不进共享快照。install 依赖某个凭据却一直失败，先确认它是不是被放在了用户级。另外，保存环境配置或改它的密钥本身就会触发一次新 Build。环境级密钥（environment-scoped secrets）则对该环境里每个仓库生效，不流向其它环境。

仪表盘上还有几组开关，按用途分：

默认项：默认模型（run 没指定模型时用它）、默认仓库（留空则每次让用户选）、base branch（agent 创建 PR 时 fork 的分支，留空则用仓库默认分支）。
网络访问：用户级和团队级支持三种模式——完全放开、默认域名清单加你自己加的域名、以及只允许你显式添加的域名。环境级设置可以继承用户或团队策略、追加环境 allowlist，或自定义访问模式。
安全项（全部需要管理员权限）：是否展示 agent 摘要（文件 diff 图与代码片段）、是否把这个展示延伸到 Slack 等已连接的外部渠道、以及团队追问（team follow-ups）。

团队追问有三档：Disabled（只有创建者能追问）、Service accounts only（只能对服务账号创建的 agent 追问）、All（任何成员可对团队内任意 agent 追问）。文档在这一节下面直接写了风险，原样转述：开启后一个用户可以影响另一个用户的密钥与凭据所驱动的 agent 执行，追问消息可以让 agent 读环境变量、把密钥打进日志、推到外部端点，或用创建者的令牌做事，权限较低的成员因此可能提权；文档建议用对待共享 SSH 密钥或服务凭据的谨慎程度对待这个开关。

五、边界：哪些地方文档明说了不支持或还没到

Cursor 替你生成 Dockerfile：private beta，面向 Enterprise 团队，需申请。
Computer use：作为团队功能仅对 enterprise 团队开放；在 Dockerfile 仓库上，只支持基于 Debian/Ubuntu 的 Linux 发行版，其它发行版文档让你联系支持。
Long running agents：由 team admin 控制；文档明确写了 multi-repo 环境暂不支持，选了多仓环境这个开关会被禁用。
资源规格：每个 cloud agent 跑在一个默认 VM 规格上，内存与 CPU 有限，Enterprise 计划可联系支持提额；自助的自定义资源配置，文档写的是 coming soon。
Docker 与 Tailscale：文档说 Docker 跑在另一层容器里有边缘情况，简单流程「通常可用」（这是文档的措辞，不是保证），复杂场景要从 fuse-overlayfs 与 iptables-legacy 那套配置起步；Tailscale 则在 Cloud agent VM 的默认网络模式下不工作，要改用 userspace networking，而这种模式下 VM 无法作为 tailnet 的出口节点。
远程机器访问：没有，只能通过 Dockerfile 和配置文件间接控制。

还有一条属于行为边界而非能力缺失：默认分支的运行从活跃 Build 记录的 commit 开始，只有开了 Update stale builds 且 Build 超过 Staleness threshold，agent 才会在启动时拉最新默认分支代码（阈值有官方默认值，会随版本调整，以文档为准；设为 0 表示每次都拉）。特性分支则从活跃 Build 的磁盘出发再检出你要的分支，源码是分支的、依赖复用 Build 的。

六、怎么验证你配对了

判据要落在可查的记录上，而不是「感觉能跑了」。

看 Builds 标签页。文档写明这里能看到每个 Build 的类型、状态与开始时间，能查详情和日志，能手动 Trigger build、激活草稿 Build 或停用某个 Build、取消进行中的 Build，也能从指定 Build 启动 agent。第一次配完，最直接的验证就是触发一次 Build 并确认它 Success。
确认失败不会污染现状。失败的 Build 不替换活跃 Build，agent 继续从最近一次成功的环境启动。
复现失败。文档给的办法是从失败的 Build 启动一个 agent，机器以失败时的状态打开，可以在里面看日志、改环境、跑一次测试 Build 再验证。
追溯用的是哪个 Build。每次 agent 运行都记录它从哪个 Build 启动，拿这个溯源就能把行为差异对上确切的配置与仓库 commit。
让 agent 自己查。文档提到可以通过内置的 Cursor Cloud MCP 让 Cloud Agent 检查和管理 Builds，并给了一段示例提示词：让它检查最近一次失败的 Build、修配置、跑测试 Build，在给出最终 install 与 start 命令前先验证。

最后一件常被忽略的事：文档建议在 AGENTS.md 里加一节 Cloud 专用的设置与测试说明，标题可以写成 Cursor Cloud specific instructions，变长就拆到别的文件再从这里引用。环境把机器准备好，AGENTS.md 告诉 agent 在这台机器上怎么做事——只配一半，另一半的问题就会以「它为什么不跑测试」的形式回到你身上。

本文依据 Cursor 官方文档（cursor.com/docs 与 cursor.com/help）于 2026-08-18 的公开内容整理。该产品闭源，本文只复述官方文档写明的机制，不推断其内部实现； 我们没有对文中涉及的功能做过实测，因此不涉及界面外观、操作手感与运行速度的任何描述。该产品迭代频繁，文中涉及的设置项与命令随版本变动，请以官方文档最新内容为准。本文不涉及订阅价格、额度与模型清单，相关信息请以官方定价与模型说明页为准。

安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。