配置沙箱模板和实例

连接 AI 助手

在智能体开发服务平台（AgentWorks）中，沙箱让智能体在受控环境中执行命令、处理文件和运行代码。沙箱是可选能力，不是智能体实例的默认运行边界。沙箱模板保存创建沙箱时使用的设置；沙箱实例是实际运行任务的环境。多个智能体实例选择同一个沙箱实例时，会共享其中的文件、环境变量和运行状态。

选择是否使用沙箱

先根据任务需要的执行方式选择路径，再决定是否创建沙箱资源。

需要的结果	选择	执行位置或共享结果
使用模型、知识、记忆或 Skill，或者使用平台内置、远程 MCP 或调用方工具	不配置沙箱	对应的 AgentWorks 服务、MCP Server 或接入方执行工具；Skill 本身不执行命令
每个智能体实例需要自己的命令、文件或代码环境	沙箱模板	创建每个智能体实例时分别准备沙箱
多个智能体实例有意共享工作区、配置和运行状态	现有沙箱实例	所有引用方共享文件、环境变量、凭证和清理操作
继续使用你自己的沙箱或容器中的依赖、文件和网络连接	用户工具包	你的应用接收工具请求，在自己管理的环境中执行并返回结果
每段会话或每次运行需要全新执行环境	用户工具包或远程 MCP 管理的外部环境	调用方或 MCP 服务管理创建、身份校验、复用和销毁；该环境不是 AgentWorks 沙箱

平台工具包由 AgentWorks 执行，外部 MCP 工具由 MCP Server 执行，用户工具由业务系统执行。添加这些能力不会创建或关联 AgentWorks 沙箱。需要比较工具执行位置时，参见根据任务选择能力和定义用户工具包。

选择文件系统功能、沙箱和对象存储

文件系统功能、沙箱和对象存储分别解决当前任务文件、命令执行和长期保存问题。先确定模型是否只需整理当前会话的文件、是否要运行命令，以及结果是否需要长期保存。文件系统功能的基本含义参见了解文件系统功能和工作文件。

方式	如何启用	适合	文件范围和保留方式
文件系统功能（未关联沙箱）	在智能体模板中开启 启用文件系统；新建模板默认开启	让模型通过智能体文件工具读取、整理或生成任务文件	文件按会话读写；新会话看不到上一会话创建的文件。需要跨会话保留时写入已批准的外部存储
沙箱工作目录	向智能体模板添加沙箱模板或实例；文件工具改用所关联沙箱的工作区	执行命令、代码和需要特定镜像或依赖的文件处理	使用同一沙箱资源的智能体共享工作区；保留时长以目标环境的实际配置为准
沙箱对象存储挂载	创建沙箱模板或实例时开启 存储挂载；可以单独使用，无需开启智能体模板的 启用文件系统	让沙箱访问企业自有的 S3 兼容对象存储	需要保留的写入应从对象存储控制台按完整路径重新下载并核对；并发写入前还应验证目标应用和对象存储的处理方式

在 文件系统 中开启 启用文件系统 后，模型可以使用智能体文件工具。未关联沙箱时，这些工具按会话读写文件，新会话看不到上一会话创建的文件；关联沙箱后，它们改为读写所关联沙箱的工作区。需要跨会话或运行环境保留文件时，请把文件写入已批准的外部存储。

OSS 或其他对象存储挂载由沙箱配置。访问挂载时，请把相应沙箱接入智能体，并按挂载的只读或读写设置操作。启用文件系统 只控制智能体文件工具；关闭后，沙箱命令仍可按运行环境权限创建本地文件。验证对象存储挂载时，请从对象存储控制台按完整路径重新读取测试对象。

只需要读取 Skill 说明和参考文件时，在智能体模板中开启文件系统并保留 read_file 即可，不需要为此添加沙箱；建议选择 仅只读。需要运行命令、使用特定环境或访问对象存储挂载时，再添加沙箱。选择沙箱模板时，每个智能体实例使用各自的沙箱；选择现有沙箱实例时，关联它的智能体共享工作区。分别在所选位置核对文件，并向管理员确认重启、替换或删除后的保留和清理方式。

