Cursor Cloud Agent 初始设置指南

很多人以为 Cursor Cloud Agent 的初始设置，就是打开 Cloud 模式随便发一句任务就行，其实根本不是。真正容易卡壳的地方有三个：团队还没连上 GitHub、仓库权限给得要么太宽要么太窄、环境跑通之后没存可复用的快照。把这三处一次性配好，后面再发任务，它才能直接拉仓库、装依赖、跑检查，最后把 Walkthrough 和代码差异都给你返回来。

先确认权限，明确设置终点

入口位置：先确认你能进 Cursor Dashboard 的团队空间，还有权在 GitHub 组织里装应用。主要动作：备好 Cursor 团队管理员权限、GitHub 组织管理员权限，再找至少一个用来验证的仓库；另外得确认这个仓库里有能重复跑的安装和测试流程。成功标志：Dashboard 里能看到 Integrations 选项，GitHub 组织允许安装 Cursor.com，目标仓库的默认分支、启动方法都清清楚楚。失败处理：缺任何一个管理员权限，就先找对应的管理员来连，别拿个人仓库临时绕开团队的权限边界。

设置到这一步的关键入口长这样：输入区上方已经选好了仓库、分支和 Cloud，下面会出现 Set up Agent 按钮。这时候先别急着提交任务，GitHub 连接对不对、仓库范围合不合适，还得一项一项核对清楚。

从团队仪表盘连接 GitHub

入口位置：登录 Cursor Dashboard，进到你要设置的目标团队空间，在左侧导航栏点开 Integrations。主要动作：找到 GitHub 连接板块，点 Connect；要是之前已经连过，就用 Manage Connections 检查下现有绑定对不对。成功标志：页面会跳转到 GitHub 的应用安装流程，要是已经连过，现有连接里能看到正确的 GitHub 组织。失败处理：看不到连接按钮的话，先核对当前进的团队空间对不对、你有没有 Cursor 管理员身份；别在个人设置页翻来覆去找团队集成，那儿根本没有。

怎么判断自己走对入口了？看左侧 Integrations 是不是已经选中，还有页面上有没有出现连接管理按钮。图里的 BugBot 是同一团队集成页里的功能区，不是 Cloud Agent 的设置终点，别搞错了。

选对要安装 Cursor.com 的 GitHub 组织

入口位置：从 Dashboard 发起连接后，GitHub 会打开 Install Cursor.com 页面。主要动作：在个人账号和组织列表里，选真正持有目标仓库的那个组织；要是组织旁边显示 Configure，就点进这个组织继续配置。成功标志：页面会进入该组织的 Install and Authorize 权限确认页，而不是跳回个人账号。失败处理：找不到目标组织的话，先检查当前 GitHub 账号有没有组织安装权限；要是只有普通成员权限，就得找组织管理员来操作。

这一步最关键的不是点得快，而是选对仓库的归属。个人账号和多个组织会同时列出来，要是选错了，回到 Cursor 也看不到团队项目。

只给 Cloud Agent 开它真正需要的仓库权限

入口位置：进到 GitHub 的 Install and Authorize 页面后，找到 Repository access 一栏。主要动作：在 All repositories 和 Only select repositories 之间选一个。第一次试用更推荐只勾一个验证仓库；真有统一管理需求的时候再扩大范围，选好后点 Install and Authorize 就行。成功标志：授权完成后会返回 Cursor Dashboard，GitHub 连接状态正常，Cloud 模式里能列出所有已授权的仓库。失败处理：仓库列表缺东西的话，先回到 GitHub App 设置里补选，别重复安装第二份连接；要是组织策略阻止安装，就交给 GitHub 管理员处理。

图里上方是全部仓库选项，下方是指定仓库选项。测试阶段把范围收窄到一个仓库，既容易判断权限有没有生效，也能减少把无关代码暴露给团队自动化流程的风险。

选环境设置方式，填好运行参数

入口位置：回到 Cloud 模式，选好仓库和分支，点 Set up Agent。主要动作：在引导式设置和 Dockerfile 两种方式里选一个。第一次接入可以先用引导式设置，照着页面填入环境变量和机密信息，再让 Cloud Agent 在共享终端里执行安装和启动；要是仓库已经有稳定的 Dockerfile，也可以用它来固定系统依赖和启动环境。成功标志：共享终端能正常拉代码、装依赖，还能执行仓库约定的启动或测试命令，机密字段不会以普通文本的形式出现在任务说明里。失败处理：依赖安装失败的话，先修正仓库的安装命令或者 Dockerfile；访问外部服务失败的话，检查变量名和机密是不是填全了，千万别把密钥直接写进仓库。

跑通环境，存好可复用快照

入口位置：引导式设置的共享终端装完依赖后，接着运行应用和最小验证命令。主要动作：得确保环境真的启动起来，还能生成可查看的演示、截图或者测试结果；确认没问题后选 Save this environment snapshot 就行。成功标志：结果区明明白白显示 setup is complete，能打开 Walkthrough 产物，也能看到保存环境快照的操作选项。失败处理：只有安装日志、没有可运行结果的话千万别保存；先补齐启动端口、构建命令或者测试依赖，再重新完成当前环境检查。

图的上方有完成说明和 Walkthrough，底部才是保存快照的按钮。先验收应用能正常运行再保存，能避免后面每个任务都从一个缺东少西的环境开始。

用首个小任务检查整条链路通不通

入口位置：回到 Cloud Agent 输入区，保持刚才选的仓库、分支和环境快照不变。主要动作：提交一个范围很小、能自动验证的任务，比如改一处文案然后运行现有测试。任务完成后依次查看 Walkthrough、测试输出、Diff 和提交列表，没问题再决定要不要 Mark as ready。成功标志：结果页能看到验证证据，Diff 里只包含预期文件，测试命令通过，分支指向正确的目标。失败处理：要是任务能改代码却没法验证，先补仓库的测试命令或者环境依赖；要是出现无关改动，就缩小任务描述并检查基础分支，别直接标记就绪。

图的左侧是任务说明、Walkthrough 和验证摘要，右侧是 Diff。两边都核对通过了，才说明仓库权限、环境快照、运行命令和结果回传已经连成了一条完整的链路。

初始设置完成检查清单

1. Cursor 团队管理员和 GitHub 组织管理员权限都已经确认到位。
2. Dashboard 的 Integrations 已经连对了 GitHub 组织，没有误用个人账号。
3. Repository access 只包含 Cloud Agent 当前需要用到的仓库。
4. Cloud 模式能列出目标仓库和分支，也能正常进入 Set up Agent。
5. 环境变量和机密信息是分开配置的，密钥没有写进代码仓库或者任务正文。
6. 共享终端能完成安装、启动和最小测试，运行结果可以正常查看。
7. 环境快照已经在验证通过后保存好了，后续任务不用再重复准备同一套依赖。
8. 首个小任务的 Walkthrough、测试输出、Diff 和分支目标都符合预期。
9. 6 张界面图都能正常打开，分别对应证明设置入口、集成入口、组织选择、仓库授权、快照保存和结果验收这几个环节。