《Cursor文檔》-雲端環境設置

Cursor文檔 Cursor Cloud Agent 2026-08-26 40 閱讀

雲端代理運行在隔離的 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。

Dockerfile 倉庫的 Computer Use 支持

對於基於 Debian/Ubuntu Linux 發行版的 Dockerfile 倉庫，支持 Computer use。如果你需要支持其他 Linux 發行版，請聯繫支持。

資源限制

每個雲端代理都運行在默認 VM 規格上，內存和 CPU 資源有限。如果您使用的是企業版方案，並且您的倉庫需要更多資源，請聯繫支持，我們可以提高您工作區的資源限制。

自助配置自定義資源即將上線。

安裝腳本

安裝腳本此前在儀表盤和文檔中稱爲更新腳本。

Cursor 創建 Build 時會運行安裝腳本 (即 environment.json 中的 install) 。該腳本會在後臺完成，不會延遲每次智能體啓動。

對於 Cursor 可提前準備的工作，請使用 install。例如安裝依賴項、生成代碼、編譯產物和預熱磁盤緩存。

安裝腳本可以通過智能體使用的同一本地套接字讀取智能體元數據，並簽發 OIDC 身份令牌。

安裝腳本冪等性

安裝腳本必須具有冪等性。它會在每個 Build 中運行，並且可能會在
已準備好的磁盤狀態下運行。

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。

Cursor 會使用 1 小時後過期的 STS 憑證來承擔該角色。
當智能體被喚醒時，Cursor 會刷新缺失、無效或將在 15 分鐘內過期的憑證。

如需與 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"
}

重要的路徑行爲

build 中的 dockerfile 和 context 路徑是相對於 .cursor 的。當
省略 context 時，其默認值爲 .cursor。.、./ 和 ..
會被特殊處理，表示代碼倉庫根目錄而不是 .cursor，因此如果要通過 COPY
使用不帶路徑的文件名複製位於 .cursor 中的文件，請省略 context。install
命令是從你的項目根目錄執行的。

完整的 schema 定義見此處。

運行 Docker

雲端代理支持 Docker 工作流。我們內部會將其用於運行多個服務的全棧倉庫。

對於簡單配置，安裝 Docker 通常就足夠了。一旦 Docker 已安裝並且守護進程已啓動，像 docker run hello-world 這樣的命令通常都可以正常運行。

Docker 運行於另一層容器之內，因此在 Cloud Agents 中會有一些邊界情況。簡單工作流通常可以正常工作。更復雜的配置應從下面的 fuse-overlayfs 和 iptables-legacy 配置開始。

對於較複雜的 Docker 用法，建議使用 fuse-overlayfs、iptables-legacy，並確保你的雲端智能體用戶可以運行 Docker。

複雜 Docker 配置推薦使用的 Dockerfile

########################################################
# DOCKER INSTALLATION
########################################################

# 安裝 Docker
RUN 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.json
RUN 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 ubuntu
RUN usermod -aG sudo ubuntu
# 爲 ubuntu 用戶配置免密 sudo
RUN 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 模式遵循這種方式。

用戶空間網絡無法讓 VM 顯示爲 tailnet 出口節點。

運行 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 創建的本地監聽器。

請將 tunnel token 和 Access 服務 token 機密信息保存在 Cursor 機密信息 中，而不是
代碼倉庫中。如果它們是爲概念驗證創建的，請在測試完成後進行
輪換。

相關文章

Cursor 3 多 Agent 架構：Planner/Worker 分工最高降本 15 倍 2026-07-29 Cursor 多 Agent 蜂羣用 1339 美元重建 SQLite：Planner/Worker 分層纔是 Agent 經濟學 2026-07-30 600 億美元收購 Cursor：SpaceX/xAI 要重塑 AI 編程工具格局？ 2026-07-31 Cursor 3 多 Agent 架構：Planner/Worker 分層如何將編碼成本降低 15 倍 2026-08-01 GitHub 爆火 Ponytail：讓 AI Agent 像「最懶的高級工程師」一樣寫代碼 2026-08-02
羽毛球分组比赛记分
小程序二维码

欢迎使用《羽毛球分组比赛记分》微信小程序

小夜