沙箱给内置 Agent 一个隔离的执行环境：跑命令、读写文件、运行长驻进程。日常 Agent 应用（数据处理、文件操作、运行用户代码、托管 stdio MCP）都依赖它。
启用沙箱后，内置 Agent 会自动获得六个工具，无需在流水线里逐项开启。
内置工具
| 工具 | 用途 |
|---|
exec | 在沙箱内执行 Shell 命令 |
read | 读取工作区文件 |
write | 创建或覆盖文件 |
edit | 字符串替换式修改文件 |
glob | 按 glob 模式查找文件 |
grep | 按正则搜索文件内容 |
exec 在沙箱容器内运行；其余五个直接读写主机映射到 /workspace 的目录。
这些工具面向内置 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} | 完全无状态 |
同一作用域内的命令共享文件系统状态。需要完全隔离请选”每条消息”。
生命周期
| 情况 | 行为 |
|---|
| 空闲超过 5 分钟 | 自动清理 |
| 有 Box 托管进程（如 stdio MCP）在跑 | 不清理，进程结束后才释放 |
配置 persistent: true | 永不自动清理 |
快速开始
- 准备后端：本机装好 Docker，或选择 Nsjail / E2B
- 写入
config.yaml：
box:
enabled: true
backend: 'local'
local:
host_root: './data/box'
- 启动 LangBot：沙箱自动启用
- 在流水线里选择内置 Agent + 支持函数调用的模型
之后 Agent 会自动获得六个工具。详细配置见沙箱配置。
关闭沙箱
设置 box.enabled: false。所有依赖沙箱的能力（内置工具、Skill 创建/编辑/激活、stdio MCP）会一并停用；http/sse 模式的 MCP 不受影响。
下一步
