AI Agent 如何實現檔案隔離？開發者最佳實踐

本文要點

結論先行：AI Agent 檔案隔離的核心是边界可声明、越界可检测、污染可回滚——不是禁止写檔案，而是禁止「写到别人的目錄里」。
工程上推荐三层叠加：路径白名单（工具级）→ git worktree（仓库级）→ 独立 HOME/雲 Mac 节点（主机级）。
同机双 Agent（如 Claude Code + Codex）必须禁止共用一个工作目錄；与站内双 Agent 隔離架构一致。
MCP Server 只挂一份、路径与 worktree 对齐；工具作用域见 MCP 部署决策。
文末附場景矩阵、推荐組合、7 步落地清單与驗收指标（交叉写入 0 次、越权读取告警率）。

開發者工作区与檔案权限——AI Agent 檔案隔離最佳實踐 — 檔案隔離不是「不让 Agent 写檔案」，而是让每次写入落在可审计、可回滚、不可交叉污染的边界内。

先行結論：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 部署串联，可得到可复制的生产拓扑。