Claude Code credential mask 是什么

sandbox credentials 的 mask 模式在 Linux/WSL2 用 sentinel 与代理出站注入，支持 extract、JWT、AWS SigV4 重签。

Claude Code credential mask 是什么

sandbox 里跑 gh api 或读 ~/.aws/credentials，你既想拦泄露，又不想工具完全拿不到密钥。claude code credential mask 是什么：在 sandbox.credentials 里把条目设为 "mode": "mask"，沙箱内进程看到的是占位 sentinel，出站请求经 sandbox proxy 换回真值；Linux 与 WSL2 对凭据文件也适用，macOS 上文件 mask 会退化为 deny 读。

作者：CodePass 技术编辑

mask 和 deny 差在哪

deny 直接禁止读凭据文件或删掉环境变量，sandbox 里的 gh、npm publish、curl 往往一起挂。mask 保留「工具以为自己有 token」的语义：进程内日志、子进程环境、被 agent 读到的文件内容都是假的，只有 proxy 在允许的目标 host 上替换成真凭据。

GH_TOKEN、NPM_TOKEN 这类整值变量 mask 配置在官方文档有完整 JSON 样例；injectHosts 收窄注入面，避免 sentinel 被带到任意域名。与 CLAUDE_CODE_SUBPROCESS_ENV_SCRUB 不同：scrub 对沙箱内外所有子进程生效，mask 只影响 sandboxed Bash 且保留「可认证出站」能力。两者可同时开，scrub 去掉 Anthropic 自身 API key，mask 管你的第三方 PAT。

环境变量 mask 需要 Claude Code v2.1.199+；文件 mask 需要 v2.1.221+；Week 32（v2.1.224）又加了 extract 字段、decode: "jwt"、以及 AWS SigV4 重签相关选项。前提仍是 sandbox 开启，且对 mask 出站通常要配 network.tlsTerminate，否则 proxy 看不到明文，substitution 失败，命令仍只带 sentinel，认证报错。

团队 rollout 时可先用 /doctor 看 sandbox 段是否被 project settings silently 忽略，再让 agent 在沙箱里跑一条只读 gh api user，确认能通、日志无真 token。deny 与 mask 可混用：只读源码的 repo 仍 deny ~/.ssh，只对 CI token 开 mask。

Linux 与 WSL2 上文件怎么 mask

官方 Mask credential files 写明：Linux 与 WSL2 上，沙箱命令读被 mask 的文件时，匹配到的秘密片段会被 sentinel 替换；macOS 则在 filesystem isolation 开启时把 mask 当 deny，读文件直接失败。自测方法：让 Claude 在沙箱里 cat ~/.config/gh/hosts.yml，Linux/WSL2 应看到占位 token，macOS 应看到拒绝。

典型配置片段（GitHub CLI 的 hosts.yml，用 extract 指出哪一段是 token）：

{
  "sandbox": {
    "credentials": {
      "files": [
        {
          "path": "~/.config/gh/hosts.yml",
          "mode": "mask",
          "extract": "oauth_token:\\s*(\\S+)",
          "injectHosts": ["api.github.com"]
        }
      ]
    }
  }
}

extract 用正则捕获要 mask 的子串；decode: "jwt" 则验证 JWT 并换成结构有效的假 token，还可加 maskClaims 只遮 payload 里指定 claim。onExtractNoMatch 默认 warn 并跳过该条（文件可读真值），若秘密可能存在但 pattern 可能漏匹配，应改成 deny。目录、glob、大于 8 MiB 或非 UTF-8 文件无法 mask，会 fallback 到 deny。

多行 YAML、INI 或 kubeconfig 里往往有多段 secret，一条 extract 只遮匹配到的捕获组；重复出现的同一 token 可开 maskDuplicates，但短字符串会误伤正文，官方建议只用于长随机串。JWT 场景下 agent 若只 decode payload 做 exp 检查，假 token 仍能通过结构校验，真 exp 被 mask 的 claim 则显示占位值。

sentinel 与 proxy 替换流程

沙箱命令发起 HTTPS 请求时，内置 proxy 检查目标 host 是否在 injectHosts 或 network.allowedDomains 内。请求头、body 里的 sentinel 被换成真实 token；未列出的 host 不会注入，避免把 GitHub token 送到任意域名。injectHosts 写 canonical 压缩形式的 IP/主机名，端口不参与匹配；/doctor 会警告永远匹配不到的条目。