选择沙箱模板或实例

默认选择 沙箱 - 模板：

• 选择 沙箱 - 模板 时，平台会为每个智能体实例创建一个沙箱。不同智能体实例不会共享其中的文件、挂载的 Skill 和运行状态。
• 选择 沙箱 - 实例 时，所有使用这个沙箱的智能体实例都会进入同一个工作区，共享文件、环境变量和运行状态。

只有多个智能体实例明确需要共享这些内容时，才选择现有沙箱实例；无法确认时，仍选择沙箱模板。新建会话不会创建新沙箱。需要不同 Skill、文件或凭证的智能体不要复用同一个现有沙箱实例。

确认沙箱适合当前任务

创建前，先确认两件事：任务需要在沙箱中运行命令或处理文件，并且当前租户已有可用的沙箱规格和环境。

区分沙箱和用户工具包

根据任务实际执行的位置选择能力：

• 使用 AgentWorks 提供的执行环境：配置沙箱模板或实例，使用其命令、文件和代码执行工具。
• 使用你自己的沙箱或容器：通过用户工具包，让你的应用接收工具请求，在对应环境中执行并返回结果。
• 已有提供 MCP 接口的执行服务：配置 MCP 连接，使用该服务提供的工具。

在同一个智能体模板中同时添加沙箱和用户工具包，不会让沙箱自动执行用户工具。这两种能力仍按各自的方式执行。

确认租户已有规格和环境

重要

仅限 AgentWorks 平台配置后台

创建或修改沙箱规格和沙箱环境，以及为租户分配沙箱规格，需要进入独立的平台配置后台。日常创建智能体的 AgentWorks 控制台只能选择已经分配给当前租户的规格和环境；没有合适选项时，请联系有后台权限的管理员。

普通用户创建沙箱模板时，只能选择平台管理员已经开放给当前租户的规格和环境。

有后台权限的管理员在平台配置后台完成以下工作：

• 在 沙箱规格管理 中设置沙箱类型、CPU、内存、磁盘、超时和网络限制。
• 在 沙箱环境管理 中准备镜像和工作目录。
• 在租户详情的 沙箱规格 中选择 配置沙箱规格，把规格分配给租户。

管理端环境页面中的 环境变量和启动参数目前显示为 暂不支持。需要其他配置时，请选择管理员已准备的环境，或联系管理员。管理员可参见管理沙箱资源。

理解沙箱模板启动类型

在用户控制台的 沙箱模板启动类型 中选择：

• Docker 容器
• Virtual Machine

该选项用于选择新沙箱的隔离类型：Docker 容器或虚拟机。冷启动或预热启动由管理员在沙箱规格中设置。

上线前确认启动、回收、保留和费用

Docker 容器或 Virtual Machine 表示隔离类型。上线前，请另行向平台管理员确认沙箱是否常驻、首次执行需要等待多久、空闲后是否回收、工作目录能保留多久，以及空闲期间是否计费。

沙箱在第一次工具调用时创建或分配运行环境。同一沙箱资源 ID 的运行环境仍可用时，后续工具调用可能继续使用该环境。沙箱隔离按资源划分，而不是按 AgentWorks 会话、调用任务或调用方划分；需要隔离文件、进程或凭证时，请使用不同的沙箱资源。

需要可预测的任务期限时，请让平台管理员提供目标环境实际生效的运行超时和空闲回收配置，并在应用层设置截止时间、取消处理和幂等恢复。规格页面中的数值仅供配置参考；资源释放和安全清理仍应使用组织规定的明确流程。

对于 Docker 沙箱，容器销毁时会自动移除容器，写在容器内部可写层中的文件随之消失。外部工作目录和对象存储挂载在清理时会被卸载，外部文件或对象继续由对应存储管理。判断运行环境销毁后的文件结果时，先确认路径属于容器内部、外部工作目录还是对象存储挂载。

为生产任务选择规格前，请让平台管理员确认：

• 冷启动或预热方式，以及首次执行的预期等待时间。
• 单次运行超时、空闲回收阈值和回收后的启动行为。
• 工作目录和进程能否跨空闲回收、重新启动或维护继续保留。
• 计费单位，以及启动中、运行中、空闲和预热资源分别如何计费。

