云端环境

选择 Agent 运行的容器、网络与依赖。

Environment 定义了 Session 运行的容器模板：环境类型、网络策略、预装依赖、启动脚本和 metadata。你可以为不同场景创建不同的环境：严格隔离的安全审计环境、预装数据科学库的分析环境、或者开放网络的通用开发环境。

​

环境是什么

Environment 是 Session 的基础设施层：

• 环境类型 - cloud 表示云端托管容器，self_hosted 表示自托管执行环境
• 网络策略 - 控制容器的出站网络访问
• 依赖包 - 预装系统包、Python 包、Node.js 包
• 启动脚本 - 容器准备阶段、依赖安装完成后执行的用户脚本

每个 Session 启动时会基于指定的 Environment 模板创建隔离的运行实例。

​

字段说明

字段	类型	必填	说明
id	string	-	系统生成，env_ 前缀
type	string	-	固定为 "environment"
name	string	是	环境名称
description	string	否	描述信息，默认 ""
config	object	是	环境配置
config.type	string	是	环境类型："cloud" 或 "self_hosted"
config.networking	object	否	cloud 环境的网络策略
config.packages	object	否	cloud 环境的预装依赖包配置
config.setup_script	string	否	sandbox 准备阶段执行的 shell 脚本（最大 64 KB）
metadata	object	否	自定义 key/value metadata
archived_at	string|null	-	归档时间（ISO 8601），未归档时为 null
created_at	string	-	创建时间
updated_at	string	-	最后更新时间

​

Config 类型

config.type 可以是 "cloud" 或 "self_hosted"。

self_hosted 的 config 必须严格为：

{"type": "self_hosted"}

Self-hosted Environment 不会启动托管云端容器。外部 worker 通过 Work API poll、ack、heartbeat 和 stop 该 Environment 下的 Session work。

cloud 的 config 可以包含 networking、packages 和 setup_script。

​

网络策略

config.networking 支持三种请求模式，所有模式都必须使用对象格式（字符串简写如 "unrestricted" 不被支持，会返回 400）。

模式	值	说明
完全开放	{"type": "unrestricted"}	容器可以访问任意外部地址
受限	{"type": "limited", "allow_package_managers": true}	仅允许访问已知安全的公共服务和包管理器
白名单	{"type": "allowed_hosts", "allowed_hosts": [...]}	仅允许访问指定主机名

Cloud Environment 响应会包含以下 networking 字段。省略字段会按默认值返回。

字段	类型	默认值
type	string	limited
allowed_hosts	string 数组	[]
allow_package_managers	boolean	false
allow_mcp_servers	boolean	false

​

完全开放

{
  "config": {
    "type": "cloud",
    "networking": {"type": "unrestricted"}
  }
}

适用于需要下载依赖、访问外部 API 的通用开发任务。

​

受限模式

{
  "config": {
    "type": "cloud",
    "networking": {
      "type": "limited",
      "allow_package_managers": true
    }
  }
}

适用于不需要任意外网访问、但仍需通过包管理器拉依赖的任务。

​

白名单模式

{
  "config": {
    "type": "cloud",
    "networking": {
      "type": "allowed_hosts",
      "allowed_hosts": [
        "api.github.com",
        "registry.npmjs.org",
        "pypi.org"
      ]
    }
  }
}

适用于安全合规要求高的场景，精确控制可访问的外部服务。

​

预装依赖

通过 config.packages 指定容器启动时预装的依赖：

{
  "config": {
    "type": "cloud",
    "networking": {"type": "unrestricted"},
    "packages": {
      "apt": ["git", "build-essential", "libssl-dev"],
      "pip": ["pandas", "numpy", "scikit-learn"],
      "npm": ["typescript", "eslint", "prettier"]
    }
  }
}

包管理器	字段	说明
apt	packages.apt	Debian/Ubuntu 系统包
pip	packages.pip	Python 包
npm	packages.npm	Node.js 包

预装依赖会增加环境初始化时间。只添加确实需要的包，其余可在 Session 运行时按需安装。

​

启动脚本

config.setup_script 是一段在 sandbox 准备阶段、packages 安装完成之后执行的 shell 脚本，使用 /bin/bash -lc 解释器运行。常用于克隆代码、写配置文件、warmup 缓存等无法用 packages 表达的初始化步骤。

