Skip to main content

Command Palette

Search for a command to run...

Agent

云端环境设置

云端代理运行在隔离的 Ubuntu 机器上。请配置环境，使智能体拥有开发者会使用的相同仓库、工具、依赖项、机密信息和网络访问权限。

在你的 Cloud Agents 仪表盘 中创建一个新环境。

什么是云端代理环境？

云端代理的开发环境与您笔记本电脑上的环境类似：包括已克隆的仓库、已安装的依赖项、机密信息、启动命令以及网络访问。

高效的开发环境会为代理提供有关您的代码库和组织的完整上下文，使其能够测试并验证其工作。

为什么环境配置很重要？

智能体的能力取决于其运行环境。一个能编写代码，却不能运行测试、查询服务或访问 API 的智能体，无法完成整个工作闭环。

要从头到尾完成工程任务，云端代理需要一个配置完善的开发环境，其中包含实现自主高效工作所需的全部仓库、工具、依赖项和上下文。

开发环境也能让智能体会话更高效。Build会在后台准备仓库、工具和依赖项，让智能体启动时即可使用准备就绪的机器。

环境设置是提升云端代理效能的最重要步骤。

环境设置选项

为你的云端代理配置环境主要有两种主要方式：

  1. 让 Cursor 的智能体通过 Cloud Agents 仪表盘 自行设置环境。智能体会安装依赖项、验证环境，并创建其首个 Build。
  2. 使用 Dockerfile 手动配置环境。如果选择此选项，你可以在 .cursor/environment.json 文件中指定 Dockerfile。

这两种方式都允许你指定安装脚本。Cursor 会在创建 Build 时运行该脚本，确保智能体启动前依赖项已准备就绪。

多仓库环境

当智能体需要跨多个代码仓库工作时，请使用多仓库环境。创建环境时，选择多个仓库。Cursor 会将每个选定的仓库克隆到智能体所在的机器上，并将该环境复用于后续使用同一仓库群组的智能体运行和自动化。

当前端、后端、基础设施或共享库位于不同仓库中时，多仓库环境会很有用。智能体可以检查整个工作区、协同进行更改、跨仓库运行测试，并在其修改过的仓库中发起 PR。

你可以访问 Cloud Agents 仪表盘中的环境配置页面，查看当前处于活动状态的环境，以及所有过去处于活动状态的版本。

环境解析顺序

Cursor 会按代码仓库或仓库群组解析环境配置，并使用第一个匹配项：

  1. 代码仓库中的 .cursor/environment.json
  2. 个人保存的环境
  3. 团队保存的环境

这样，团队层面可以有可预测的默认值；同时，当代码仓库级别不存在 .cursor/environment.json 时，个人用户仍可通过个人环境进行覆盖。用户覆盖也便于在向整个团队推广之前，先测试新的环境配置。

智能体驱动的设置 (推荐)

Cursor 可以在不到 10 分钟内在云端完成开发环境设置。你可以从 Cloud Agents 仪表盘 或 Cursor 桌面应用中的 代理窗口 启动引导式设置。

系统会要求你连接 GitHub、GitLab、Azure DevOps 或 Bitbucket 账户，并选择一个或多个仓库。

接着，你需要向 Cursor 提供安装依赖和运行代码所需的环境变量及机密信息。

在智能体工作时，你可以在共享终端会话中查看其进度，同时它会处理安装依赖等设置任务。Cursor 会在验证代码并成功完成 Build 后保存该环境。

后续 Cloud Agents 将从当前 Build 开始，并可通过运行你的软件来测试更改。将配置提交到 .cursor/environment.json，让整个团队都能从中受益。

使用 Dockerfile 手动配置 (高级)

对于高级场景，可通过 Dockerfile 配置环境：

  • 创建一个 Dockerfile，用于安装系统级依赖、指定特定的编译器版本、安装调试器，或切换基础操作系统镜像
  • 不要 COPY 整个项目；Cursor 会管理工作区并检出正确的提交
  • 直接编辑 .cursor/environment.json 以配置运行时设置
  • 如需使用私有包注册表或构建时凭证，请使用构建机密信息

以下是一个 .cursor/environment.json 示例，其中引用了 .cursor/Dockerfile (相对路径) 和 custom_script.sh 安装脚本：

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

如果你的仓库需要 Docker、Tailscale 或 Cloudflare Tunnel，请参阅下方的运行 Docker、运行 Tailscale和运行 Cloudflare Tunnel。

