代码沙箱

代码沙箱是 Clouisle 的隔离执行环境，用于在工作流、Agent 和工具中运行用户提供的 Python 与 JavaScript 代码。每个任务都在独立的运行环境中启动，只挂载当前任务的工作目录，并由超时、输出限制与磁盘配额约束失控任务。

隔离方式

• 一次任务一个隔离环境：任务运行在全新的隔离空间中，看不到宿主机的其他进程、文件或网络配置，也不会复用上一个任务的临时文件。
• 系统目录只读：系统运行时和依赖目录以只读方式挂载，任务不能修改系统二进制、已安装依赖或系统配置。
• 只有工作目录可写：任务只能写入自己的 /workspace 目录及其临时目录；任务结束后临时目录随任务清理，会话过期后整个工作目录自动清理。
• 进程随任务回收：任务超时或被取消时，沙箱内启动的所有子进程一起结束，不会残留在后台。
• 独立的运行环境：任务只拿到经过过滤的进程环境，而不是平台的完整环境。

沙箱不会静默降级为「无隔离执行」：隔离环境启动失败时任务直接失败，而不是退回到宿主进程运行。

支持的运行时

官方部署的沙箱镜像预装中日韩字体，使用 matplotlib、seaborn、Pillow 生成图表时可以正常显示中文，不会出现方块乱码。

使用场景

• 代码工具：在管理后台能力 > 代码中创建可复用的代码工具，安装精确固定版本的依赖并声明 /workspace 下的产物，保存后供 Agent 和工作流调用（见自定义 HTTP 与代码工具）。
• 工作流代码节点：在工作流图中直接嵌入代码，接收输入变量并把结果传给下游节点（见工作流节点）。
• Agent 调用：Agent 通过函数调用触发代码工具，由模型根据任务需要决定何时运行。

执行边界

每个任务都受以下限制，实际生效值取任务配置与调用方超时中先到的一个：

调用方还有一层独立超时：直接执行代码的默认超时为 30 秒，Agent 对话中调用代码工具的外层上限为 60 秒。已保存工具的超时优先于调用时传入的值，两边谁先到期谁生效：沙箱内超时表现为「执行超时」，外层超时表现为「工具调用超时」。

产物路径必须位于 /workspace 内，写到其他位置会被拒绝。单个产物默认上限 10MB，产物总量默认上限 10MB。

出站网络

沙箱出网由设置 > 安全中的沙箱出口白名单控制，与同一页面的出站网络白名单是两套独立策略：把内网主机加入出站网络白名单不会放行沙箱。

• 只接受精确主机名，大小写不敏感；通配符、IP 地址和网段在保存时被拒绝。
• 默认放行 pypi.org、files.pythonhosted.org、pypi.python.org、registry.npmjs.org；最多 200 条，重复项去重。
• 空白名单阻断全部外网。任务只能通过 HTTPS 的 443 端口访问名单内主机，HTTP、其他端口和直接访问 IP 都被拒绝。
• 自定义 Python 包索引与 Node 源必须使用 HTTPS，主机名必须在名单内。
• 修改后对下一个任务生效，无需重启服务；已运行的任务保持启动时的策略。
• 关闭沙箱出口白名单只影响新任务：新任务可以访问任意目标、协议与端口；文件系统隔离、超时、磁盘与输出限制不随开关关闭。名单保留，重新开启即恢复。

读取策略失败时按「空白名单」处理，即阻断全部外网。宿主或集群层面的网络策略仍是外层兜底。

宿主与节点要求

沙箱依赖宿主或节点允许创建隔离的进程空间。官方部署已按特权方式运行沙箱节点，通常不需要调整节点内核；自定义部署如果无法启动隔离环境，任务会全部失败并提示无法创建命名空间。这类问题属于节点内核或安全配置，处理方式见故障排查。

失败与排查

• 执行超时：任务在超时时间内没有结束，输出可能不完整；缩小输入或调高工具的超时配置。
• 输出被截断：标准输出或标准错误超过上限，末尾会出现截断标记；调试时把关键信息写到产物文件。
• 产物未生成：确认写入路径在 /workspace 内，且单个文件与总量都没有超过上限。
• 无法安装依赖：包源主机不在沙箱出口白名单内，或使用了 HTTP。改用 HTTPS 并让管理员添加主机名。
• 任务直接失败而不是降级：隔离环境不可用时不会退回无隔离执行，属于部署问题，按故障排查检查沙箱节点。

参见：

• 工具与 Skills — 内置工具与沙箱边界
• 自定义 HTTP 与代码工具 — 配置代码工具
• 工作流节点 — 代码节点集成
• 自托管架构 — 沙箱节点与部署要求