费用规则以目标环境的计费说明或服务合同为准。需要长期保留的文件和结果应写入管理员确认的外部存储，并从存储端重新读取以验证结果。管理员应按说明沙箱如何启动、回收和计费说明规格中的磁盘、工作目录、启动、回收和计费方式。

警告

按实际环境配置管理任务期限

向平台管理员确认实际生效的运行超时和空闲回收时间，并在应用层设置任务截止时间。数据保留、锁释放和安全清理请使用各自的明确机制；一次观察到的回收时间只用于本次排查。

创建沙箱资源

沙箱实例可以直接选择规格和环境进行创建，不需要先创建沙箱模板。沙箱规格和环境仍需由管理员提前提供。

根据沙箱是否需要随智能体实例分别创建，选择创建模板、直接创建实例，或从模板预先创建实例。

操作账号需要有创建沙箱的权限，且租户已分配可用的沙箱规格和环境。

创建沙箱模板

当多个智能体实例需要相同的运行设置，但要分别使用自己的文件、环境变量和运行状态时，请选择沙箱模板。

1. 打开新建沙箱模板页面。

   创建沙箱模板

   也可从左侧导航进入 沙箱管理，选择 沙箱模板，再选择 新建沙箱模板。

2. 填写 名称和描述。

3. 选择 Docker 容器 或 Virtual Machine。

4. 在 资源规格 和 环境配置 中选择已开放的项目。

5. 在 环境变量 中配置模板变量。

6. 只把需要因智能体实例而变化的环境变量标记为 可配置。

7. 可选：按挂载对象存储配置企业自有存储。

8. 选择 创建沙箱模板。

仅在共享相同文件时创建沙箱实例

只有所有使用这个沙箱的智能体实例都可以共享相同文件、Skill、凭证和运行状态时，才使用此路径。任一项无法确认时，请创建沙箱模板。

确认共享沙箱实例的影响

选择现有沙箱实例后，所有使用这个沙箱的智能体实例都会进入同一个工作区。一个智能体写入的文件可能被其他智能体看到或修改；重启、清理和资源占用也会相互影响。文件能保留多久、运行环境是否会持续存在，取决于管理员提供的环境。

共享内容	用户可能遇到的问题
文件和输出	看到其他用户或任务创建的文件，或者自己的文件被覆盖、修改或删除
Skill、脚本和依赖	看到非预期的 Skill 集合，或者受到其他任务所做脚本和依赖变更的影响
执行状态和资源	并发任务争用 CPU、内存或磁盘；共享环境中留下的进程或中间状态影响后续任务
环境变量和凭证	使用这个沙箱的任务使用相同配置，写入其中的凭证不会按智能体分开
更新、重启和清理	一个智能体的变更、重启或清理中断其他任务，或者删除其他任务仍需使用的状态

同一租户中具有相应权限的用户，可以在不同智能体模板中选择同一个现有沙箱实例。由不同用户创建智能体，不会让沙箱内容自动分开。

注意

不支持不同 Skill 集合共享同一个沙箱实例

不支持让需要不同 Skill 集合的智能体复用同一个现有沙箱实例。共享沙箱只有一个 /skills 视图，不会按智能体合并或切换 Skill 文件。

例如，智能体 A 使用 Skill 1–3 并先初始化共享沙箱后，智能体 B 即使配置了 Skill 4–6，也可能仍只看到 Skill 1–3。

请选择 沙箱 - 模板，让每个智能体实例获得自己的沙箱。只有所有智能体实例都可以共享相同文件、Skill 集合和运行状态时，才选择 沙箱 - 实例。

直接创建或选择现有沙箱实例前，确认以下条件全部满足：

• 所有智能体使用相同的 Skill 集合和版本；需要执行 Skill 文件时，这些文件已经放入共享沙箱。
• 所有使用者都可以看到同一组输入文件、工作文件和输出。
• 所有智能体可以使用相同的环境变量、凭证和对象存储挂载。
• 修改文件、重启或清理沙箱可以同时影响所有智能体。
• 团队已经记录当前和计划使用这个沙箱的智能体，以及由谁负责变更、数据保留和清理。

