创建一个新的云端执行环境,用于托管 Agent 会话。
POST /api/v1/cloud/environments
创建一个新的云端执行环境,用于托管 Agent 会话。
请求头
| 头部 | 必选 | 说明 |
|---|---|---|
Authorization | 是 | Bearer <PAT 或 SAT> |
Content-Type | 是 | application/json |
x-qoder-beta | 条件 | 当 config 中包含 storage.buckets 时必填,值为 oss-bucket-2026-09-23 |
请求体
| 字段 | 类型 | 必选 | 说明 |
|---|---|---|---|
name | string | 是 | 非空环境名称 |
description | string | 否 | 环境描述 |
config | Environment config | 否 | Environment 配置;省略时默认为 {"type":"cloud"} |
metadata | Metadata 对象 | 否 | 自定义元数据,省略时为 {} |
config.storage.buckets 中声明的自有 OSS bucket 会挂载到 Session 的 /mnt/buckets/<name>。字段、凭证、授权和权限策略见 挂载自有 OSS Bucket(Beta)。
示例请求
示例请求:带初始化脚本
示例响应
HTTP 200 OK
响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 环境唯一标识,前缀为 env_ |
type | string | 资源类型,固定值 "environment" |
name | string | 环境名称 |
description | string | 环境描述 |
config | Environment config | Environment 配置 |
metadata | Metadata 对象 | 自定义元数据 |
archived_at | string|null | 归档时间(ISO 8601),未归档时为 null |
created_at | string | 创建时间(ISO 8601 格式) |
updated_at | string | 最后更新时间(ISO 8601 格式) |
错误码
| HTTP | type | 说明 |
|---|---|---|
| 400 | invalid_request_error | 缺少必填字段 name |
| 400 | invalid_request_error | config 或 metadata 字段值不合法 |
| 400 | invalid_request_error | config.setup_script 不是字符串或长度超过 64 KB |
| 400 | invalid_request_error | config.startup_script 不是字符串或长度超过 64 KB |
| 400 | invalid_request_error | config.storage.buckets 不合法、缺少 x-qoder-beta 请求头,或保存时试挂被拒绝 |
| 401 | authentication_error | 认证失败,PAT 或 SAT 无效或过期 |
| 403 | permission_error | 无权执行此操作 |
| 503 | feature_not_available | 账号不满足 oss_bucket Beta 资格 |
| 503 | api_error | 保存时 OSS / STS 暂时不可用,可重试 |