过去几个版本（v2.1.219、v2.1.221）里，Claude Code 陆续为沙箱环境补齐了一整套凭据保护机制——从最基础的「拒绝读取」到「结构化脱敏」「JWT 感知脱敏」「AWS SigV4 重签名」再到「文件级哨兵替换」。这些功能分散在不同版本的 Changelog 里，本文把它们整合成一份完整的沙箱凭据保护指南，帮你理解每种模式适合什么场景。
为什么这是一个真问题
Claude Code 的沙箱机制允许 Agent 在受限环境中执行命令，但很多实际任务需要访问云服务凭据——比如读取 AWS 配置文件判断当前登录状态、调用需要 Bearer Token 认证的内部 API 等。这带来一个两难：完全禁止访问凭据文件，会让 Agent 无法完成很多正常任务；完全放开访问，又意味着凭据明文暴露在模型的上下文中——一旦发生 Prompt 注入攻击，这些凭据就可能被泄露出去。Claude Code 团队近期给出的答案，是构建一套分层的、按需选择的脱敏体系。
模式一：extract + onExtractNoMatch（结构化字段脱敏）
（v2.1.219 引入）
针对结构化的环境变量值，用 extract 正则捕获需要保护的部分，
onExtractNoMatch 控制正则未命中时的兜底行为
适合场景：环境变量整体不敏感，但其中嵌套了一段需要保护的密钥或 Token 字符串。
模式二：decode: "jwt" + maskClaims（JWT 感知脱敏）
（v2.1.219 引入）
专门针对 JWT 格式的凭据，可以解码后按声明（claims）级别
选择性遮盖，而不是整体拒绝或整体放行
适合场景：现代云服务大量使用 JWT 作为访问令牌，这类 Token 内部往往包含一些对任务逻辑有用的非敏感声明（比如过期时间、作用域），和真正敏感的签名部分。JWT 感知脱敏能做到「让 Agent 看到有用的声明字段，但看不到能被重放利用的完整签名 Token」这种精细粒度的控制。
模式三：awsPairs / sigv4（AWS 请求重签名）
（v2.1.219 引入）
针对 AWS SigV4 签名的请求，沙箱代理可以在出口处用真实凭据
重新签名，而 Agent 侧全程接触不到真实密钥
适合场景：需要 Agent 频繁调用 AWS API 的自动化任务。这三种模式（extract/JWT/SigV4）都有一个共同前提——需要 network.tlsTerminate，且只能从 user、managed 或 --settings 配置的设置文件中生效，这是一个刻意的权限收紧，防止普通项目配置文件擅自开启敏感的网络中间人能力。
模式四：mode: "mask"（文件级哨兵替换，v2.1.221 新增）
（v2.1.221 引入，仅 Linux/WSL）
沙箱化命令读到的是「哨兵副本」（整份文件或 extract 正则
捕获的片段），真实值仅在数据流出沙箱边界（egress）时
由代理动态替换
这是目前最新、也是应用场景最广的一种模式——不再局限于环境变量，而是直接针对凭据文件（比如 ~/.aws/credentials 这类文件）。原理是「读时是假的，用时（网络出口）才是真的」，让工具能正常运作的同时，Agent 本身从未真正见过明文密钥。需要特别注意：该模式目前仅支持 Linux 和 WSL，macOS 上会自动退化为 deny（直接拒绝读取）——如果你在 macOS 上配置了 mode: "mask"，实际生效的是更严格的拒绝策略，使用前需要确认平台兼容性。
四种模式怎么选
场景：环境变量中嵌套了一段密钥字符串
→ extract + onExtractNoMatch
场景：需要处理 JWT 格式的访问令牌
→ decode: "jwt" + maskClaims
场景：Agent 需要频繁调用 AWS API
→ awsPairs / sigv4
场景：需要保护整份凭据文件（如 ~/.aws/credentials），
且运行在 Linux/WSL 上
→ mode: "mask"
场景：运行在 macOS 上，且凭据文件不需要被工具直接读取
→ deny（默认最简单可靠的选择）
一个配套的安全修复也值得记住
在梳理这套体系时，有一个 v2.1.224 的修复值得特别提醒——带结尾斜杠的 denyRead 规则（比如 denyRead: "~/.aws/"）此前在 Linux 和 macOS 上可能被悄悄绕过。如果你此前配置了类似写法的拒绝规则，务必在升级后重新验证其是否真正生效——脱敏体系设计得再精细，也要建立在基础拒绝规则真正可靠的前提上。
总结
从「整体拒绝」到「结构化脱敏」再到「文件级哨兵替换」，Claude Code 的沙箱凭据保护体系正在变得越来越精细——本质上是在解决同一个核心矛盾：让 Agent 有能力完成需要凭据的真实任务，同时把「模型上下文中出现明文密钥」这个攻击面降到最低。对于在企业环境中部署 Claude Code 处理云资源相关任务的团队，理解这四种模式的适用边界，是构建安全 Agent 工作流的必修课。
来源：Claude Code Changelog （v2.1.219、v2.1.221、v2.1.224）— Claude Code 官方文档，Anthropic