你可以通过 Dockerfile 配置环境；无法直接访问远程机器。

Dockerfile 构建使用层缓存。更改 Dockerfile 时，Cursor 只会重新构建发生变更的层，而不是从头重新构建每一层。

Cursor 配置的 Dockerfile (私测)

对于不想从头编写 Dockerfile 的团队，Cursor 可以为你配置一个。在设置过程中，Cursor 会检查你的仓库，识别工具和依赖项，并生成一个基于 Dockerfile 的环境配置，供你编辑和进行版本管理。

此流程目前面向企业版团队开放私测。要申请访问权限，请联系你的 Cursor 账户代表，或使用你的团队管理员账户发送电子邮件至 hi@cursor.com。

资源限制

每个云端代理都运行在默认 VM 规格上，内存和 CPU 资源有限。如果您使用的是企业版方案，并且您的仓库需要更多资源，请联系支持，我们可以提高您工作区的资源限制。

自助配置自定义资源即将上线。

安装脚本

安装脚本此前在仪表盘和文档中称为更新脚本。

Cursor 创建 Build 时会运行安装脚本 (即 environment.json 中的 install) 。该脚本会在后台完成，不会延迟每次智能体启动。

对于 Cursor 可提前准备的工作，请使用 install。例如安装依赖项、生成代码、编译产物和预热磁盘缓存。

Build 如何使用安装脚本

Cursor 基于环境的基础镜像，克隆仓库并运行 install 脚本直至完成。Build 成功后会保存生成的磁盘状态，并成为当前活动 Build。新的智能体会从当前活动 Build 启动。

确保脚本能够完成全部设置。耗时的设置应放在 install 中，因为它在智能体请求之前运行，而不是在启动时运行。pnpm install 等命令仍可复用已准备好的状态，只更新发生变化的依赖项。

Build 仅保留磁盘状态。正在运行的进程、导出的 shell 变量和内存缓存不会延续到智能体运行中。使用 start 或 terminals 启动服务。

环境配置恢复

构建失败不会替换当前活跃的 Build。您排查失败原因并创建替代 Build 时，智能体仍会从最近一次成功构建的环境启动。

打开环境的 Builds 标签页，查看日志、从失败的 Build 启动智能体，或选择其他成功的 Build。有关 Build 控制和调试，请参阅 Cloud Agent Builds。

如何确定安装脚本中应包含哪些内容

将所有可重复执行的准备步骤放入 install，包括完整安装依赖、生成代码、编译构建产物，以及其他会将可复用结果写入磁盘的操作。

不要将长时间运行的进程放入 install。将 Docker、数据库、隧道和开发服务器配置为启动命令。对于智能体仅在特定任务中需要的服务，还可以在 AGENTS.md 中添加说明。

启动命令

智能体从 Build 启动后，Cursor 会运行 start 命令，然后运行配置好的 terminals。可使用它们启动在智能体运行期间需要持续运行的进程。

在很多仓库中可以省略 start。如果你的环境依赖 Docker，请在 start 中添加 sudo service docker start。

terminals 用于运行应用代码进程。这些终端在你和智能体共享的 tmux 会话中运行。

在 AGENTS.md 中添加云端专用说明

云端代理会读取 AGENTS.md 文件。我们建议为仅针对云端的设置和测试添加一个专门的小节，标题例如可使用 Cursor Cloud specific instructions。

如果该小节内容变得较多，我们建议引用其他文件来提供针对具体任务的详细说明。更多信息请参见我们的 AGENTS.md 文档。

环境变量和机密信息

为了像人类开发者那样完整地运行和测试代码，云端代理通常需要环境变量，以及 API 密钥、数据库凭证等机密信息。

推荐：在 Cursor 设置中使用“机密信息选项卡”

管理机密信息最简单的方式是在 cursor.com 上进行。这些机密信息会以环境变量的形式提供给云端代理。

如需了解不同类型的机密信息，请参阅我们的机密信息文档。如需在不使用长期密钥的情况下授予云角色访问权限，请参阅 OIDC 身份令牌。

环境作用域机密信息

当某项凭据应仅对使用某一环境的 agents 可用时，请使用环境作用域机密信息。这对于多仓库环境、预发布环境凭据或访问需求不同的仓库群组非常有用。

环境作用域机密信息适用于该环境中的所有仓库。其他环境无法使用它们。

登录凭据和 2FA

如果您的应用需要登录，请将您本地使用的相同凭据添加为机密信息，例如用户名、电子邮件和密码。

