Claude Code 的 blockWritesOutsideWorkingDirectories：禁止写工作目录之外的文件（v2.1.314 新增）

本文根据 Claude Code 官方《Configure permissions》、设置参考和 changelog 整理，资料核对于 2026-11-05。配图为本站整理的示意图，不是界面截图。本站（bigolab.com）不是 Anthropic 官方网站。

适用于谁

• 用 Claude Code 时担心它把文件写到项目之外（比如你的主目录或别的项目）的人；
• 在 bypassPermissions 模式下跑自动化、想加一道保险的人；
• 管理团队配置，想在设置文件里统一限制的人。

结论先说

1. 是什么：permissions.blockWritesOutsideWorkingDirectories，设为 true 后，Write、Edit、NotebookEdit 三个文件工具在所有权限模式下（包括 bypassPermissions）都拒绝写工作目录之外的路径。
2. 例外：Claude Code 自己的一些文件，例如计划文件。
3. 不管什么：官方明说这个键不限制 Shell 命令、MCP 工具和 hook 运行的程序，要限制 Shell 往哪写，得用沙箱（sandboxing）。
4. 版本：需要 Claude Code v2.1.314（2026-10-30）或更高。
5. 姐妹键：permissions.blockReadsOutsideWorkingDirectories 管读，一样在所有模式下生效。

图：本站根据 Claude Code 官方《Configure permissions》 整理的示意图

一、先弄清「工作目录」

官方说明：默认情况下，Claude 能访问你启动它时所在目录里的文件；这个目录是会话的主工作目录，直到你用 /cd 把会话移到别处。扩展访问范围有三种方式：

• 启动时：命令行参数 --add-dir <路径>；
• 会话中：/add-dir 命令；
• 持久配置：在设置文件里写 additionalDirectories。

添加的目录，其文件遵循和原目录一样的权限规则：读取不再询问（网络路径除外），编辑权限则看当前权限模式。大仓库里怎么搭配这些设置，见 /guides/claude-code-large-repo-focus-directories。

二、怎么打开

在 .claude/settings.json（项目共享）、.claude/settings.local.json（仅自己）或用户设置里，把键设为 true。下面的写法是本站按官方键名写的示意：

json
{
  "permissions": {
    "blockWritesOutsideWorkingDirectories": true
  }
}

要同时限制读取，再加上 "blockReadsOutsideWorkingDirectories": true。官方还提到，在自动（auto）模式下，Claude 第一次读取工作目录之外的内容时，Claude Code 会主动提示你打开读取那个键。设置文件的层级与位置见 /guides/claude-code-settings-json。

图：本站根据 Claude Code 官方《Configure permissions》 整理的示意图

三、它和普通权限提示有什么不同

普通情况下，写文件会弹出权限提示，你可以点允许。而在 bypassPermissions 这类跳过提示的模式里，这些提示根本不出现，Claude 想写哪里都行。这个键的意义是：不依赖你点不点同意，而是直接让文件工具拒绝，所以连 bypassPermissions 也绕不过。权限模式的区别见 /guides/claude-code-permission-modes。

四、需要写到外面怎么办

如果确实有一个外部目录需要写（例如另一个包、共享配置目录），官方的思路是把它「加为工作目录」，也就是上面第一节的三种方式之一，这样它就不再算「外部」。官方设置参考页对此有专门的一节（Let one directory through the read or write block），具体写法请直接看那一节。

五、一定要知道的盲区

官方明确写了：这个键只管 Write、Edit、NotebookEdit。如果 Claude 用 Bash 执行 echo x > ~/somewhere 或者 cp，或者通过 MCP 工具、hook 脚本写文件，它不会被拦。要限制 Shell 命令的写入位置，官方建议使用沙箱（sandboxing）。所以安全配置要分层：文件工具用这个键，Shell 用沙箱，再加上 permissions.deny 规则对具体命令和路径做限制。

常见问题

Q：设置了但 Claude 还是写到外面了？

先看它是不是用 Bash 写的，这个键不管 Shell。其次确认版本不低于 v2.1.314。

Q：它能代替权限提示吗？

不能，它只是额外的硬性边界。日常权限提示和模式仍然照常工作。

Q：团队怎么统一？

放在项目共享的 .claude/settings.json 里提交，或者用组织的托管设置。额度较紧或团队规模变大的话，可了解 Claude Code 订阅方案。

参考资料

• Claude Code 官方：Configure permissions — https://code.claude.com/docs/en/permissions
• Claude Code 官方：Settings reference — https://code.claude.com/docs/en/settings-reference
• Claude Code 官方：Changelog（2.1.314）— https://code.claude.com/docs/en/changelog