任一项不满足或无法确认时，不要创建共享沙箱实例；请改为创建沙箱模板。

创建沙箱实例

通过共享检查后，可以直接创建一个供这些智能体共同使用的沙箱实例，无需先创建沙箱模板。

1. 打开新建沙箱实例页面。

   创建沙箱实例

   也可从左侧导航进入 沙箱管理，选择 实例，再选择 创建实例。

2. 选择类型、规格和环境。

3. 填写环境变量。

   直接创建实例时，不能把类型、规格、环境和环境变量保存为可供后续实例填写参数的模板。

4. 创建实例。

实例创建后，按准备命令、文件和运行依赖核对已有环境、命令和文件，再将沙箱接入智能体。

从模板创建实例

需要提前准备可供智能体关联的沙箱时，可以从现有模板创建实例，并填写本次使用的参数。

1. 选择沙箱模板。
2. 输入 实例名称和 描述。
3. 填写模板开放的参数。
4. 检查只读的规格和环境。
5. 选择 创建实例。

如果沙箱应随智能体实例动态创建，把沙箱模板添加到智能体模板，而不是提前手动创建所有沙箱实例。

预先从模板创建的沙箱实例，后续通过 沙箱 - 实例 关联时仍属于共享资源，也必须满足共享实例检查。

挂载对象存储

创建沙箱模板或实例时，可以展开 存储挂载，把企业自有的 S3 兼容对象存储映射到沙箱本地目录。AgentWorks 控制台支持阿里云 OSS 和火山引擎 TOS 凭证。

配置前准备：

• 取得把目标 Bucket 或指定子目录接入 AgentWorks 的许可，并确认允许读取或写入的准确范围。
• 创建只包含本次任务所需权限的对象存储凭证。只读任务不要授予写入或删除权限。
• 在授权范围内准备一个内容已知且不含敏感信息的读取测试对象。
• 需要读写时，另行准备一个可清理的测试目录或唯一对象名，并确定获准的清理方式。不要使用生产对象测试写入、覆盖或删除。
• 确认对象的版本、生命周期、备份、恢复、访问审计和费用由哪个存储所有者管理。

任一条件不满足时，先停止配置并让存储所有者补齐权限、测试数据或恢复方案；不要使用权限更大的共享凭证绕过准备工作。

1. 在 凭证管理 的 对象存储凭证 页签预先创建凭证，或者在存储挂载中选择新建凭证。新建的凭证会进入凭证管理列表供后续复用。

   请只在凭证配置中填写 AccessKey ID 和 Secret Access Key，不要粘贴到提示词、描述、聊天消息或测试对象中。

2. 在沙箱模板或实例表单中开启 存储挂载。

3. 选择一个对象存储凭证。在 AgentWorks 控制台的同一个沙箱表单中，所有挂载点共用这一凭证。

4. 为每个挂载点填写 Bucket、Bucket 子目录和沙箱内的本地目录；按需添加备注。

   • AgentWorks 控制台会自动为本地目录补齐开头的 /，最终保存为绝对路径。
   • 不能使用 /、/tmp、/skills 等系统或平台保留路径；在控制台中，多个挂载点的本地目录不能相同，也不能互为父子目录。
   • Bucket 名称不能填写 URL 或包含 /；Bucket 子目录不能包含 .. 或连续斜杠。

5. 保留默认的 只读，除非任务确实需要写入并已经验证最小权限、覆盖风险和并发行为。需要写入时改为 读写。

6. 按需添加挂载点，然后保存。

   在 AgentWorks 控制台中最多添加 10 个挂载点。保存前平台会使用所选凭证预检所有 Bucket；失败时根据页面给出的原因修正凭证、区域、Endpoint、Bucket 或网络访问。

保存挂载后，把该沙箱添加到智能体模板，创建或更新智能体实例，再按测试智能体实例选择网页版对话或实际接入方式，按下一节验证读取和写入。沙箱详情页中的 加载工具只用于查看沙箱提供的工具，不能代替对象存储挂载验证。对象存储挂载由沙箱配置，开启 启用文件系统不会创建挂载。

