zh usage sandbox readme

沙箱 (Sandbox)

沙箱给内置 Agent 一个隔离的执行环境：跑命令、读写文件、运行长驻进程。日常 Agent 应用（数据处理、文件操作、运行用户代码、托管 stdio MCP）都依赖它。

启用沙箱后，内置 Agent 会自动获得六个工具，无需在流水线里逐项开启。

内置工具

工具	用途
exec	在沙箱内执行 Shell 命令
read	读取工作区文件
write	创建或覆盖文件
edit	字符串替换式修改文件
glob	按 glob 模式查找文件
grep	按正则搜索文件内容

exec 在沙箱容器内运行；其余五个直接读写主机映射到 /workspace 的目录。

Note

这些工具面向内置 Agent。使用 Dify、n8n、Langflow、Coze 等外部 Runner 时，请使用对应平台自己的工具机制。

沙箱作用域

在流水线 AI 配置中可选择沙箱在不同消息间如何共享。默认"每个会话"足够大多数场景使用。

作用域	模板	共享范围
全局	{global}	所有用户共用一个沙箱
每个会话（默认）	{launcher_type}_{launcher_id}	同一群/私聊共用
每个用户	{launcher_type}_{launcher_id}_{sender_id}	群里每位成员独立
每个对话	{launcher_type}_{launcher_id}_{conversation_id}	按对话隔离
每条消息	{query_id}	完全无状态

Warning

同一作用域内的命令共享文件系统状态。需要完全隔离请选"每条消息"。

生命周期

情况	行为
空闲超过 5 分钟	自动清理
有 Box 托管进程（如 stdio MCP）在跑	不清理，进程结束后才释放
配置 persistent: true	永不自动清理

快速开始

1. 准备后端：本机装好 Docker，或选择 Nsjail / E2B
2. 写入 config.yaml：

   box:
     enabled: true
     backend: 'local'
     local:
       host_root: './data/box'

3. 启动 LangBot：沙箱自动启用
4. 在流水线里选择内置 Agent + 支持函数调用的模型

之后 Agent 会自动获得六个工具。详细配置见沙箱配置。

关闭沙箱

设置 box.enabled: false。所有依赖沙箱的能力（内置工具、Skill 创建/编辑/激活、stdio MCP）会一并停用；http/sse 模式的 MCP 不受影响。

下一步

• 沙箱配置 — 后端、安全预设、挂载、环境变量
• 运行时与扩展关系 — 沙箱、Skills、MCP、插件如何分工