# 更新工作区沙箱配额

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

更新有管理权限的工作区沙箱配额及临时沙箱自动分配策略。设置上限不会删除已有资源。

```text
PATCH https://api.moi.matrixorigin.cn/v5/agent-sandboxes/quota
```

## 调用前准备

准备目标工作区的个人访问令牌与相应操作权限；环境、令牌、工作区和沙箱 ID 保持一致。[公共对象和结果确认](objects.md)说明资源身份、字段及状态。示例的资源值须替换为实际值。

## 请求

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

```bash
curl -X PATCH "https://api.moi.matrixorigin.cn/v5/agent-sandboxes/quota" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  --data-binary '{"max_managed_count":0,"auto_ephemeral":"inherit"}'
```

:::::
:::::{tab-item} 参数说明

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `max_managed_count` | integer | 否 | 0～100；0 可用于停止继续分配托管沙箱。 |
| `max_ephemeral_count` | integer | 否 | 0～100；临时沙箱分配上限。 |
| `auto_ephemeral` | string | 否 | inherit、enabled 或 disabled，分别继承部署设置、启用或禁用自动临时分配。 |

至少提交一个有效字段；省略或 null 保持原值，显式 0 必须保留。请求字符串策略与响应数值 override 使用不同表示，见字段表。更改上限只影响后续准入，不是终止或删除当前沙箱的操作。

:::::
::::::
:::::::

## 成功响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "workspace_id": "workspace-example",
    "max_managed_count": 0,
    "max_ephemeral_count": 10,
    "auto_ephemeral_override": 0,
    "updated_by": "user-example",
    "updated_at": "2026-11-11T08:00:00Z"
  }
}
```

:::::
:::::{tab-item} 字段说明

HTTP 200 的数据含义如下；示例值不是默认配置。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功时为 OK。 |
| `msg` | string | 响应说明。 |
| `data.workspace_id` | string | 当前工作区 ID。 |
| `data.max_managed_count` | integer | 保存的托管上限。 |
| `data.max_ephemeral_count` | integer | 保存的临时上限。 |
| `data.auto_ephemeral_override` | integer | 0 继承、1 显式启用、2 显式禁用。 |
| `data.updated_by` | string | 最后更新者 ID。 |
| `data.updated_at` | string | 更新时间，RFC 3339。 |

:::::
::::::
:::::::

## 结果确认

检查返回配置与[当前托管占用](get-quota.md)。override:0 仅表示继承，不能单凭它判断部署默认自动策略的最终值。

## 错误处理

按 HTTP 状态及响应 code 判断；[公共错误与恢复](objects.md#错误与恢复)区分参数、权限、配额、提供商和结果未知。错误不证明尚未产生资源，也不能当成重试或清理已经完成。
