企业官网建设流程全解析

Claude Code 沙箱如何配置文件与网络隔离？claude-howto 的 sandbox 设置与凭证掩码

【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto

当 Claude Code 在自动化任务中执行 Bash 命令时，这些命令默认可以直接读写本机文件、访问网络。如果你想限制它们只能写项目目录、只能访问指定域名，并且不泄露凭证文件的真实内容，就需要启用沙箱（Sandboxing）。claude-howto 仓库的 09-advanced-features/README.md 的 Sandboxing 章节完整记录了这一层的启用方式、配置键和凭证掩码（credential masking）规则，本文基于该文档整理出一条可执行的配置路径。

沙箱提供的是OS 级别的文件系统与网络隔离，作用于 Claude Code 执行的 Bash 命令。文档明确它是权限规则（permission rules）的补充层，二者同时生效、构成纵深防御，因此配置沙箱不会替代你已有的permissions规则。

启用沙箱

文档给出两种启用入口：

claude --sandbox # 启动时启用沙箱 claude --no-sandbox # 显式关闭沙箱

会话内也可以用斜杠命令开关：

/sandbox

对应的配置键是sandbox.enabled。如果你的环境本身不具备沙箱条件（比如 Linux/WSL 上缺少 bubblewrap），可以设置sandbox.failIfUnavailable: true，让 Claude Code 在无法激活沙箱时直接失败而不是静默降级——这是文档给出的硬性成功条件。

配置文件隔离

文件系统隔离通过sandbox.filesystem下的三组路径清单控制，语义是白名单加例外：

文档给出的完整示例配置（/Users/me为文档中的示例路径，替换成你的项目与主目录）：

{ "sandbox": { "enabled": true, "failIfUnavailable": true, "filesystem": { "allowWrite": ["/Users/me/project"], "allowRead": ["/Users/me/project", "/usr/local/lib"], "denyRead": ["/Users/me/.ssh", "/Users/me/.aws"] }, "enableWeakerNetworkIsolation": true } }

这个示例对应的目标很典型：命令只能写项目目录，能读项目目录和依赖库，同时显式禁读~/.ssh与~/.aws两个凭证目录。配置位置可参考文档 Configuration and Settings 一节列出的~/.claude/config.json、./.claude/config.json和~/.config/claude-code/settings.json。

另有一个针对工具链兼容问题的开关：sandbox.filesystem.disabled（v2.1.216+）会整体跳过文件系统隔离，但保留网络出口控制。文档给出的适用条件是：文件沙箱把现有工具链弄坏、但网络出口策略必须保留的场景。注意它只从 user settings、managed settings 或--settings生效，项目配置无法设置。

配置网络隔离

网络隔离围绕域名清单，三个键按优先级配合：

通配符加例外的主路径写法（example.com为文档示例域名）：

{ "sandbox": { "network": { "allowedDomains": ["*.example.com"], "deniedDomains": ["evil.example.com"] } } }

文档的解释是：通配符放行example.com下的所有主机，但deniedDomains中点名的主机仍然被阻止。若希望默认拒绝而非逐个点名，v2.1.219 起可用strictAllowlist: true，沙箱命令访问非白名单主机时不提示直接拒绝。

macOS 边界：文档的 How It Works 一节明确 macOS 上没有完整网络隔离，需要用sandbox.enableWeakerNetworkIsolation: true来获得（较弱的）网络限制。上面示例配置末尾的这项开关就是为 macOS 准备的；在 Linux/WSL 上不需要它。

配置凭证掩码（credential masking）

sandbox.credentials（v2.1.187+）用于阻止沙箱内命令读取凭证文件和含密钥的环境变量。v2.1.221 之前只能deny——命令一旦需要凭证就失败。v2.1.221 引入的mode: "mask"改变了这一点：沙箱进程读到的是文件的sentinel（哨兵）副本，命令照常运行，真实值由沙箱代理在数据发往网络时替换回去，凭证不落进进程可读的内容里。

文档示例：

{ "sandbox": { "network": { "tlsTerminate": true }, "credentials": { "files": [ { "path": "~/.aws/credentials", "mode": "mask" } ] } } }

这里有两条容易漏掉的约束，直接影响配置能否生效：

1. 所有掩码能力都要求network.tlsTerminate。代理必须能看到请求内部内容才能做替换，示例中两者因此出现在同一配置里。
2. 凭证掩码选项只从 user settings、managed settings 或--settings生效，项目设置既不能开启掩码、也不能改掩码对象。把这段 JSON 放进项目级.claude/settings.json是不会起作用的。

版本能力矩阵（来自文档的表格，写配置前先对照自己的版本）：

所以掩码路径的平台边界是：Linux/WSL 全功能，macOS 上文件掩码退化为拒绝读取。如果你的环境是 macOS 且命令确实需要~/.aws/credentials，掩码不可用，只能选择deny后让该命令失败，或把网络访问移出沙箱白名单之外的方案由你按文档另行决定——文档没有为 macOS 掩码回退给出替代配置。

Linux/WSL 上的工具路径（可选）

Linux 与 WSL 的沙箱依赖bubblewrap（bwrap）和socat两个外部二进制，默认从$PATH查找。安装在非标准位置时，用 v2.1.133+ 的两个路径键指定（/opt/...为文档示例路径）：

{ "sandbox": { "bwrapPath": "/opt/bubblewrap/bin/bwrap", "socatPath": "/opt/socat/bin/socat" } }

macOS 特有的一键开关sandbox.allowAppleEvents（v2.1.181+）则用于放行沙箱命令发送 Apple Events，与文件和网络隔离正交，按需添加。

验证与已知边界

文档没有提供单独的沙箱状态查询命令，可用的判定信号集中在配置语义本身：

• failIfUnavailable: true时，沙箱无法激活会让启动直接失败——这是最直接的"沙箱确实生效"检查，配置成false（或不设置）则静默降级，无法从启动结果区分是否隔离。
• 网络侧，deniedDomains中点名的主机即使落在通配符范围内也会被阻止，可用白名单内一个明确拒绝的域名观察其请求是否被拦下。
• 凭证掩码在 macOS 上不会报错，而是静默回退为deny——如果命令此前依赖读取凭证文件，回退后会从"带掩码运行"变为直接失败，这是平台差异而不是配置错误。
• 项目设置对凭证掩码和filesystem.disabled均无效，这两项必须写在 user settings、managed settings 或通过--settings传入。

文档列出的典型适用场景：安全运行不可信或自动生成的代码、防止误改项目外文件、在自动化任务中限制网络访问。配置完成后，沙箱与既有的权限规则继续并行工作，/sandbox可随时在会话内切换开关。

【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto