什么是沙箱
文档用一句话描述了这一边界:“当沙箱开启时,Claude 运行的 shell 命令及其启动的进程都在其边界内启动。”
除非你主动开启,否则它是关闭的。文档指出:“沙箱默认处于关闭状态。”
强制执行是在操作系统层面进行的。在 macOS 上,Claude Code 使用内置的 Seatbelt 框架。在 Linux 和 WSL2 上,它依赖于 bubblewrap 和 socat 两个包。文档提到,Claude Code 的沙箱是基于 Anthropic 的开源沙箱运行时包构建的。
如何开启沙箱
在会话中运行 /sandbox。它会打开一个带有三个选项卡的面板:
- Mode (模式):选择自动允许 (auto-allow) 或常规权限。
- Overrides (覆盖):选择在沙箱中失败的命令是否可以回退到非沙箱环境下运行。
- Config (配置):显示解析后的沙箱设置。
在 Linux 上,如果缺少某些组件,会出现一个 Dependencies (依赖) 选项卡。如果它是唯一的选项卡,则沙箱尚无法启动。
设置保存的位置很重要。当你在面板中选择模式时,Claude Code 会将其保存到 .claude/settings.local.json,因此它仅适用于当前项目。要为所有项目开启沙箱,请在用户设置 ~/.claude/settings.json 中将 sandbox.enabled 设置为 true。
有一个默认项需要检查。文档警告说:“默认情况下,当平台不支持沙箱或启动时的依赖检查失败时,Claude Code 会在没有沙箱的情况下运行命令。”如果你依赖沙箱作为安全门禁,请将 sandbox.failIfUnavailable 设置为 true,这样 Claude Code 在启动失败时会直接退出。
为了检查沙箱是否生效,文档建议让 Claude 运行一个向你的主目录写入文件的命令,例如在那里创建一个探测文件。在沙箱内,这在 macOS 上会失败并提示“操作不允许”错误,在 Linux 上则提示“只读文件系统”错误。你自己输入命令无法测试这一点,因为你在 shell 提示符下输入的命令通常是在沙箱外运行的。
默认限制哪些内容
文档提供了一个默认设置表。简而言之:
写入 (Writes):沙箱化命令可以写入工作目录、每个用户的临时目录,以及你通过 --add-dir 或 /add-dir 添加的目录。受保护的路径仍然被拒绝写入。
读取 (Reads):机器的大部分内容是可读的,包括凭据文件,如 SSH 密钥和 AWS 凭据。你需要通过 filesystem.denyRead 或凭据设置自行缩小读取范围。
网络 (Network): “没有直接的外连路由。连接通过你机器上的代理进行,该代理会根据你的允许域名列表检查每个主机,该列表初始为空。”当命令第一次需要访问新域名时,Claude Code 会请求批准。
环境变量 (Environment variables):命令继承 Claude Code 的环境,“包括其环境中的任何机密信息”,除非你对其进行清除或掩码处理。
如果你期望沙箱能隐藏所有内容,那么第二点非常重要。默认情况下,读取权限是很宽泛的。沙箱的默认职责是阻止项目外的写入以及向未授权主机的网络流量。
受保护的路径
在沙箱化命令可以写入的文件夹内,某些路径仍然被拒绝写入。文档将其分为四组:
- 在你的工作目录及其上级目录中:
.claude配置文件、.claude/skills、.claude/agents、.claude/commands和.claude/hooks目录、.mcp.json,以及 Claude Code 自行运行的文件,如.claude/workflows和.claude/scheduled_tasks.json。 - 仅在你的工作目录中:shell 启动文件(如
.bashrc和.zshrc)、.gitconfig、.vscode和.idea目录,以及.git内部的hooks和config条目。 - 会将你的工作目录变为裸 git 仓库的文件:顶层的
HEAD、objects和refs以及相关条目。 - 在
~/.claude或CLAUDE_CONFIG_DIR指向的文件夹中:其大部分内容,加上~/.claude.json和凭据存储。
共同点是这些都是 Claude Code 读取的配置和运行的代码。Skill 是 Claude 遵循的指令。Hook 是 Claude Code 运行的脚本。设置决定了权限。如果沙箱化命令可以重写其中任何一个,下一个会话就会以该命令写入的内容启动。
你无法通过意外操作来放宽这些限制。文档指出,如果你添加了一个涵盖这些路径的写入许可或编辑允许规则,“保护仍然适用”。解除保护的唯一方法是完全关闭文件系统隔离,这也会移除其余的文件系统层。
要查看针对你机器解析的路径,请运行 /sandbox 并打开 Config 选项卡,它们会出现在“允许中的拒绝”条目里。
这也解释了开头的例子。沙箱的拦截适用于沙箱化的 shell 命令。Claude 内置的 Edit 工具遵循权限规则而非沙箱规则,且权限系统维护着自己的受保护路径列表,因此通过该工具进行的编辑是在那里决定的。
如果 git 签出或合并因为无法更新这些路径而失败,文档中有一个针对该情况的故障排除条目,且最近的 Claude Code 版本增加了一个提示,当沙箱化 git 命令无法更新受保护文件时会告知 Claude。
哪些内容在沙箱外运行
文档对范围的界定非常精确:“沙箱包裹的是 shell 命令。”有几类内容不是 Claude 运行的 shell 命令:
- 内置的文件和 Web 工具:Read、Edit、Write、WebFetch 和 WebSearch 遵循权限规则。沙箱中的读取拒绝条目不会阻止 Read 工具,允许域名列表也不会限制 WebFetch。
- Claude Code 启动的其他进程:Command hooks、本地 MCP 服务器、插件监控器和 LSP 服务器都在沙箱外运行。
- Mods:它们在 Claude Code 内部运行自己的代码。
一些 shell 命令也会在沙箱外运行:
- 你输入的命令:在大多数会话中,你在
!shell 提示符下输入的命令。 - 排除的命令:匹配
excludedCommands中条目的命令。 - 非沙箱化重试:下文将详细介绍。
文档建议,如果你希望将所有这些都放在一个边界内,可以使用另一种工具:在容器、虚拟机或沙箱运行时中运行 Claude Code 进程本身。
自动允许与常规权限
两种模式都执行相同的文件系统和网络限制。区别在于审批方式。
自动允许 (Auto-allow):当命令在沙箱内运行时,无需提示即可批准。但某些情况仍会提示:匹配 Bash 拒绝规则的命令、针对关键路径的 rm,以及针对特定内容的询问规则(如 git push 规则)。在程序前设置变量的命令(例如在运行测试前设置环境变量)也会进入常规流程,因为变量可能会改变运行的程序。
常规权限 (Regular permissions):无论是否沙箱化,每个 Bash 命令都会经过正常的权限流程。文档将其描述为“更多的控制,更多的审批”。
Claude 何时请求在非沙箱环境下重试
文档将重试称为“逃生舱”:“非沙箱化重试是针对在沙箱内失败的命令(例如与沙箱不兼容的工具)的逃生舱。”
当沙箱拦截网络连接时,Claude Code 会在命令结果中指明被拒绝的主机,以便 Claude 了解失败原因。Claude 随后可能会带参数重试,为该特定命令禁用沙箱。谁来批准重试取决于你的权限模式:
- 在 Manual (手动) 和 accept-edits (接受编辑) 模式下,你会看到一个标题为“Bash command (unsandboxed)”的提示。
- 在 auto (自动) 模式下,分类模型会评估该命令。
- 在 bypass-permissions (绕过权限) 模式下,它无需提示即可运行。
- 在 don't-ask (不询问) 模式下,它会被拒绝。
两项设置可以改变这一点:匹配该命令的允许规则也会批准其重试;而针对禁用沙箱参数的询问规则会强制要求提示,即使在 auto 或 bypass 模式下也是如此。
要移除此逃生舱,请将 allowUnsandboxedCommands 设置为 false。文档称之为“严格沙箱模式”。除非匹配排除命令,否则 Claude 运行的命令将始终保持沙箱化。如果你或管理员在托管设置中或通过 --settings 设置了此项,沙箱将变为“管理员要求”,Claude Code 会忽略尝试放宽限制的仓库设置。
保护凭据
由于默认读取权限较广,凭据需要明确的规则。文档明确指出没有任何内容会被自动拦截:“没有内置的凭据拒绝列表,因此只有你列出的文件和变量会受到限制。”
sandbox.credentials 设置接收文件路径和环境变量名称,每个都有两种模式:
- Deny (拒绝):拦截文件的读取,并在每个沙箱化命令执行前取消设置该变量。
- Mask (掩码):向命令显示占位符,沙箱代理仅在向你允许的主机发出请求时才替换为真实值。
来自每个设置范围的 Deny 条目会被合并,且任何范围都不能移除另一个范围添加的条目。掩码模式需要更多配置,包括代理处的 TLS 终止,且仅在用户设置、托管设置或 --settings 中生效。
项目无法更改的设置
某些沙箱设置仅在特定位置受信任。最明显的例子是关闭文件系统隔离。文档解释了风险:如果关闭该功能并自动允许命令,沙箱化命令可以写入后续命令会读取的文件(如 ~/.claude/settings.json),“并利用它们在下次运行时扩大自己的访问权限”。
因此,.claude/settings.json 和 .claude/settings.local.json 中的项目设置无法设置此项。只有用户设置、托管设置和 --settings 可以。如果你禁用了重试,即使项目设置显示为 true,你用户设置中的 false 依然有效。
我们在 Codex 权限配置文件 指南中介绍了 Codex 如何划定类似的界限,在可写工作区内保持其自身的配置文件夹为只读。
人们最初常有的误解
以为沙箱是开启的。 它默认是关闭的。
以为它会自动隐藏凭据。 在你添加凭据规则之前,读取权限是很宽泛的。
尝试为 .claude 添加允许规则。 受保护的路径始终受保护。
以为它涵盖了 hooks 和 MCP 服务器。 它们在沙箱外运行。
假设启动失败会停止 Claude Code。 如果没有设置 failIfUnavailable,命令将在非沙箱环境下运行。
解决方案:有目的地配置沙箱
第 1 步:在需要的地方开启它
针对单个项目使用 /sandbox,或通过用户设置针对所有项目开启。
第 2 步:添加凭据规则
拒绝或掩码处理命令不应看到的文件和变量。
第 3 步:决定是否保留逃生舱
保留带提示的非沙箱化重试,或通过严格模式将其关闭。
第 4 步:记录每个设置存在的原因
记录你允许了哪些域名、文件夹和排除项,以及每个条目的原因。
在 MemoryLake 中设置
沙箱设置只是配置文件中的简短几行。它们背后的原因——例如为什么要允许某个域名、哪个工具需要排除项,或者为什么在某个仓库中关闭重试——是配置文件无法解释的项目上下文 (context)。当几个月后有人询问某条规则是否仍有必要时,这些原因才是最有帮助的。
MemoryLake 是此类项目上下文的记忆层,例如安全决策、允许的异常及其背后的原因。这些信息被统一保存在你维护的一个地方,并可供你连接的助手(如 ChatGPT、Claude Code 和 Codex)使用。
你用自己的语言编写条目。MemoryLake 不会从你的 Claude Code 设置、.claude 文件夹、沙箱配置、会话或任何供应商的存储中读取、写入或删除任何内容。沙箱仍按 Anthropic 描述的方式工作。
第 1 步:创建 API 密钥
登录并从控制面板生成密钥。像对待其他凭据一样,将其存储在仓库之外。

