本文要点
- 结论先行：AI Agent 文件隔离的核心是边界可声明、越界可检测、污染可回滚——不是禁止写文件，而是禁止「写到别人的目录里」。
- 工程上推荐三层叠加：路径白名单（工具级）→
git worktree（仓库级）→ 独立 HOME/云 Mac 节点（主机级）。 - 同机双 Agent（如 Claude Code + Codex）必须禁止共用一个工作目录；与站内 双 Agent 隔离架构 一致。
- MCP Server 只挂一份、路径与 worktree 对齐；工具作用域见 MCP 部署决策。
- 文末附场景矩阵、推荐组合、7 步落地清单与验收指标（交叉写入 0 次、越权读取告警率）。
先行结论：AI Agent 文件隔离层级怎么选
没有「一种隔离搞定一切」。个人笔记本上单 Agent：路径白名单 +
.gitignore纪律往往够用；同机多 Agent 改同一仓库：必须git worktree+ 独立 tmux 会话；客户数据或生产密钥：独立云 Mac 节点或容器沙箱才是底线。
2026 年 8 月，kvmboot 工单里「Agent 把 .env 提交进 PR」「两个 CLI 同时改 package.json」类事故，90% 是隔离层级选错，而非模型「太聪明」。下表按接入成本从低到高排列；多数团队应在路径白名单 + worktree 停住，再按需上容器或独立节点。
非对称结论：文件隔离解决的是「写到哪里」；记忆隔离解决的是「记住什么」——两者都要做，但不能互相替代。
1. 为什么 AI Agent 必须做文件隔离（Why）
Agent 与传统 IDE 补全的最大差异是自主执行：它会读目录、改多文件、跑 shell、通过 MCP 触达 Git 与数据库。没有边界时，典型失败模式包括：
- 交叉污染：Agent A 在
feature/auth改 API，Agent B 同时在main跑格式化，结果package-lock.json被覆盖——合并冲突之外还有「静默覆盖」。 - 密钥外泄：Agent 为「修复配置」读取
~/.aws/credentials或项目.env，上下文或日志带出片段；路径白名单未配置时几乎必然发生。 - 越权写入：MCP Filesystem Server 根目录设得太宽（如
/Users），一次错误tools/call可删家目录。 - 不可回滚：Agent 直接改工作区而非 worktree/分支，没有「丢弃整个工作副本」的逃生舱。
这与 云 Mac 双 Agent 架构 里强调的「禁止共用一个工作目录」同源：Host 上了云只是解决在线时长，文件隔离解决写入主权。官方参考：Claude Code 权限与 IAM、Cursor Agent 安全说明。
2. 六种文件隔离方案分类（What）
2.1 路径白名单（工具级，最快）
在 Claude Code 的 settings.json 或项目 .claude/settings.json 中声明 allowedDirectories / 拒绝敏感路径。Cursor 侧用 Rules + Agent 模式限制工作区根。优点：零基础设施；缺点：依赖人不忘改配置，且无法阻止同进程内的「误读」已挂载密钥。
2.2 独立 HOME 与工作目录（进程级）
为每个 Agent 准备 HOME=/opt/agents/claude 与 HOME=/opt/agents/codex，配置、缓存、本地 MCP 状态互不干扰。配合 tmux 会话绑定用户或环境变量，是同机双 CLI 的最低成本方案。
2.3 git worktree（仓库级硬隔离）
git worktree 在同一仓库创建多个检出目录，各 Agent 绑定不同 worktree 路径与分支。交叉写入在文件系统层面即不可能「改到对方目录」——除非配置错误。详见 远程 Mac M4 worktree 农场指南。
2.4 容器沙箱（执行级）
Docker/Podman 将 Agent 运行时与挂载卷绑定；只读挂源码、可写挂 /tmp/agent-out。适合 CI Agent 跑不可信脚本。Apple Silicon 上注意镜像架构与 Docker 安全模型；纯 macOS 原生 Agent 往往仍用 worktree + 用户隔离更顺滑。
2.5 MCP 工具作用域（服务级）
每个 MCP Server 只暴露必要工具与根路径：Git Server 限仓库根；Filesystem Server 禁止 挂 $HOME。多 Client（Claude Code + Codex）共享同一 Server 进程时，路径必须与各 Client 的 worktree 对齐，避免「Server 指向 A 目录、Client 以为在 B」。
2.6 云 Mac 独立节点（主机级）
每个 Agent 或每个租户一台云 Mac mini：SSH 密钥、Keychain、仓库 clone 物理分离。成本最高，但验收最简单——交叉写入在基础设施层即为 0。适合客户数据分区、生产发布 Agent。
3. 六种方案五维对比表
| 方案 | 入口 | 执行边界 | 成本 | 权限边界 | 适合人群 |
|---|---|---|---|---|---|
| 路径白名单 🥇 | Claude Code / Cursor 配置 | 读写仅限 allowlist 目录 | 零额外硬件 | 工具级；依赖配置纪律 | 单 Agent、快速上线 |
| 独立 HOME + 工作目录 🥈 | Unix 用户 / 环境变量 | 进程级文件系统视图 | 一台机多用户即可 | OS 用户隔离；需运维 | 同机双 Agent（Claude + Codex） |
| git worktree 🥉 | git CLI / Agent 工作区 | 仓库级硬隔离工作副本 | 磁盘多一份检出 | 分支/目录不可交叉写入 | 并行改同一 repo 的多 Agent |
| 容器沙箱 | Docker/Podman | 挂载卷 + namespace | 镜像构建与 CI 成本 | 强；macOS 上 ARM 需注意 | CI Agent、不可信脚本 |
| MCP 工具作用域 | MCP Server 配置 | 工具可见文件/API 子集 | 与 MCP 同机部署 | 按 Server/Client 绑定 | 多 Client 共享只读资产 |
| 云 Mac 节点隔离 | SSH / VNC 独立实例 | 整机 VM/裸金属 | 按租期计费 | 最强；密钥与 repo 物理分离 | 生产 Agent、客户数据分区 |
4. 三层叠加架构（实战拓扑）
kvmboot 内部推荐的默认拓扑（一台 24GB 云 Mac 上跑双 Agent）：
L1 工具层：Claude Code / Codex 各自 allowedDirectories + 拒绝 ~/.ssh、.env L2 仓库层：git worktree add ../wt-claude feature/x ；git worktree add ../wt-codex feature/y L3 会话层：tmux session claude → cd wt-claude ；tmux session codex → cd wt-codex L4 服务层：单一 MCP Git Server，root 指 monorepo；各 Client cwd 对齐各自 worktree L5（可选）主机层：敏感租户 → 独立云 Mac 实例，不与其他 Agent 合租
验收时跑三条探针：ls 对方 worktree 应只读或不可见；故意让 Agent 写 ../wt-other/README 应失败；git status 只显示本 worktree 变更。
5. 开发者最佳实践清单
- 先划「不可写区」再划「可写区」：默认拒绝
~、/etc、.env*、*.pem，再白名单项目子目录。 - Agent 永不以 root 跑：专用 Unix 用户，
umask 027，日志目录单独挂载。 - worktree 命名规范：
wt-{agent}-{branch-slug}，避免与人工 clone 目录混淆。 - MCP 单例 + 路径契约：文档写明「Client cwd 必须等于 Server 允许的子路径」；换 worktree 时重启 Client 会话。
- 提交前人工或 CI 门禁：Agent 只推分支，不直推
main；pre-commit扫描密钥。 - 临时文件进
tmp/：Agent 生成的大文件、解压包限定在 worktree 内tmp/，定期git clean。 - 云 Mac 常驻节点：笔记本合盖会中断长会话与 MCP 长连接；隔离配置应落在7×24 在线的执行节点（参见 MCP 与云 Mac 同机部署）。
6. 场景选择矩阵
| 你的场景 | 首选 | 备选 | 别选 |
|---|---|---|---|
| 个人笔记本单 Agent 改一个 repo | 路径白名单 | feature 分支 | 整机云 Mac（过度） |
| Claude Code + Codex 同机并行 | worktree + 独立 HOME | 双 tmux | 同一 cwd |
| CI 跑不可信生成脚本 | 容器沙箱 | 临时云 Mac | 裸路径白名单 |
| 多租户 SaaS Agent | 独立云 Mac / VM | K8s + 卷隔离 | 共享 worktree |
| 只读查阅公司 Wiki/代码 | MCP 只读 Server | TencentDB Wiki 层 | 宽 Filesystem MCP |
| OpenClaw 多 Skill 并行 | worktree + Gateway 路由 | OpenClaw 插件隔离 | 单目录多进程写 |
7. 推荐组合（Stack）
组合 A — 个人极客：Cursor 路径规则 + feature 分支 + 本地 .env 不进仓库 组合 B — 双 CLI 同机：独立 HOME + 双 worktree + 单 MCP Git + 云 Mac 24GB 组合 C — 团队 CI Agent：Docker 沙箱 + 只读 mount 源码 + 云 Mac 跑 sign/notarize 组合 D — 多租户生产：每租户独立云 Mac + 独立 SSH Key + 无共享 MCP 组合 E — OpenClaw 编排：Gateway + 每任务 worktree + launchd 定时清理 tmp
8. 常见误区
- 误区 1：以为「分支隔离」等于「文件隔离」——未提交改动仍在同一 working tree，另一 Agent 的
npm install仍会改锁文件。 - 误区 2：MCP Filesystem 挂项目根的上级目录——一次
write可波及所有子项目。 - 误区 3：双 Agent 共用
~/.claude或~/.codex状态目录——Hooks 与缓存串线。 - 误区 4：只靠 Prompt「请不要改别的目录」——模型会遵守一段时间，配置与 OS 边界才可靠。
- 误区 5：隔离做了但验收不做——应量化「交叉写入次数」与「越权读取告警」，见下文 7 步清单。
9. 7 步落地与验收标准
- 盘点写入面：列出 Agent 会触达的路径（repo、
~/配置、MCP 根、/tmp）。 - 配置 L1 白名单：Claude Code / Cursor 拒绝敏感路径；记录配置到仓库
docs/agent-isolation.md。 - 建 worktree：每并行 Agent 一个目录；
git worktree list入 CI 检查。 - 绑 tmux + HOME：会话名与目录名一致；文档化启动脚本。
- MCP 对齐：单 Server、路径与 worktree 一致；跑
tools/list冒烟。 - 48h 并行压测：两 Agent 同时改不同模块；指标：交叉写入 0 次、
tools/call成功率 ≥95%、越权探针 100% 被拒绝。 - 上云常驻：配置迁入云 Mac；本机仅 SSH；租期与存储见 kvmboot 套餐。
10. FAQ
Q1：文件隔离和沙箱是一回事吗？
A：沙箱是执行环境受限（容器、Seatbelt）；文件隔离是路径主权。可叠加：容器里仍要 mount 对的路径。
Q2：只有一个 Agent 还要 worktree 吗？
A：单 Agent 可用 feature 分支；若你经常「开第二个 CLI 试方案」，建议提前建 worktree，成本低。
Q3：MCP 能否每个 Agent 各起一个 Server？
A：可以，但内存与端口成本翻倍；同机双 Agent 更常见是单 Server + 多 Client cwd 对齐。
Q4：macOS 上 Docker 隔离 Agent 靠谱吗？
A：CI 场景靠谱；日常 Claude Code 原生体验更好，优先 worktree + 用户隔离。
Q5：验收指标怎么量化？
A：kvmboot 内部三指标：交叉写入 0、越权探针拒绝率 100%、并行 48h 内 memory_pressure 黄区 ≤2h（见双 Agent 文）。
11. 总结
AI Agent 文件隔离的本质是：让每一次写入落在可声明、可审计、可丢弃的边界内。开发者最佳实践不是追求「最强隔离」，而是按场景叠加——路径白名单打底，并行改仓用 worktree，租户与客户数据用独立云 Mac。与 双 Agent 隔离、worktree 农场、MCP 部署 串联，可得到可复制的生产拓扑。
在云 Mac 上落地 Agent 文件隔离
文件隔离配置需要稳定在线的执行节点：worktree、MCP、tmux 会话不应随笔记本合盖而断。 kvmboot 云 Mac mini M4 提供 7×24 SSH/VNC、16GB/24GB 可选，适合双 Agent worktree 农场与 MCP 同机部署。 Apple Silicon 统一内存降低多 worktree + 向量索引并行时的内存压力；macOS 便于 Keychain 与 codesign 与 Agent 流水线同机。
建议先用日租跑 48h 并行压测验收隔离指标，再转月租固定节点。 查看 kvmboot 云 Mac 套餐。