文件沙盒（Sandbox）是把 AI 编程 CLI 安全开放给半可信用户的隔离机制，常与 oncall 配合使用。开启后，话题里的人让机器人改代码、跑命令时所有写操作都被隔离，真实文件一个字节都不变；机器人却照常读取真实项目/配置/登录态原生干活（它感知不到自己在沙盒里）。改完由 owner 审阅 diff 卡片，确认无误再落盘，或直接丢弃。
一句话定位：这是「防误改 + 改动可审」的隔离，不是「防一切」的安全沙箱——它保证真实仓库不被沙盒写操作污染、每笔改动需 owner 点头才落盘，但不阻止机器人读取本机文件或访问网络。
能力边界
| 写隔离 | 所有写入（改/建/删文件、跑 build）落到隔离层，真实文件永不被修改 |
| 原生读 | 读到的是真实文件系统（真实项目、CLI 配置、代理 env），工具链开箱即用 |
| 登录态持久 | CLI 鉴权目录真实绑定，沙盒内登录/刷新 token 对真实生效 |
| 零拷贝省磁盘 | 基于 overlayfs，不 clone 项目，只有被改动的文件占额外磁盘 |
| 审阅后落盘 | owner 审 diff + patch 文件，确认再 git apply 回真实仓库 |
| 额外只读输入 | sandboxReadonlyPaths 可把兄弟仓库、文档快照等只读暴露给机器人 |
| 不隔离读 | 默认可读本机所有文件（含 bots.json、~/.ssh），需 per-bot 显式屏蔽 |
| 默认不隔离网络 | 默认可访问网络/代理；sandboxNetwork: false 进入独立网络命名空间 |
开启方式
前置要求：Linux（依赖 bubblewrap + overlayfs）。root 用内核 overlayfs，非 root 自动回退 fuse-overlayfs；依赖在开启沙盒时自动安装，无自动安装权限时提示手动命令。Mac（sandbox-exec）在路线图上，暂未支持。
方式一：bots.json（见 bots-json）：
{
"name": "oncall-bot",
"cliId": "claude-code",
"sandbox": true, // 开启文件沙盒
"sandboxHidePaths": ["~/.ssh", "~/.botmux/bots.json"], // 可选：屏蔽敏感路径
"sandboxReadonlyPaths": ["/srv/source-snapshots/service-a"], // 可选：额外只读路径
"sandboxNetwork": false // 可选：关闭沙盒内网络出口
}方式二：Dashboard「Bot 配置」页打开「文件沙盒」开关（见 dashboard）。
按会话固化：开/关沙盒只对新话题生效，已在跑的老会话保持原样；重启 daemon 不会把历史会话拖进沙盒模式。
落盘（/land）
机器人在沙盒改完后，由 owner 在话题里发 /land，会收到「沙盒改动落盘」卡片：
- 改动统计：N 个文件（+x / −y）与落盘目标仓库路径；
- diff 预览：项目相对路径 + 真实增删行，过长自动截断；
- 完整
.patch附件：可git apply，适合大改动离线逐行审阅； - 「应用到磁盘」/「丢弃」按钮：仅 owner 可点。应用前真实仓库不受任何影响。
实测最硬场景：让沙盒里的机器人改 botmux 自己的运行源码并重新编译，线上正在跑的进程毫发无损——改动全在隔离层，/land 后才落回。
三个配置项
sandboxHidePaths（隐私屏蔽）：被列路径在沙盒里以空目录/空文件遮罩。没有默认值——不配就是全可读（包括 bots.json 本身），按对群成员的信任级别自行决定挡哪些（如 ~/.ssh、~/.aws/credentials）。
sandboxReadonlyPaths（额外只读输入）：每个已存在路径以只读方式挂到沙盒同一路径（~ 展开为家目录），不存在的项被忽略。适合共享源码快照、参考仓库、运行手册等不应进入 /land 改动集的输入。两条护栏：
sandboxHidePaths遮罩永远优先——与遮罩重叠的只读项不会重新暴露被隐藏内容；- 等于或包含家目录/会话工作目录的项会被忽略并告警（否则会整体顶掉写隔离 overlay），工作目录之下的子路径不受影响。
sandboxNetwork（网络策略）：默认保留网络（包安装、API 调用、CLI 联网）。设为 false 会添加 --unshare-net，让 CLI 在无宿主网络的命名空间运行。开关很硬：模型/API、包管理器、git remote、代理都可能不可用，除非 CLI 能完全依赖已挂载的本地输入工作。
注意事项
- 仅 Linux：依赖 bwrap + overlayfs（非 root 自动用 fuse-overlayfs，依赖自动安装）；Mac 暂未支持。
- 读不隔离：默认全可读，挡敏感凭证要主动配
sandboxHidePaths。 - 网络默认开放：只有确认机器人能接受无网络/无代理时才设
sandboxNetwork: false。 - build 产物会进改动集：沙盒里跑
pnpm build/编译，产物（如dist/）也会出现在/land改动集。落盘前看清 diff，别把编译产物 apply 覆盖真实仓库。 - 机器人无感：它看到的是 overlay 合并视图，以为改的就是真文件；隔离对它完全透明。
botmux send照常：沙盒里通过 daemon 中转正常发消息/附图/附件/自定义卡片 JSON（应用凭证不进沙盒环境）。
与 Oncall 的组合
文件沙盒 + oncall 是标准搭配：oncall 把机器人开放给一群人随时 @，沙盒保证这群人的改动不会动到真实仓库，且每笔改动 owner 审阅后才落盘——半可信、多人、随时改的值班场景的标配。