验证对象存储挂载

先在非生产沙箱中验证，再让生产智能体使用挂载。只读任务完成第 2 步后直接检查第 7 步；只有任务明确需要写入时，才执行第 3–6 步。

1. 在沙箱中列出挂载目录，读取准备好的非敏感测试对象，并将内容与已知值比较。

   预期结果是能够找到并完整读取该对象。

2. 对默认的 只读 挂载，在准备好的测试目录中尝试创建一个新对象。

   预期结果是写入被拒绝，并且 Bucket 中没有新增对象。出现异常时，按处理挂载验证失败恢复，不要继续读写验证。

3. 需要写入时，核对本次读写验证的覆盖风险、并发影响和外部费用。

   注意

   读写挂载不提供事务或锁

   读写挂载可能产生覆盖、并发写入和外部费用。AgentWorks 不把挂载声明为数据库事务、分布式锁或强一致文件系统。生产写入前，应使用目标应用和对象存储完成恢复、重复执行与并发测试。

4. 改用 读写，在准备好的测试目录中创建一个名称唯一、内容可识别的临时对象，再在当前沙箱中读取并核对内容。

5. 从对象存储端或全新替代沙箱重新读取同一对象，确认写入已经持久化。

   • 使用对象存储控制台或组织批准的客户端，按 Bucket、子目录和完整对象名重新列出并读取对象。
   • 无法使用这些工具时，创建不复用原工作目录的全新替代沙箱，挂载同一子目录并读取同一对象。

   危险

   独立读回成功后再确认写入成功

   读取成功且内容一致后，再把该对象记为已经持久化。两种方式都找不到对象时，把本次写入视为失败，停止后续业务步骤，不要用同一对象名覆盖或重试。

6. 确认路径和对象名仅属于本次测试后，按获准方式保留或清理临时对象，并确认原有对象未被修改。

   凭证未获删除权限时，由存储所有者处理该测试对象，不要扩大凭证权限。

7. 在沙箱运行记录和智能体实例的 Trace 中核对测试结果、目标沙箱和挂载目录。

   当前沙箱中的读回结果、Trace 和沙箱运行记录用于核对本次工具调用。对象是否已经持久化，请以第 5 步中对象存储端或全新替代沙箱的读取结果为准。

需要用固定合成数据验证只读规则、只读输入和读写报告，并从对象存储核对报告哈希时，参见构建订单与退款交付验收助手。

处理挂载验证失败

任一步出现以下结果时停止接入真实任务，并按对应路径恢复：

结果	停止条件和恢复操作
保存前的 Bucket 预检失败	不要创建或更新沙箱。按页面提示核对存储类型、区域、访问地址、Bucket、凭证权限和网络访问；修正后重新预检。
挂载已保存，但无法读取已知测试对象	不要扩大权限或改为读写。先核对沙箱资源、挂载目录、Bucket 子目录和测试对象名，再由存储所有者确认凭证的读取范围。
只读挂载成功写入	立即停止让智能体使用该沙箱，不要写入真实数据。确认已保存只读设置且测试使用的是目标沙箱；仍可写入时，保留运行记录并联系管理员处理。
读写挂载无法创建临时对象，或者外部存储中找不到新对象	把写入视为失败，不要接入生产写入，也不要修改已有对象。保留目标沙箱、Trace、运行记录和完整对象名，恢复到上一个已验证的只读挂载或配置，修正权限和路径后用新的临时对象重新验证。
无法确认临时对象的准确路径或归属	不要执行批量删除。记录测试时使用的 Bucket、子目录和唯一对象名，由存储所有者只清理确认属于本次测试的对象。

将沙箱接入智能体

创建沙箱资源后，还要把它添加到智能体模板，并确认环境中已有任务所需的命令、文件、运行时和依赖。

将沙箱添加到智能体模板

需要让智能体使用已准备好的沙箱运行命令或处理文件时，将沙箱资源关联到智能体模板，再创建或更新智能体实例。

1. 创建或编辑智能体模板，打开 插件配置。

2. 单击 添加插件。

