> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langbot.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 沙箱 (Sandbox)

> LangBot 沙箱（Box Runtime）为内置 Agent 提供隔离环境，安全地执行命令与读写文件。

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

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

## 内置工具

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

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

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

## 沙箱作用域

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

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

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

## 生命周期

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

## 快速开始

1. **准备后端**：本机装好 Docker，或选择 Nsjail / E2B
2. **写入 `config.yaml`**：
   ```yaml theme={null}
   box:
     enabled: true
     backend: 'local'
     local:
       host_root: './data/box'
   ```
3. **启动 LangBot**：沙箱自动启用
4. **在流水线里**选择内置 Agent + 支持函数调用的模型

之后 Agent 会自动获得六个工具。详细配置见[沙箱配置](./config)。

## 关闭沙箱

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

## 下一步

* [沙箱配置](./config) — 后端、安全预设、挂载、环境变量
* [运行时与扩展关系](./runtime-relationships) — 沙箱、Skills、MCP、插件如何分工