云端环境 - Qoder CN

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

环境是什么

Environment 是 Session 的基础设施层：

容器类型 — 目前支持 cloud（云端托管容器）
网络策略 — 控制容器的出站网络访问
依赖包 — 预装系统包、Python 包、Node.js 包

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

字段说明

字段	类型	必填	说明
`id`	string	—	系统生成，`env_` 前缀
`type`	string	—	固定为 `"environment"`
`name`	string	是	环境名称
`description`	string	否	描述信息，默认 `""`
`config`	object	是	环境配置（类型、网络、包）
`config.type`	string	是	容器类型，当前固定为 `"cloud"`
`config.networking`	object	否	网络策略；必须为对象，可选值为 `{"type": "unrestricted" \| "limited" \| "allowed_hosts"}`
`config.packages`	object	否	预装依赖包配置
`status`	string	—	环境状态：`ready`
`archived`	boolean	—	是否已归档，默认 `false`
`archived_at`	string\|null	—	归档时间（ISO 8601），未归档时为 `null`
`created_at`	string	—	创建时间
`updated_at`	string	—	最后更新时间

网络策略

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

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

`networking` 对象字段

字段	类型	说明
`networking.type`	string	网络策略类型：`unrestricted` / `limited` / `allowed_hosts`
`networking.allow_package_managers`	boolean	`limited` 模式下是否允许包管理器（pip / npm / apt 等）访问
`networking.allowed_hosts`	array	`allowed_hosts` 模式下允许的主机名列表

完全开放

{
  "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 运行时按需安装。

创建环境

# 创建一个数据科学专用环境
curl -s -X POST https://api.qoder.com.cn/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 .

成功返回 201 Created：

{
  "id": "env_019e44eb66bb748cabcd1489f6fa4428",
  "type": "environment",
  "name": "data-science",
  "description": "",
  "config": {
    "type": "cloud",
    "networking": {"type": "unrestricted"},
    "packages": {
      "apt": ["build-essential"],
      "pip": ["pandas", "numpy", "matplotlib", "scikit-learn", "jupyter"]
    }
  },
  "status": "ready",
  "archived": false,
  "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.cn/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.cn/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT"

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

更新环境

# 为已有环境添加新的依赖包
curl -s -X PUT https://api.qoder.com.cn/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 生效。

删除环境

# 删除自定义环境
curl -s -X DELETE https://api.qoder.com.cn/api/v1/cloud/environments/env_ds456 \
  -H "Authorization: Bearer $QODER_PAT"

当 environment 仍被未归档的 session 引用时，DELETE 返回 409 "Environment is in use and cannot be deleted"。需要先归档/删除引用方 session，或改用 POST /environments/{id}/archive 软删（无引用约束）。

环境选型建议

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

常见问题

Q: 环境创建后需要等待多久才能使用？A: 环境创建后状态直接为 ready，可立即用于创建 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 配置

​环境是什么

​字段说明

​网络策略

​networking 对象字段

​完全开放

​受限模式

​白名单模式

​预装依赖

​创建环境

​创建安全受限环境

​查询环境

​更新环境

​删除环境

​环境选型建议

​常见问题

​下一步