3. 默认选择 沙箱 - 模板，再选择目标模板。只有已经完成共享实例检查时，才选择 沙箱 - 实例。

4. 按需设置模板开放参数，然后保存智能体模板。

5. 在智能体模板详情页的 插件 页签中确认沙箱类型、名称和资源 ID。

6. 更新使用沙箱模板的智能体实例前，检查并保留沙箱配置。

   • 保存需要保留的环境变量、挂载及其他配置。
   • 把需要长期保留的差异写回来源模板或开放参数。

   注意

   更新实例可能覆盖生成沙箱的配置

   通过沙箱模板生成的沙箱在智能体实例更新时会重新应用模板和实例参数，直接改动生成沙箱的配置可能被覆盖。

7. 创建或更新智能体实例。

8. 运行实际命令测试沙箱，确认工具可用性和外部文件读取结果。

准备命令、文件和运行依赖

让智能体读取 Skill 说明时，需要开启文件系统并保留 read_file。将 Skill 文件挂载到沙箱不会自动启用这个工具。

使用 Skill 脚本前，再确认文件如何进入沙箱：

• 智能体模板同时使用技能组和 沙箱 - 模板 时，新沙箱采用模板中的设置，平台会把所选版本的 Skill 文件以只读方式挂载到新沙箱的 /skills 目录。执行前，请列出该目录并找到目标 Skill；存在同名 Skill 时，目录名可能带有附加标识。
• 选择 沙箱 - 实例 时，如果智能体模板同时使用技能组，平台仍会把该智能体所选版本的 Skill 文件以只读方式挂载到这个沙箱的 /skills。

注意

共享沙箱的 Skill 文件可能被覆盖

共享沙箱只有一个 /skills 目录，后接入的智能体可能覆盖先前挂上的 Skill 文件。“只读”限制的是智能体对文件的修改，不代表后续挂载不会替换文件。需要不同 Skill 集合时，改用沙箱模板。

文件已经出现在沙箱中，不表示平台会自动运行脚本。智能体仍需调用沙箱工具执行文件，所需运行时和依赖也必须已经安装在环境中。

然后：

1. 选择已经包含所需命令、运行时和依赖的环境。

2. 配置正确的工作目录和环境变量。把输出写到可写工作目录，不要尝试修改 /skills。

   需要试改 Skill 脚本时，可以把所需文件复制到可写目录，保留相对目录结构，并使用副本路径运行。修改副本不会更新平台上的 Skill；要保存这些修改，参见维护 Skill。

3. 把沙箱模板或实例添加到智能体模板，并创建或更新智能体实例。

4. Skill 或技能组的版本选择发生变化后，先更新或重新创建非生产智能体实例，并核对实际文件，再更新生产实例。

5. 先运行一个只读、可预测的测试命令，再运行真实任务。

需要使用最终用户的业务凭证时，优先通过用户工具包或在沙箱外完成授权的 MCP 服务执行。确需向沙箱提供凭证时，应使用最小权限和最短有效期，并且不要让不应使用该凭证的智能体共享这个沙箱。

需要长期保留的文件和结果应写入已批准的外部存储。每次写入后，从对象存储控制台按完整路径重新读取，或者使用全新替代沙箱读取同一对象。沙箱工作目录只用于运行任务；目标环境另有数据保留说明时，按该说明管理副本和保留时间。

Skill 自动挂载只提供文件，不会执行脚本、安装依赖或注册工具。不要把 Skill ZIP 当作沙箱镜像或依赖安装包。测试时，请分别确认 Skill 已激活、文件已进入沙箱，以及沙箱工具已经执行文件。

选择沙箱隔离范围

先决定哪些智能体可以使用同一个工作区：

• 每个智能体实例需要自己的沙箱时，在智能体模板中选择沙箱模板。
• 多个智能体实例需要共享沙箱时，显式选择同一个现有沙箱实例。

API 接入不会为新会话、线程、调用任务或单次运行自动创建沙箱。