与 claude code auto mode 默认改什么 的关系：auto mode 用分类器批 tool call，mask 是 sandbox 层的凭据隔离，两者叠加。auto 放行 curl 不等于真实 token 进沙箱日志；mask 失败时你看到的仍是 sentinel。组织若在 managed settings 里配了 credentials.files 的 deny，只有 managed 能改 filesystem.disabled，mask 条目是否 pin 住 filesystem 取决于最终是 mask 还是 fallback deny，部署前应用 /doctor 过一遍。

自定义 network.customProxy 时，mask 替换逻辑仍在 Claude Code 内置 proxy 或你配置的 TLS 终止链路上；若 proxy 只做 CONNECT 隧道、不 inspect 明文，mask 与 tlsTerminate 必须成对出现。Red team 时可故意让 agent 在沙箱里 printenv 与 curl -v，确认 stderr 与 transcript 不含真 secret，再放开 auto mode 给 wider 团队。

extract、JWT 与 AWS SigV4

Week 32 把结构化凭据处理补全到 v2.1.224。环境变量 mask 可选 extract 只替换值的一部分；decode: "jwt" 在变量或文件里找 JWT，验证后整段替换或按 claim 局部 mask。AWS 请求带 SigV4 签名，必须同时 mask AWS_ACCESS_KEY_ID 与 AWS_SECRET_ACCESS_KEY（整值 mask，不用 extract），proxy 识别 access key 的 sentinel 后重签；只 mask secret 会导致请求带着占位签名出站，AWS 拒绝，启动时会有 warning。

临时凭证还要 mask AWS_SESSION_TOKEN。非标准变量名可用 credentials.awsPairs 手动配对。某些 SigV4 形式 proxy 无法重算，可用 credentials.sigv4 把对应形式设为 passthrough，让 AWS 返回官方错误而不是 proxy 中断。以上 awsPairs、sigv4、带 extract 的文件 mask 字段，仅接受 user settings、managed settings 和 --settings CLI 传入，仓库内 .claude/settings.json 里的 mask 会被忽略，防止 PR 里塞 injectHosts 把 token 打到攻击者域名。

配置落点与常见坑

mask 条目不能写在项目 .claude/settings.json 或 .claude/settings.local.json；团队统一策略应走 managed settings 或每人 ~/.claude/settings.json。与 Claude Code CLI 基础 里 --settings 叠加时，确认最终 JSON 合并后 sandbox 段完整。

常见坑：开了 mask 但没开 network.tlsTerminate，TLS 直通导致 substitution 永远不发生；injectHosts 与 allowedDomains 不一致，请求根本出不了 sandbox；在 macOS 上期待文件 sentinel，实际得到读拒绝；用 http:// 托管插件或凭据 URL（archive 与 mask 都要求 HTTPS）。在 自托管 runner 上，sandbox 与 proxy 行为跟本地 CLI 一致，但 egress 走公司 proxy 时要同时配 HTTPS_PROXY 与 doctor 检查。

Enterprise 可把 mask 模板放进 managed settings 统一下发，开发者 laptop 上的 project settings 无法放宽 inject 范围。轮换 PAT 后 sentinel 会话级重建，一般不必重启 Claude Code；若 proxy 缓存了旧映射，/reload 或新开会话即可。文档 v2.1.224 的 Week 32 摘要一行带过 file mask 增强，细节仍以 sandboxing 长页为准。

复制检查：沙箱内 echo $GH_TOKEN 应显示 per-session sentinel；对 api.github.com 的 gh api user 应成功，对未授权 host 的 curl 不应泄露真 token。文件 mask 在 Linux 用 cat 看 sentinel，在 macOS 预期读失败而非假文件。

WSL2 与原生 Linux 行为一致，适合在 Windows 主机的 Claude Code 沙箱里 mask ~/.config/gh/ 或 %USERPROFILE% 映射路径；路径写法仍用 ~ 展开规则，别混用 Windows 反斜杠进 JSON。公司 egress 走 MITM 代理时，tlsTerminate 与代理 trust store 必须一起配，否则 mask 成功但 TLS 握手失败，表现像「token 无效」。

参考资料