初次接触 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。两侧均核对通过后，才说明仓库权限、环境快照、运行命令和结果回传已连成一条完整的链路。
初始设置完成检查清单
- Cursor 团队管理员和 GitHub 组织管理员权限均已确认到位。
- Dashboard 的 Integrations 已正确关联 GitHub 组织，未误用个人账号。
- Repository access 仅包含 Cloud Agent 当前需要用到的仓库。
- Cloud 模式能列出目标仓库和分支，也能正常进入 Set up Agent。
- 环境变量和机密信息分开配置，密钥未写入代码仓库或任务正文。
- 共享终端能完成安装、启动和最小测试，运行结果可正常查看。
- 环境快照已在验证通过后保存，后续任务无需重复准备同一套依赖。
- 首个小任务的 Walkthrough、测试输出、Diff 和分支目标均符合预期。
- 6 张界面图均能正常打开，分别对应设置入口、集成入口、组织选择、仓库授权、快照保存和结果验收等环节。