目标	是否支持	做法
每个智能体实例使用不同沙箱	支持	在智能体模板中选择沙箱模板
多个智能体实例共享沙箱	支持	显式选择同一个现有沙箱实例，并共同管理文件、Skill、配置和清理
每个渠道用户使用不同沙箱	间接支持	使用渠道模板绑定，让每位用户通过 /init 创建智能体实例，并让智能体模板选择沙箱模板
每个 API 用户或业务租户使用不同沙箱	不自动支持	为相应隔离范围分别准备智能体实例，并让每个实例通过沙箱模板获得沙箱
每段会话或线程使用新沙箱	不支持	使用新的业务会话标识或新建渠道会话不会创建、切换或清空沙箱
每个调用任务或单次运行使用新沙箱	不支持	新输入、中断响应或取消运行不会创建、切换或清空沙箱

注意

会话和调用任务不是沙箱边界

新建会话、更换渠道用户或 API 调用方，不会自动创建新的沙箱。多个最终用户使用同一个智能体实例时，仍使用该实例关联的沙箱。即使不同智能体实例来自不同用户，只要它们选择同一个现有沙箱实例，沙箱仍然共享。

API 返回的 context_key 标识会话，不是沙箱选择参数。wst_ Token 不能创建、绑定或删除沙箱，SendMessage 也不能指定沙箱。新建会话、开始新任务或取消运行都不会重建或清空沙箱。

为会话或调用任务使用外部隔离环境

每段会话或每次运行都需要全新执行环境时，请使用由业务系统管理的外部执行服务。通过 HTTP 与 WebSocket 接入的业务系统，可以通过用户工具包接收工具中断，并在外部服务中完成操作：

• 每段会话使用新环境：业务系统创建外部环境，记录它与已授权用户、业务会话和 context_key 的对应关系，并在业务会话结束或达到应用设定的有效期后销毁环境。
• 每次运行使用新环境：业务系统为本次运行创建外部环境，在运行结束、失败或超时后销毁环境。

这个外部环境不是 AgentWorks 沙箱，只用于执行用户工具。模型运行、平台工具包和已经关联的沙箱工具仍在原来的位置执行。

如果使用远程 MCP Server 管理外部环境，业务系统必须向它提供并校验可信的用户或会话标识。不要根据模型生成的环境 ID 选择执行环境。

如果工具必须在 AgentWorks 沙箱内运行，请提前分别创建智能体实例和沙箱。不能通过消息提交接口为每段会话或每次运行动态创建沙箱。

需要使用最终用户的业务凭证时，优先使用用户工具包或在沙箱外完成用户授权的 MCP 服务。不要把用户专用的原始凭证放入由其他用户或智能体实例共享的沙箱。

不同的沙箱资源 ID 只表示配置了不同沙箱，不表示外部账号、凭证、知识、记忆或业务权限已经自动隔离。资源 ID 也不能说明沙箱会持续运行多久或文件会保留多久。

运行测试并检查限制

上线前，请确认智能体调用了预期工具、沙箱实际执行了预期命令，并检查工具权限、网络和资源限制是否生效。

限制沙箱网络和资源

平台管理员可以在规格中配置带宽、私网地址出站控制、DNS 允许或拒绝列表、超时和空闲回收。生产规格应按最小权限开放网络，并为长任务设置合理超时。

这些控制属于规格。普通用户不能在每个沙箱模板中任意扩大管理员分配的资源或网络权限。

检查 Trace 和沙箱运行记录

检查两个位置：

• 在 Trace 中确认智能体调用了预期工具。如果使用 Skill，还要确认 Skill 已激活并读取了正确版本。
• 在 沙箱运行记录 中确认实际执行的命令和结果。

排查问题时，还要检查：

• 智能体实例是否运行。
• 沙箱实例和规格是否可用。
• 环境变量是否按实例参数生成。
• 网络策略是否允许目标地址。
• 智能体模板的 工具权限 是否按预期自动拒绝、自动批准或发出人工审批中断。

测试沙箱执行

把沙箱模板或实例添加到测试智能体模板，并创建一个非生产智能体实例。先验证命令能否执行，再按实际用途检查文件和访问范围。

1. 核对测试智能体实例关联的沙箱资源 ID。

   需要验证多个智能体的共享或独立关系时，再创建第二个测试实例：选择沙箱模板时，两个沙箱资源 ID 应不同；选择同一个现有沙箱实例时，ID 应相同。资源 ID 不能代替实际访问范围检查。