如果您的登录流程使用基于 TOTP 的 2FA，也请将 TOTP 密钥 (有时称为共享密钥或根密钥) 添加为机密信息。智能体可以使用 oathtool --totp -b "$TOTP_SECRET" 生成当前的 6 位验证码。

含有多个 .env 文件的 monorepo

如果你的 monorepo 中有多个 .env.local 文件：

  • 将所有 .env.local 文件中的值添加到同一个 Secrets 选项卡
  • 当 key 重复时，使用不同的变量名，例如 NEXTJS_* 和 CONVEX_*
  • 根据需要在各个应用中引用这些变量

如果你在创建 snapshot 时包含了 .env.local 文件，它们可能会被保存下来，并可供云端代理使用。出于安全性和管理方面的考虑，仍然推荐使用 Secrets 选项卡。

使用 AWS IAM 角色

Cursor 支持承担客户提供的 IAM 角色，以便与 AWS 进行更深度的集成。这样，你就可以向云端代理授予特定的 AWS 权限，而无需共享长期凭证。

  1. 创建 IAM 角色：在你的 AWS 账户中，创建你希望云端代理承担的 IAM 角色，并记下其 ARN (例如 arn:aws:iam::123456789012:role/acmeRole) 。

  2. 配置 IAM 角色机密信息：前往 Cursor Dashboard → Cloud Agents，添加一个名为 CURSOR_AWS_ASSUME_IAM_ROLE_ARN 的用户或团队机密信息，并将其值设为你创建的 IAM 角色 ARN。

  3. 生成外部 ID：这一步必须由团队管理员在团队设置的 Advanced 部分完成。前往 Cursor Dashboard → Settings → Advanced，找到 External ID 设置。如果你没有看到外部 ID，请在 "AWS IAM Role ARN" 字段中输入一个占位值，点击 "Validate & Save"，然后重新加载页面。这样会为你的团队生成一个外部 ID (例如 cursor-xxx-yyy-zzz) 。

  4. 配置 IAM 角色信任策略：在你的 AWS 账户中，更新 IAM 角色的信任策略，使其信任 Cursor 的角色承担方。该信任策略应如下所示：

{  "Version": "2012-10-17",  "Statement": [    {      "Sid": "AllowCursorAssume",      "Effect": "Allow",      "Principal": {        "AWS": "arn:aws:iam::289469326074:role/roleAssumer"      },      "Action": "sts:AssumeRole",      "Condition": {        "StringEquals": {          "sts:ExternalId": "cursor-xxx-yyy-zzz"        }      }    }  ]}

将 cursor-xxx-yyy-zzz 替换为为你的团队生成的外部 ID。

环境变量：

配置完成后，Cursor 会设置以下环境变量，让 AWS 工具使用 cursor-cloud-agent 配置文件：

  • AWS_CONFIG_FILE 指向由 Cursor 管理的 AWS 配置文件
  • AWS_PROFILE 设置为 cursor-cloud-agent
  • AWS_SDK_LOAD_CONFIG 设置为 1

使用默认凭证链的 AWS CLI 和 AWS SDK 会在执行设置命令时以及智能体运行期间自动使用此配置文件。你无需自行导出 AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY 或 AWS_SESSION_TOKEN。

如需与 AWS STS AssumeRoleWithWebIdentity、GCP、Azure 或其他 OIDC 验证器联合，请从智能体 VM 签发 OIDC 身份令牌，而不要存储长期云密钥。

在代码中通过 environment.json 进行配置

如果你希望在代码中定义环境配置，可以将 .cursor/environment.json 提交到你的代码仓库中。

Build 会使用环境默认分支中的配置。若要在功能分支中更改配置，请提交并推送配置，然后在该分支上启动智能体。Cursor 会在当前活跃 Build 的基础上检出所请求的分支；如果分支更改了依赖项，智能体可以重新运行安装命令。

基于快照的 environment.json 示例 (快照 ID 可从仪表盘的 environments 页面获取)：

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

下面是一个 .cursor/environment.json 示例，其中引用了 .cursor/Dockerfile (相对路径) 和 custom_script.sh 安装脚本：

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

完整的 schema 定义见此处。

运行 Docker

云端代理支持 Docker 工作流。我们内部会将其用于运行多个服务的全栈仓库。

对于简单配置，安装 Docker 通常就足够了。一旦 Docker 已安装并且守护进程已启动，像 docker run hello-world 这样的命令通常都可以正常运行。