第 2 步:上传你的第一条记忆
从你在解决方案第 4 步中写下的内容开始:每个沙箱异常及其原因。每个条目对应一个异常。

第 3 步:连接你的 AI 和智能体
连接 Claude Code、Codex 以及你使用的其他助手。每个助手都可以根据你已记录的原因检查提议的异常。

这在实践中改变了什么
第一个区别是审查变得更容易。每个异常都附带了添加它的原因。
第二个区别是减少了宽泛的规则。当原始需求明确时,更容易选择狭窄的路径或域名。
第三个区别是跨工具的一致性。相同的安全决策在 Claude Code 和 Codex 中均可使用。
Claude Code 沙箱最佳实践
如果你依赖沙箱,请设置 failIfUnavailable。 否则,启动失败会导致命令在非沙箱环境下运行。
优先选择狭窄的写入路径而非排除项。 排除的命令将以你的完整访问权限运行。
明确列出凭据。 默认情况下不会拒绝任何凭据。
不要动受保护的路径。 它们保护着 Claude Code 下次加载的内容。
使用容器实现完全隔离。 Hooks、MCP 服务器和内置工具都在沙箱之外。
使用探测命令进行测试。 让 Claude 运行它,不要自己输入。
结论
Claude Code 沙箱包裹了 Claude 运行的 shell 命令及其启动的进程。它默认处于关闭状态。开启后,命令可以写入你的工作目录、临时目录和添加的目录,读取权限保持宽泛,网络流量通过仅允许你批准的主机的代理进行。
在可写文件夹内,受保护的路径保持拒绝写入,包括 .claude 设置、skills、agents、commands、hooks 以及 ~/.claude 的大部分内容,因此命令无法重写下一个会话加载的配置。内置工具、hooks 和 MCP 服务器在沙箱外运行,失败的命令可以尝试在非沙箱环境下重试,除非你通过严格模式将其关闭。