为了提供基于云的代码分析、执行和调试，云端智能体需要在你的活动会话期间临时存储和处理与会话相关的代码、配置和对话上下文。为此，你需要配置自定义云端运行环境。

该功能适用于需要在云端隔离环境中运行代码、管理项目依赖或与 AI 协作进行复杂调试等场景。这解决了本地环境不一致、资源受限等问题，让你能随时随地在统一的云端环境中进行开发和调试。

适用范围

自定义云端环境配置仅可在 Code 模式中使用。

配置自定义云端运行环境

操作步骤

1. 在界面左下角，点击 头像 > 设置，进入设置中心。
2. 在左侧导航栏中，选择 云端运行环境。
   你将进入云端环境配置面板。
3. 在面板右上角，点击 创建 按钮。
   页面上显示云端环境配置窗口。
   
4. 配置云端环境，然后点击 确认 按钮。
   参数说明如下：

配置详解

运行环境配置

预装依赖提供了一个可复现、可分发的应用运行环境模板。它把应用运行所需的一切打包在一起，使应用能够在任何支持容器的平台上以一致的方式运行。

• 基础容器镜像
  TraeWork 官方构建并维护了一个 all-in-one 通用容器镜像，其中预装了常见的工具链和语言生态系统。

• 预装语言和版本
  通过 preinstalled_packages 配置项目所需的编程语言版本。
  预装包中包含的语言和版本如下：

需注意：

• 若未手动指定语言的版本，则默认使用最新版本。
• 你可以通过 GET /api/v1/environment_configs/supported_versions 获取最新支持的版本列表。
• 手动指定的版本必须为 TraeWork 支持的版本（参考上表）。

敏感变量 vs 环境变量

敏感变量和环境变量用于存储敏感信息和普通配置参数。两者的区别如下：

使用建议：

• 敏感信息（如密码），使用敏感变量来存储。
• 普通配置（如开关、日志级别），使用环境变量来存储。

运行时配置

在运行时配置中，你可以通过脚本来自定义环境的安装和启动过程。

• 参数说明

• 使用场景和示例
  • 场景 1：简单项目（单一服务）
    适用于前端项目、简单 API 服务。例如：

    {
        "install": "npm install",
        "start": "npm run dev"
    }
    

  • 场景 2：全栈项目（多服务）
    适用于需要同时启动多个服务的项目。例如：

    {
        "install": "npm install && pip install -r requirements.txt",
        "terminals": [
            {"name": "Frontend", "command": "npm run dev"},
            {"name": "Backend", "command": "uvicorn main:app --reload"}
        ]
    }
    

  • 场景 3：开发辅助（监控任务）
    适用于需要持续运行测试或类型检查的项目

    {
        "install": "npm install",
        "start": "npm run dev",
        "terminals": [
            {"name": "Test Watcher", "command": "npm run test:watch"},
            {"name": "Type Check", "command": "npm run typecheck -- --watch"}
        ]
    }
    

• 脚本执行时机和顺序
  install、start 和 terminals 脚本的执行时机和顺序如下：

  环境启动
      │
      ▼
  ┌─────────────────────────────────────┐
  │ 1. 执行 install 命令                │  ← 阻塞等待，必须完成后才继续
  │    (安装项目依赖)                    │
  └─────────────────────────────────────┘
      │
      ▼
  ┌─────────────────────────────────────┐
  │ 2. 执行 start 命令                  │  ← 后台运行，不阻塞
  │    (启动主进程)                      │
  └─────────────────────────────────────┘
      │
      ▼
  ┌─────────────────────────────────────┐
  │ 3. 打开 terminals                  │  ← 并行打开所有终端
  │    (启动辅助服务/监控任务/测试/DB)     │
  └─────────────────────────────────────┘
      │
      ▼
    环境就绪
  

  需注意：
  • install 失败会阻断后续步骤。
  • start 和 terminals 都是长时间运行的进程。
  • 所有 terminals 并行启动，无先后顺序。

网络策略配置

网络策略用于控制沙箱的网络访问权限。

目前，你可以通过配置 network_policy 对象来限制出站流量，仅允许环境访问指定的常用依赖源。该配置块为固定模式，参数说明如下：

完整示例

一个完整的云端运行环境配置示例如下：

{
    "name": "Full Stack Dev Environment",
    "description": "React + FastAPI 全栈开发环境",
    "preinstalled_packages": {
        "python_version": "3.12",
        "node_version": "20"
    },
    "runtime_config": {
        "install": "npm install && pip install -r requirements.txt",
        "start": "npm run dev",
        "terminals": [
            {
                "name": "Backend Server",
                "command": "uvicorn main:app --reload --port 8000",
                "description": "FastAPI 后端服务"
            },
            {
                "name": "Test Runner",
                "command": "pytest --watch",
                "description": "Python 测试监听"
            }
        ]
    },
    "secrets": {
        "API_KEY": "your_api_key", // 替换成实际 API Key
        "DB_PASSWORD": "your_db_password" // 替换成实际密码
    },
    "environment_variables": {
        "DEBUG": "true",
        "LOG_LEVEL": "info"
    },
    "network_policy": {
        "mode": 1,
        "allowlist_policy": 0,
        "common_dependencies": ["npm", "pypi", "github"]
    }
}

使用自定义云端运行环境

使用限制

自定义云端运行环境只能在 Code 模式中使用。

操作步骤

• 网页版
  TraeWork 网页版中的任务皆在云端环境中运行。因此，与 AI 对话前，你可以直接在对话框的右下方选择所需的自定义云端运行环境。
  
• 桌面版
  TraeWork 桌面版支持本地环境和云端环境。使用云端运行环境的步骤如下：
  1. 打开一个从 GitHub 拉取的远程项目。
  2. 在对话输入框左下角，将运行环境设置为 云端。
  3. 在对话输入框左下角，选择所需的自定义云端运行环境。