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下的三组路径清单控制语义是白名单加例外配置键作用sandbox.filesystem.allowWrite允许沙箱内命令写入的路径sandbox.filesystem.allowRead允许读取的路径sandbox.filesystem.denyRead明确禁止读取的路径文档给出的完整示例配置/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.disabledv2.1.216会整体跳过文件系统隔离但保留网络出口控制。文档给出的适用条件是文件沙箱把现有工具链弄坏、但网络出口策略必须保留的场景。注意它只从 user settings、managed settings 或--settings生效项目配置无法设置。配置网络隔离网络隔离围绕域名清单三个键按优先级配合配置键作用版本sandbox.network.allowedDomains沙箱进程允许访问的域名支持*.通配—sandbox.network.deniedDomains即使被allowedDomains的通配符放行也要阻止的域名v2.1.113sandbox.network.strictAllowlist非白名单主机直接拒绝、不再询问v2.1.219通配符加例外的主路径写法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 maskingsandbox.credentialsv2.1.187用于阻止沙箱内命令读取凭证文件和含密钥的环境变量。v2.1.221 之前只能deny——命令一旦需要凭证就失败。v2.1.221 引入的mode: mask改变了这一点沙箱进程读到的是文件的sentinel哨兵副本命令照常运行真实值由沙箱代理在数据发往网络时替换回去凭证不落进进程可读的内容里。文档示例{ sandbox: { network: { tlsTerminate: true }, credentials: { files: [ { path: ~/.aws/credentials, mode: mask } ] } } }这里有两条容易漏掉的约束直接影响配置能否生效所有掩码能力都要求network.tlsTerminate。代理必须能看到请求内部内容才能做替换示例中两者因此出现在同一配置里。凭证掩码选项只从 user settings、managed settings 或--settings生效项目设置既不能开启掩码、也不能改掩码对象。把这段 JSON 放进项目级.claude/settings.json是不会起作用的。版本能力矩阵来自文档的表格写配置前先对照自己的版本能力起始版本行为凭证文件mode: maskv2.1.221命令读 sentinel代理在出口替换真实值。仅 Linux 和 WSL——macOS 上文件掩码回退为denyextract/onExtractNoMatchv2.1.224只掩结构化环境变量值中的单个字段并定义模式不匹配时的行为decode: jwt配maskClaimsv2.1.224解码 JWT 后只掩码指定的 claims其余保持可读awsPairs/sigv4v2.1.224代理在替换真实 access key 后对 AWS SigV4 请求重新签名所以掩码路径的平台边界是Linux/WSL 全功能macOS 上文件掩码退化为拒绝读取。如果你的环境是 macOS 且命令确实需要~/.aws/credentials掩码不可用只能选择deny后让该命令失败或把网络访问移出沙箱白名单之外的方案由你按文档另行决定——文档没有为 macOS 掩码回退给出替代配置。Linux/WSL 上的工具路径可选Linux 与 WSL 的沙箱依赖bubblewrapbwrap和socat两个外部二进制默认从$PATH查找。安装在非标准位置时用 v2.1.133 的两个路径键指定/opt/...为文档示例路径{ sandbox: { bwrapPath: /opt/bubblewrap/bin/bwrap, socatPath: /opt/socat/bin/socat } }macOS 特有的一键开关sandbox.allowAppleEventsv2.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考