2. 核对沙箱运行环境和可用工具。

   确认规格、环境变量、所需命令和网络范围符合测试要求，并在沙箱实例详情中加载工具列表。

   注意

   沙箱没有单独的审批开关

   沙箱工具是否需要人工审批，由智能体模板的 工具权限 决定，不必为了测试沙箱临时开启审批。需要设置规则时，参见配置工具审批流程。

3. 检查测试所需的目录和文件。使用 Skill 时，先按技能组关联步骤启用文件系统、保留 read_file，再列出 /skills，核对目标 Skill 和所选版本的文件。

   多个智能体共用沙箱时，必须使用同一套 Skill；需要不同 Skill 集合时，改用沙箱模板。

4. 在 网页版对话 中选择测试实例，让它运行一个只读、可预测的沙箱命令，例如查看工作目录或列出测试目录。

5. 对照 Trace 和 沙箱运行记录，核对实际工具名称、参数、执行结果和目标实例。

   • 使用 Skill 时，还要确认 read_file 成功读取了目标 SKILL.md。读到说明或挂载了文件，不等于脚本已经执行。
   • 任务会向对象存储挂载路径写入文件时，还须从对象存储端重新读取，确认文件确实保存成功。

6. 按实际配置检查访问限制。

   注意

   使用虚构数据和非生产凭证

   以下检查只使用测试身份、虚构数据和非生产凭证。

   • 多人使用时，分别用应该能访问和不应该能访问的测试身份，确认数据和权限没有超出预期范围。
   • 配置了工具权限规则时，按验证审批流程检查实际用到的规则。
   • 配置了网络限制时，访问一个应被拒绝的测试地址，确认请求被拦截。

7. 确认文件和资源仅属于本次测试后，清理测试文件和不再使用的测试资源。

处理超时、网络和启动失败

• 启动慢：确认管理员规格是冷启动还是预热启动，并检查资源是否可用。
• 命令超时：比较任务时长、规格运行超时和智能体实例调用超时，不要只扩大其中一个值。
• 域名无法解析：检查规格的 DNS 允许和拒绝列表，拒绝列表优先。
• 私网地址不可达：检查 RFC1918 出站限制和例外 CIDR。
• 镜像或命令不存在：检查环境镜像、工作目录和镜像版本。
• 没有可选规格或环境：让管理员确认资源已分配给当前租户且类型匹配。

不要通过永久放开所有网络或取消所有超时来解决单次失败。

安全修改或删除沙箱

修改共享沙箱实例会影响所有使用它的智能体模板和智能体实例。生产清单应记录来源沙箱模板、实际沙箱资源 ID、规格、环境、使用它的智能体和清理负责人。

需要分阶段变更时，创建替代实例或模板，在测试智能体实例中验证后再切换生产引用。修改沙箱模板、规格或环境，不表示已经创建或正在运行的沙箱已经迁移；请核对受影响的资源 ID，并重复执行测试。

删除沙箱模板后，请在实例列表中检查并分别处理相关沙箱实例。删除沙箱实例前，先移除智能体模板和智能体实例引用，保留必要运行记录，并确认实例工作目录中没有仍需留存的数据。

仍被模板或实例引用的规格和环境不能删除。请先迁移所有引用，再执行删除。

变更对象存储挂载和凭证

已经通过独立读回验证的对象，由外部对象存储的保留策略管理。变更沙箱、挂载或凭证时，按以下顺序保护需要保留的对象：

1. 由存储所有者确认对象的保留、版本、备份、恢复、访问审计和后续清理方式。

2. 需要轮换 AccessKey 或 Secret Access Key 时，新建替代凭证并验证挂载。

   注意

   编辑现有凭证不能替换 AccessKey

   编辑现有凭证只能修改名称、区域和访问地址，不能替换存储类型或 AccessKey。

3. 轮换凭证时，迁移所有引用后再删除旧凭证。

4. 完成沙箱、挂载或凭证变更后，从对象存储重新读取需要保留的对象。