Docker 运行于另一层容器之内，因此在 Cloud Agents 中会有一些边界情况。简单工作流通常可以正常工作。更复杂的配置应从下面的 fuse-overlayfs 和 iptables-legacy 配置开始。

对于较复杂的 Docker 用法，建议使用 fuse-overlayfs、iptables-legacy，并确保你的云端智能体用户可以运行 Docker。

######################################################### DOCKER INSTALLATION######################################################### 安装 DockerRUN install -m 0755 -d /etc/apt/keyrings && \    curl --retry 3 --retry-delay 5 -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg && \    chmod a+r /etc/apt/keyrings/docker.gpg && \    echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \    $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null && \    apt-get update && \    apt-get install -y \    docker-ce=5:28.5.2-1~ubuntu.24.04~noble \    docker-ce-cli=5:28.5.2-1~ubuntu.24.04~noble \    containerd.io \    docker-buildx-plugin \    docker-compose-plugin \    && rm -rf /var/lib/apt/lists/*RUN apt-get update && apt-get install -y fuse-overlayfs && rm -rf /var/lib/apt/lists/*RUN mkdir -p /etc/docker && \    printf '%s\n' '{' \    '  "storage-driver": "fuse-overlayfs"' \    '}' > /etc/docker/daemon.jsonRUN apt-get update && apt-get install -y iptables && rm -rf /var/lib/apt/lists/*RUN update-alternatives --set iptables /usr/sbin/iptables-legacy && \    update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy######################################################### CONFIG UBUNTU USER######################################################### 确保禁用密码身份验证RUN echo 'PasswordAuthentication no\nChallengeResponseAuthentication no\nUsePAM no' > /etc/ssh/sshd_config.d/disable_password_auth.conf# 创建非 root 用户（仅在不存在时）RUN id -u ubuntu &>/dev/null || useradd -m -s /bin/bash ubuntu# 创建 docker 组（如不存在）并将 ubuntu 用户添加到该组RUN groupadd -f docker && usermod -aG docker ubuntuRUN usermod -aG sudo ubuntu# 为 ubuntu 用户配置免密 sudoRUN echo "ubuntu ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/ubuntu# 为 ubuntu 用户设置密码RUN echo "ubuntu:ubuntu" | chpasswd

运行 Tailscale

Tailscale 在云端代理 VM 的默认网络模式下无法正常工作。请改用用户态网络模式。

这样，智能体就可以通过你的 tailnet 访问私有服务和数据存储，而无需将这些服务暴露到公共互联网。

使用以下命令启动 tailscaled：

tailscaled --tun=userspace-networking \  --outbound-http-proxy-listen=localhost:1054 \  --socks5-server=localhost:1055

然后，在要让流量通过 Tailscale 的 shell 中导出这些代理变量：

export ALL_PROXY=socks5h://localhost:1055/export HTTP_PROXY=http://localhost:1054/export HTTPS_PROXY=http://localhost:1054/

之后，像平常一样运行 tailscale up ... 即可。

如果你想要一个可行的参考方案，有些客户已成功使用 tailscale-orb，因为它的 Docker 模式遵循这种方式。

运行 Cloudflare Tunnel

Cloudflare Tunnel 可在 云端代理 VM 中运行，因为 cloudflared 在用户态运行。

当 云端代理 需要访问 VPC 或内网中的私有 HTTP 服务时，请采用以下模式：

  • 在你的环境 Dockerfile 或安装脚本中安装 cloudflared。
  • 在你的私有网络中运行一个 cloudflared 连接器。
  • 通过隧道将已认证的主机名 (如 vpc.example.com) 路由到私有源站。
  • 如果你的环境使用受限出站访问，请将该主机名添加到 云端代理 网络允许列表中。
  • 将 Cloudflare Access 服务 token 值存为 Cursor 机密信息。例如，使用 CF_ACCESS_CLIENT_ID 和 CF_ACCESS_CLIENT_SECRET。

随后，云端代理 就可以通过常规 HTTPS，并携带 CF-Access-Client-Id 和 CF-Access-Client-Secret 请求头来调用该私有服务。连接器会主动建立到 Cloudflare 的出站连接，并将请求转发到你的私有源站。你的服务和数据存储会保留在你的私有网络中，连接器无需开放入站端口。

对于私有 TCP 服务 (例如数据库) ，请配置 Cloudflare TCP Access 应用，并在启动命令中运行 cloudflared access tcp。将你的应用或测试命令指向 cloudflared 创建的本地监听器。