创建沙箱实例
更新时间:2026-11-17
接口描述
基于指定模板创建一个新的沙箱实例。支持通过 clientToken 请求头实现幂等创建。
API Explorer
去调试
您可以在 API Explorer 中直接运行该接口,运行成功后可自动生成 SDK 代码示例。
请求结构
Plain Text
1POST /sandboxes HTTP/1.1
2Host: api.sandbox-execute.bj.baidubce.com
3Authorization: authorization string
4Content-Type: application/json
5clientToken: clientToken string
请求头域
除公共头域外,支持以下头域:
- Authorization:必需。IAM API Key(Bearer bce-v3/ALTAK-...)或 AK/SK 签名(bce-auth-v1/...)。
- clientToken:可选。幂等 Token,1~64 位 ASCII 可打印字符,非法返回 400。同一账号、同一 templateID、同一 clientToken 的重复请求返回同一个沙箱;前一个请求仍在创建时,后续请求最多等待 60 秒,仍未完成返回 409。
请求参数
| 参数名称 | 类型 | 是否必需 | 参数位置 | 描述 |
|---|---|---|---|---|
| templateID | String | 是 | RequestBody参数 | 沙箱模板 ID,支持 templateID:tag 格式指定模板的某个 tag 版本。 |
| timeout | Integer | 否 | RequestBody参数 | 沙箱空闲超时时间,单位秒。不传或 0 为 300;最大 604800;-1 为永久沙箱。 |
| metadata | Map<String,String> | 否 | RequestBody参数 | 沙箱标签。以 baidubce_ 开头的键为平台保留键并做校验,例如 baidubce_cpuCores(1~16)、baidubce_memoryGb(1~64)覆盖模板规格,baidubce_sandboxGraceTime(0~60 分钟)、baidubce_persistenceMode(snapshot 或 data_persistence)、baidubce_dataPersistenceSizeGb(5~4096);baidubce_securityGroupId 与 baidubce_enterpriseSecurityGroupId 互斥,设置 baidubce_subnetId 时两者必选其一。 |
| envVars | Map<String,String> | 否 | RequestBody参数 | 沙箱环境变量。 |
| secure | Boolean | 否 | RequestBody参数 | 是否开启数据面鉴权。为 true 时返回 envdAccessToken,访问沙箱需携带该令牌;否则 envdAccessToken 为空字符串。 |
| allow_internet_access | Boolean | 否 | RequestBody参数 | 是否允许沙箱访问公网。 |
| allowInternetAccess | Boolean | 否 | RequestBody参数 | allow_internet_access 的驼峰写法(E2B 兼容,已废弃),两者同时传入且取值不同时返回 400。 |
| network | SandboxNetworkConfig | 否 | RequestBody参数 | 沙箱出网策略(域名级白名单 / 黑名单)。规则非法时返回 400,策略下发失败时沙箱会被删除并返回错误。 |
| autoPause | Boolean | 否 | RequestBody参数 | 超时后是否自动暂停(而非删除),默认 false。 |
| autoResume | SandboxAutoResumeConfig | 否 | RequestBody参数 | 暂停后的自动恢复配置,仅在 autoPause 为 true 时生效。 |
| runtimeType | String | 否 | RequestBody参数 | 运行时类型,可选 kata,不传为默认 CRIU 运行时。仅白名单账号可指定 kata,否则返回 400。 |
| mcp | Map<String,Object> | 否 | RequestBody参数 | 沙箱的 MCP 配置。 |
| volumeMounts | List |
否 | RequestBody参数 | 挂载到沙箱的 NFS 卷列表,最多 10 个。kata 运行时或多容器模板不支持,携带时返回 400。 |
返回状态码
成功返回 201。请求参数非法返回 400;模板不存在或模板无可用构建返回 404;clientToken 相同的请求仍在创建中返回 409(带 Retry-After: 5);超过创建频率限制或沙箱配额返回 429(频率限制时带 Retry-After: 30);认证失败返回 403。
返回头域
除公共头域外,无其他特殊头域。返回 409 或 429 时可能携带 Retry-After(单位秒)。
返回参数
| 参数名称 | 类型 | 描述 |
|---|---|---|
| sandboxID | String | 新建沙箱实例 ID。 |
| templateID | String | 模板 ID,与请求中的 templateID 一致(含 :tag)。 |
| alias | String | 模板别名,即不含 tag 的模板 ID。 |
| clientID | String | 客户端 ID,已废弃,固定为空字符串。 |
| domain | String | 沙箱访问根域名。账号开通 VPC 私有访问时为 VPC 根域名。 |
| envdAccessToken | String | envd 访问令牌,仅 secure 为 true 时非空。 |
| envdVersion | String | envd 版本号。 |
请求示例
Plain Text
1POST /sandboxes HTTP/1.1
2Host: api.sandbox-execute.bj.baidubce.com
3Authorization: authorization string
4Content-Type: application/json
5clientToken: 1849ef6b-f73c-4f5d-b88b-259ca47af849
6
7{
8 "templateID": "openclaw-lite",
9 "timeout": 3600,
10 "metadata": {
11 "app": "agent"
12 },
13 "envVars": {
14 "FOO": "bar"
15 },
16 "secure": true,
17 "allow_internet_access": true,
18 "network": {
19 "allowOut": ["*.baidubce.com"]
20 },
21 "autoPause": true,
22 "autoResume": {
23 "enabled": true
24 },
25 "volumeMounts": [
26 {
27 "name": "data",
28 "path": "/mnt/data"
29 }
30 ]
31}
响应示例
Plain Text
1HTTP/1.1 201 Created
2Content-Type: application/json
3
4{
5 "sandboxID": "xaf6kcuqt8808tkt04o2",
6 "templateID": "openclaw-lite",
7 "alias": "openclaw-lite",
8 "clientID": "",
9 "domain": "sandbox-execute.bj.baidubce.com",
10 "envdAccessToken": "xxxxxxxx",
11 "envdVersion": "0.1.4"
12}
评价此篇文章
