#文件沙盒（Sandbox）

把 AI 编程 CLI 安全地开放给半可信用户的隔离机制——常配合 Oncall 模式 一起用。

开了沙盒后，话题里的人让机器人改代码、跑命令，所有写操作都被隔离：真实文件一个字节都不会被改动；机器人却照常读取真实的项目 / 配置 / 登录态、原生干活（它根本不知道自己在沙盒里）。改完之后由 owner 审阅 diff 卡片，确认无误再「应用到磁盘」落回真实仓库，或直接丢弃。

适合把 oncall / 值班机器人开放给不完全信任的群成员、外部协作者：既让他们用 AI 改东西，又不怕真实仓库被误改、搞乱。

#它做什么 / 不做什么

一句话定位：这是「防误改 + 改动可审」的隔离，不是「防一切」的安全沙箱。它保证真实仓库不被沙盒里的写操作污染、且每一笔改动都要 owner 点头才落盘；它不阻止机器人读取本机文件或访问网络——敏感内容请用下面的屏蔽机制挡住。

#开启方式

前置要求：Linux（依赖 bubblewrap + overlayfs）。root / 非 root 都支持——root 用更快的内核 overlayfs，非 root 自动回退到 fuse-overlayfs。依赖（bubblewrap / fuse-overlayfs）在开启沙盒时自动安装，无需提前装；环境缺自动安装权限时会提示一条手动安装命令。Mac（sandbox-exec）在路线图上、暂未支持。

#方式一：bots.json

给某个 bot 加配置：

{
  "name": "oncall-bot",
  "cliId": "claude-code",
  "sandbox": true,                          // 开启文件沙盒
  // 可选：屏蔽不想让机器人读到的敏感路径（默认空 = 全部可读）
  "sandboxHidePaths": ["~/.ssh", "~/.botmux/bots.json"],
  // 可选：额外暴露只读路径
  "sandboxReadonlyPaths": ["/srv/source-snapshots/service-a"],
  // 可选：关闭沙盒内网络出口
  "sandboxNetwork": false
}

详见 bots.json 配置。

#方式二：Dashboard

进 Dashboard 的「Bot 配置」页，打开「文件沙盒」开关、保存即可。

按会话固化：开 / 关沙盒只对新话题生效。已经在跑的老会话保持原样——重启 daemon 不会把历史会话无脑拖进沙盒模式。

#落盘（/land）

机器人在沙盒里改完后，由 owner 在话题里发：

/land

会收到一张「沙盒改动落盘」卡片：

• 改动统计：N 个文件（+x / −y），以及落盘目标仓库路径
• diff 预览：项目相对路径 + 真实增删行；过长自动截断
• 完整 .patch 文件附件：可 git apply，适合大改动离线 / 逐行审阅
• 「应用到磁盘」/「丢弃」按钮：仅 owner 可点

点「应用到磁盘」→ 把隔离层里的改动集 git apply 回真实仓库；点「丢弃」→ 扔掉这次改动。应用之前真实仓库不受任何影响。

实测过最硬的场景：让沙盒里的机器人改了 botmux 自己的运行源码并重新编译，线上正在跑的进程毫发无损——改动全在隔离层，/land 后才落回。

#隐私屏蔽（sandboxHidePaths）

默认沙盒不限制读——机器人能看到本机所有文件。如果某些路径不想让半可信的 oncall 机器人读到（私钥、密钥配置、其它项目等），在 bots.json 里 per-bot 配置：

"sandboxHidePaths": ["~/.ssh", "~/.aws/credentials", "/etc/some-secret"]

被列的路径在沙盒里会被空目录 / 空文件遮罩。没有默认值——不配就是全可读（包括 bots.json）。按你对群成员的信任级别自行决定要挡哪些。

#额外只读路径（sandboxReadonlyPaths）

当机器人需要查看额外本地上下文、但不应该修改这些内容时，配置 sandboxReadonlyPaths：

"sandboxReadonlyPaths": ["/srv/source-snapshots/service-a", "~/docs/runbooks"]

每个已存在路径会以只读方式挂到沙盒里的同一路径（~ 会展开为家目录）；不存在的项会被忽略。适合共享源码快照、参考仓库、生成文档、运行手册等不应进入 /land 改动集的输入。

两条护栏：sandboxHidePaths 遮罩永远优先——与遮罩路径重叠的只读项不会重新暴露被隐藏的内容；等于或包含家目录 / 会话工作目录的项会被忽略并告警（否则会整体顶掉写隔离 overlay），工作目录之下的子路径不受影响。

#网络策略（sandboxNetwork）

默认沙盒保留网络访问，用于包安装、API 调用和 CLI 正常联网。配置：

"sandboxNetwork": false

会添加 --unshare-net，让 CLI 在无宿主网络的命名空间里运行。这个开关很硬：模型/API 访问、包管理器、git remote、代理都可能不可用，除非该 CLI 能完全依赖已经挂载好的本地输入工作。

#注意事项

1. 仅 Linux：依赖 bwrap + overlayfs（非 root 自动用 fuse-overlayfs，依赖开沙盒时自动装）；Mac（sandbox-exec）暂未支持。
2. 读不隔离：默认全可读，挡敏感凭证要主动配 sandboxHidePaths（见上）。
3. 网络默认开放：只有确认机器人能接受无网络 / 无代理时，才设置 sandboxNetwork: false。
4. build 产物会进改动集：如果机器人在沙盒里跑了 pnpm build / 编译，产物（如 dist/）也会出现在 /land 的改动集里。落盘前看清 diff，别把编译产物 apply 覆盖真实仓库。
5. 机器人无感：它看到的是 overlay 合并视图，以为改的就是真文件、照常工作；「隔离」对它完全透明。
6. botmux send 照常：沙盒里 botmux send 通过 daemon 中转正常发消息、附图、附件、自定义卡片 JSON（应用凭证不进沙盒环境）。

#配合 Oncall 起飞

文件沙盒 + Oncall 模式 是绝配：oncall 把机器人开放给一群人随时 @，沙盒保证这群人的改动不会动到真实仓库、且每笔改动 owner 审阅后才落盘。半可信、多人、随时改的 oncall 场景的标准搭配。