约束	值
类型	string
最大长度	64 KB
解释器	/bin/bash -lc
超时	10 分钟
执行时机	sandbox 准备阶段，packages 安装完成之后

# 创建一个会自动 clone 项目并预装依赖的环境
curl -s -X POST https://api.qoder.com/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "node-with-init",
    "config": {
      "type": "cloud",
      "networking": {"type": "unrestricted"},
      "packages": {
        "npm": ["pnpm@9"]
      },
      "setup_script": "set -euo pipefail\n[ -d /workspace/.git ] || git clone https://github.com/me/repo /workspace\ncd /workspace && pnpm install --frozen-lockfile"
    }
  }' | jq .

执行成功后会在沙箱内写入完成标记，本次 sandbox 内不会重复执行；沙箱被回收重建后会再次执行。脚本以非零状态退出会导致 Session 启动失败，错误响应中会带上 exit code 和 stderr 摘要。

​

创建环境

# 创建一个数据科学专用环境
curl -s -X POST https://api.qoder.com/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "data-science",
    "config": {
      "type": "cloud",
      "networking": {"type": "unrestricted"},
      "packages": {
        "apt": ["build-essential"],
        "pip": ["pandas", "numpy", "matplotlib", "scikit-learn", "jupyter"]
      }
    }
  }' | jq .

成功返回 200 OK：

{
  "id": "env_019e44eb66bb748cabcd1489f6fa4428",
  "type": "environment",
  "name": "data-science",
  "description": "",
  "config": {
    "type": "cloud",
    "networking": {
      "type": "unrestricted",
      "allowed_hosts": [],
      "allow_package_managers": false,
      "allow_mcp_servers": false
    },
    "packages": {
      "type": "packages",
      "apt": ["build-essential"],
      "npm": [],
      "pip": ["pandas", "numpy", "matplotlib", "scikit-learn", "jupyter"]
    }
  },
  "metadata": {},
  "archived_at": null,
  "created_at": "2026-05-18T10:00:00Z",
  "updated_at": "2026-05-18T10:00:00Z"
}

​

创建安全受限环境

# 创建一个仅允许访问内部 API 的安全环境
curl -s -X POST https://api.qoder.com/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "secure-internal",
    "config": {
      "type": "cloud",
      "networking": {
        "type": "allowed_hosts",
        "allowed_hosts": ["internal-api.mycompany.com", "git.mycompany.com"]
      },
      "packages": {
        "apt": ["git", "curl"]
      }
    }
  }' | jq .

​

查询环境

# 列出所有环境
curl -s https://api.qoder.com/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT"

# 获取单个环境详情
curl -s https://api.qoder.com/api/v1/cloud/environments/env_ds456 \
  -H "Authorization: Bearer $QODER_PAT"

​

更新环境

# 为已有环境添加新的依赖包
curl -s -X POST https://api.qoder.com/api/v1/cloud/environments/env_ds456 \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "data-science",
    "config": {
      "type": "cloud",
      "networking": {"type": "unrestricted"},
      "packages": {
        "apt": ["build-essential", "libpq-dev"],
        "pip": ["pandas", "numpy", "matplotlib", "scikit-learn", "jupyter", "sqlalchemy"]
      }
    }
  }' | jq .

更新环境不会影响已运行的 Session。新配置仅对后续创建的 Session 生效。

​

环境选型建议

场景	推荐配置
通用开发	default 环境，无需额外配置
数据分析	预装 pandas/numpy，开放网络
安全审计	白名单网络，最小依赖
前端开发	预装 Node.js 生态工具，开放 npm registry
CI/CD 集成	预装 git/docker CLI，白名单模式

​

常见问题

Q: 环境创建后需要等待多久才能使用？

A: 环境创建后可立即用于创建 Session。实际的容器初始化（包括安装依赖）发生在 Session 启动时。

Q: 预装包的版本可以指定吗？

A: pip 和 npm 包支持版本指定，如 "pandas==2.1.0" 或 "typescript@5.0.0"。apt 包使用系统源的默认版本。

Q: networking 设置错误导致 Agent 运行失败怎么办？

A: 创建一个新的环境（或更新现有环境），修改网络策略后重新启动 Session。

Q: 一个账号最多能创建多少个环境？

A: 无硬性限制，但建议按实际需求创建，避免管理混乱。建议通过命名规范分类。

​

下一步

启动 Session

将 Agent 和 Environment 组合，开始执行任务。

定义 Agent

回顾 Agent 配置。