配置沙箱化 Bash 工具

​

入门

/sandbox

claude --settings '{"sandbox": {"enabled": true, "allowUnsandboxedCommands": false}}'

​

设置 Linux 和 WSL2

• bubblewrap：无特权沙箱工具，强制执行文件系统隔离
• socat：用于通过沙箱代理路由网络流量的中继

sudo apt-get install bubblewrap socat

sudo dnf install bubblewrap socat

sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'
abi <abi/4.0>,
include <tunables/global>

profile bwrap /usr/bin/bwrap flags=(unconfined) {
  userns,
  include if exists <local/bwrap>
}
EOF

sudo systemctl reload apparmor

​

沙箱模式

​

自动允许模式

• 显式 拒绝规则 始终被尊重
• 针对 关键路径 的 rm 或 rmdir 命令仍会通过常规权限流程
• 内容范围的 询问规则（如 Bash(git push *)）仍会强制提示，即使对于沙箱化命令
• 裸 Bash 询问规则，或等效的 Bash(*) 形式，对于运行沙箱化的命令会被跳过；它仍然适用于回退到常规权限流程的命令。在 Plan Mode 中，该规则不会被跳过：它也会对沙箱化命令提示，包括只读命令。在 v2.1.212 之前，跳过也适用于 Plan Mode

​

常规权限模式

​

非沙箱化重试逃生舱

• 一个 后台会话：严格沙箱模式也覆盖 shell-mode 命令
• 一个设置了 CLAUDE_CODE_SUBPROCESS_ENV_SCRUB 的 Linux 会话：每个命令都沙箱化运行，包括 shell-mode 命令

​

临时目录

​

配置沙箱

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube", "/tmp/build"]
    }
  }
}

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "denyRead": ["~/"],
      "allowRead": ["."]
    }
  }
}

​

禁用文件系统隔离

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "disabled": true
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}

​

哪些设置可以禁用它

• 用户设置、托管设置和 --settings CLI 标志可以设置它。.claude/settings.json 和 .claude/settings.local.json 中的项目设置不能，因此已检出的项目无法关闭文件系统隔离。
• 当托管设置配置 sandbox.filesystem 时，或列出任何 sandbox.credentials.files 条目且 "mode": "deny" 时，仅托管设置可以设置该键。这保持管理员部署的文件系统限制有效；要放松此类部署，请在托管设置中设置 "disabled": true。
• 当设置 CLAUDE_CODE_SUBPROCESS_ENV_SCRUB 时，Claude Code 会忽略来自每个源（包括托管设置）的 filesystem.disabled，并保持文件系统隔离开启。

​

文件系统隔离关闭时的变化

• 沙箱化命令继承你的 shell 的 $TMPDIR，而不是会话临时目录，因为每个临时目录都是可写的，Claude Code 不再将命令重定向到会话临时目录。 在 Linux 上，该变量通常在父 shell 中未设置。Bash 工具指导告诉 Claude 使用 mktemp -d 创建临时目录，而不是依赖 $TMPDIR。
• autoAllowBashIfSandboxed 仍默认为 true，因此沙箱化命令继续运行而无需提示。设置为 false 以提示沙箱化命令。

​

保护凭证

{
  "sandbox": {
    "enabled": true,
    "credentials": {
      "files": [
        { "path": "~/.aws/credentials", "mode": "deny" },
        { "path": "~/.ssh", "mode": "deny" }
      ],
      "envVars": [
        { "name": "GITHUB_TOKEN", "mode": "deny" },
        { "name": "NPM_TOKEN", "mode": "deny" }
      ]
    }
  }
}

• 项目或本地设置：Claude Code 不应用它们的任何 credentials 条目。需要 Claude Code v2.1.246 或更高版本。
• 用户设置：Claude Code 仍然应用 ~/.claude/settings.json 中的 deny 条目，并将其文件 mask 条目保持为限制，但删除其环境变量 mask 条目。

​

掩盖凭证

​

掩盖环境变量

{
  "sandbox": {
    "enabled": true,
    "network": {
      "tlsTerminate": {},
      "allowedDomains": ["*.github.com", "registry.npmjs.org"]
    },
    "credentials": {
      "envVars": [
        { "name": "GH_TOKEN", "mode": "mask", "injectHosts": ["api.github.com"] },
        { "name": "NPM_TOKEN", "mode": "mask" }
      ]
    }
  }
}

• network.allowedDomains：括号形式域列表使用，例如 "[::1]"。代理检查此列表以允许连接。
• injectHosts：其规范压缩形式中的裸地址，例如 "::1" 或 "2001:db8::1"。代理将每个条目与连接的裸目标地址匹配，忽略端口，因此括号、区域 ID 或不同压缩的拼写永远不会匹配，代理永远不会在那里注入凭证。

• extract：Claude Code 在整个值上应用的正则表达式，仅替换每个匹配的第 1 组捕获的文本，因此解析值的工具（如 DATABASE_URL 连接字符串）仍在沙箱内工作。模式必须包含至少一个捕获组。
• onExtractNoMatch 控制模式匹配不到任何内容时发生的情况：
  • warn，默认值，警告并不掩盖地传递变量
  • deny 在沙箱内取消设置变量
  • error 停止沙箱设置，直到你修复配置
• decode: "jwt"：对于持有 JSON Web Token (JWT) 的变量。Claude Code 验证值是 JWT 并将其替换为结构上有效的假令牌，因此沙箱内解码令牌的代码继续工作。添加 maskClaims 以列出要单独掩盖的顶级有效负载声明，而不是替换整个令牌；其他声明保持可读。当值未验证为 JWT 或没有列出的声明匹配时，Claude Code 会以警告不掩盖地传递变量。decode 不能与 extract 组合。

​

重新签名 AWS 请求

{
  "sandbox": {
    "credentials": {
      "awsPairs": [
        {
          "accessKeyIdVar": "MY_KEY_ID",
          "secretAccessKeyVar": "MY_SECRET_KEY",
          "sessionTokenVar": "MY_SESSION_TOKEN"
        }
      ]
    }
  }
}

• accessKeyIdVar 和 secretAccessKeyVar 命名持有访问密钥 ID 和秘密密钥的掩盖 envVars 条目。可选的 sessionTokenVar 命名持有临时凭证会话令牌的条目；设置时，代理在重新签名的请求上将真实令牌作为 x-amz-security-token 发送。
• 每个命名的变量必须是掩盖其整个值的 mask 条目，不带 extract 或 decode。
• 代理在访问密钥 ID 条目的 injectHosts 中列出的主机上重新签名请求。
• 在对中命名任何常规变量会替换自动配对。

​

掩盖凭证文件

• Linux 和 WSL2：沙箱化命令读取文件的哨兵副本，一个替代品，其秘密被替换为占位符值，沙箱代理在出站时替换真实值。
• macOS：沙箱化命令根本无法读取列出的文件。Claude Code 不构建哨兵副本，也不在出站时替换任何内容，因此使用文件进行身份验证的工具在沙箱内不工作，与 deny 的效果相同。与 deny 条目不同，即使你禁用文件系统隔离，读取块也保持有效。

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

• onExtractNoMatch 控制匹配在文件中找不到任何内容要掩盖时发生的情况：
  • warn，默认值，警告并跳过条目，因此沙箱化命令可以不掩盖地读取真实文件。默认值适合凭证可能合法不存在的情况；如果秘密可能存在但模式可能错过它，使用 deny
  • deny 使文件改为不可读
  • error 停止沙箱设置，直到你修复配置
  当读取块不会被强制执行时，Claude Code 将 deny 视为 error：当你禁用文件系统隔离时，以及当任何设置源中的 filesystem.allowRead 条目重新打开文件的路径时。
• maskDuplicates 也替换每个掩盖凭证值的逐字副本，一个 extract 捕获或 decode 验证的令牌，在匹配跨度外找到，对于在匹配无法到达的地方重复的秘密。它匹配原始子字符串，因此短或常见的值会被替换到处出现；为长、高熵秘密保留它。默认值：false。

​

沙箱如何工作

​

文件系统隔离

• 默认写入行为：对当前工作目录及其子目录的读写访问，加上使用 --add-dir、/add-dir 或 permissions.additionalDirectories 添加的任何目录，以及 $TMPDIR 指向的会话临时目录
• 默认读取行为：对整个计算机的读取访问，除了某些被拒绝的目录。注意此默认仍允许读取凭证文件，例如 ~/.aws/credentials 和 ~/.ssh/。使用 sandbox.credentials 阻止读取这些文件并取消设置密钥环境变量，或将路径添加到 denyRead。
• 被阻止的访问：无法在没有明确权限的情况下修改工作目录、添加的目录和会话临时目录外的文件，包括 shell 配置文件（例如 ~/.bashrc）和 /bin/ 中的系统二进制文件
• Git worktrees：当工作目录是链接的 git worktree时，沙箱还允许写入主存储库的共享 .git 目录，以便 git commit 等命令可以更新引用和索引。对该目录内的 hooks/ 和 config 的写入仍然被拒绝。
• 可配置：通过设置定义自定义允许和拒绝的路径

​

受保护的路径

• 在你的工作目录及其上方的目录中：.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，加上 config 和 hooks（当它们已经存在时）。即使 config 文件没有 HEAD 也会被拒绝。在 Linux 和 WSL2 上，沙箱删除在沙箱化命令运行时出现的顶级 HEAD 文件或 objects 或 refs 目录
• 在 ~/.claude 中，或 CLAUDE_CONFIG_DIR 指向的目录中：其大部分内容，加上 ~/.claude.json 和 .credentials.json 凭证存储

​

网络隔离

• 域名限制：Claude Code 默认不预先允许任何域名。命令第一次需要新的域名时，Claude Code 会提示批准；在自动模式中，Claude 会根据按命令允许的域名在命令本身上命名命令需要的主机。
• 批准选择：如果在提示时选择”是”，Claude Code 会在当前会话的其余时间内允许该主机，之后连接到同一主机时不会再次提示。如果选择”是，以后不再询问”，Claude Code 会将 WebFetch(domain:...) 允许规则保存到你的本地设置，因此该主机在未来会话中保持允许。
• 预先允许的域名：使用 allowedDomains 预先允许域名以完全避免提示。Claude Code 也预先允许来自 WebFetch(domain:...) 允许规则的域名，如权限规则中所述。
• 严格允许列表：如果在用户、托管或 CLI --settings 设置中将 strictAllowlist 设置为 true，Claude Code 会拒绝沙箱化命令访问允许列表外的任何主机，而不是提示。允许列表与沙箱否则会提示的相同：allowedDomains 加上来自 WebFetch(domain:...) 允许规则的域名，或当设置了 allowManagedDomainsOnly 时仅限托管设置条目。Claude Code 仅对沙箱化命令强制执行此；进程内工具（例如 WebFetch）仍然遵循其权限规则。在存储库的 .claude/settings.json 或 .claude/settings.local.json 中设置它没有效果。需要 Claude Code v2.1.219 或更高版本。
• 托管锁定：如果在托管设置中设置了 allowManagedDomainsOnly，非允许的域名会自动被阻止而不是提示，只有来自托管设置的 allowedDomains 和 WebFetch(domain:...) 允许规则被尊重。
• 企业代理：当你的网络要求出站流量通过企业代理时，按照代理配置的描述在你的设置的 env 块中设置 HTTPS_PROXY、HTTP_PROXY 和 NO_PROXY，以便后台代理也能获得它们，或在你启动 Claude Code 的环境中设置。Claude Code 强制执行域名允许列表，然后通过该上游代理隧道允许的连接。
• 自定义代理支持：高级用户可以在出站流量上实现自定义规则
• 全面覆盖：限制适用于所有脚本、程序和由命令生成的子进程

​

自动模式中按命令允许的域名

​

域名列表中的 IPv6 地址

• 拒绝列表：Claude Code 拒绝条目解析为的每种读法，因此无论你的意思是哪种读法都被阻止。对于没有可解析读法的条目，Claude Code 不阻止任何内容。
• 允许列表：Claude Code 永远不允许超过你写的内容。当主机和端口读法干净地解析时，它会将模糊条目重写为其主机和端口读法，并可能完全删除条目，而不是扩大允许列表。

​

操作系统级强制执行

• macOS：使用 Seatbelt 进行沙箱强制执行
• Linux：使用 bubblewrap 进行隔离
• WSL2：使用 bubblewrap，与 Linux 相同

​

沙箱隔离与权限和权限模式的关系

​

权限规则

• 权限规则控制 Claude Code 可以使用哪些工具，并在任何工具运行之前进行评估。它们适用于每个工具：Bash、Read、Edit、WebFetch、MCP 和其他工具，除了拒绝或询问规则无法阻止 EndConversation，而任何其他工具仍然存在。
• 沙箱隔离提供操作系统级别的强制执行，限制 shell 命令在文件系统和网络级别可以访问的内容。它仅适用于 Bash、PowerShell 和 Monitor 命令及其子进程。

​

权限模式

​

为你的组织配置沙箱

​

使用托管设置强制执行沙箱

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false
  }
}

• failIfUnavailable：缺少的依赖项（例如 Linux 上的 bubblewrap）会阻止 Claude Code 启动，而不是显示警告并回退到非沙箱化执行
• allowUnsandboxedCommands: false：Claude Code 忽略 dangerouslyDisableSandbox 逃生舱，因此在沙箱下失败的命令无法在其外重试

​

防止开发者扩大策略

​

自定义代理配置

• 解密和检查 HTTPS 流量
• 应用自定义过滤规则
• 记录所有网络请求
• 与现有安全基础设施集成

{
  "sandbox": {
    "network": {
      "httpProxyPort": 8080,
      "socksProxyPort": 8081
    }
  }
}

​

故障排除

• 命令因主机不允许错误而失败：许多 CLI 工具需要到达特定的主机。在提示时授予权限会将主机添加到你的允许列表，以便该工具在将来在沙箱内运行。
• jest 挂起或失败：watchman 与沙箱不兼容。改为运行 jest --no-watchman。
• Go 基础 CLI 在 macOS 上 TLS 验证失败：gh、gcloud 和 terraform 等工具在 Seatbelt 下可能无法进行 TLS 验证。在 excludedCommands 中列出这些工具。如果你使用 httpProxyPort 与 MITM 代理和自定义 CA，请改为将 enableWeakerNetworkIsolation 设置为 true。
• open、osascript 或基于浏览器的身份验证流在 macOS 上因错误 -600 失败：沙箱默认阻止 Apple Events。在你的用户、托管或 CLI 设置中将 allowAppleEvents 设置为 true 以允许它们。项目设置对此密钥被忽略。启用它会移除代码执行隔离，因为沙箱化命令随后可以在没有用户提示的情况下启动其他未沙箱化的应用程序，并向运行的应用程序发送 AppleScript 命令，受 macOS 自动化同意提示 (TCC) 的约束。或者，将命令添加到 excludedCommands。
• docker 命令失败：docker 与沙箱不兼容。将 docker * 添加到 excludedCommands。
• pbcopy、xclip 或 wl-copy 不更新剪贴板：这些剪贴板实用程序可能无法从沙箱内到达系统剪贴板，在这种情况下，管道传输到它们的文本不会到达。 要将 Claude 的输出放在你的剪贴板上，请要求 Claude 在其响应中打印它，然后运行 /copy。/copy 从 Claude Code 进程而不是从沙箱化命令写入剪贴板。 当 Claude 将文本管道传输到这些工具之一时，将该工具添加到 excludedCommands 本身不会将该调用从沙箱中取出。
• git 命令因 unable to unlink old 失败：git merge、git checkout 和类似命令在需要替换沙箱拒绝写入的文件时以这种方式失败，无论该文件是在 protected path 下（如 .claude/skills），在你的 denyWrite 条目之一下，还是在沙箱允许命令写入的目录之外。在 Linux 和 WSL2 上，错误以 Read-only file system 结尾。 失败后，Claude 可能会 提供在沙箱外重新运行命令；批准该重试，或在另一个终端中自己运行 git 命令。如果你已将 allowUnsandboxedCommands 设置为 false，Claude 无法提供重试，所以自己运行该命令。如果相同的 git 命令经常失败，将其添加到 excludedCommands。
• Bubblewrap 在容器内启动失败：在无特权容器中，bubblewrap 无法挂载新的 /proc 文件系统，所以沙箱化命令因 bwrap 错误（如 Can't mount proc on /newroot/proc: Operation not permitted）失败。将 enableWeakerNestedSandbox 设置为 true，以便内部沙箱绑定挂载容器的现有 /proc。仅在外部容器已提供你需要的隔离边界时使用此设置，因为它向沙箱化命令公开进程信息，而新的 /proc 挂载会隐藏这些信息。
• 0 字节只读文件出现在 .claude 设置路径，“是的，不要再问”不保存：在 Linux 和 WSL2 上，沙箱通过在沙箱化命令运行时在那里创建 0 字节只读占位符来对不存在的文件持有写入拒绝。沙箱在之后移除占位符。如果会话在该清理运行之前被杀死，例如通过 SIGKILL，占位符会留下。后续会话在每次启动时再次将它们绑定为只读，所以设置写入（如保存权限选择）在其中一个坐着的地方失败。 运行 claude doctor 以列出剩余的占位符文件。Stale sandbox mask files left by a killed session 警告命名最多三个，并计算其余的。在该项目中没有其他 Claude Code 会话运行时，使用 rm 删除每个文件。在 v2.1.257 之前，Claude Code 留下相同的占位符而不标记它们。
• --dangerously-skip-permissions 以 root 身份失败：当在 Linux 和 macOS 上以 root 身份或通过 sudo 运行时，此标志被阻止，因为 root 访问加上没有权限提示可以修改系统上的任何文件或服务。检查在识别的沙箱内自动跳过。要在容器中自主运行，请使用 dev container 配置，它以非 root 用户身份运行 Claude Code。

​

限制

​

安全限制

• 网络过滤：沙箱限制进程可以连接的域。默认情况下，内置代理不会终止或检查出站流量上的 TLS，因此不会检查加密连接的内容。实验性的 network.tlsTerminate 设置在代理处终止 TLS 以进行 mask 凭证替换，但不添加内容过滤。你负责确保只有受信任的域在你的策略中被允许。

• 通过 Unix 套接字的权限提升：allowUnixSockets 配置可能会无意中授予对可能导致沙箱绕过的系统服务的访问权限。例如，允许访问 /var/run/docker.sock 有效地通过 Docker 套接字授予对主机系统的访问权限。仔细考虑你通过沙箱允许的任何 Unix 套接字。
• 文件系统权限提升：过于宽泛的文件系统写入权限可能导致权限提升攻击。允许写入包含 $PATH 中的可执行文件、系统配置目录或用户 shell 配置文件（例如 .bashrc 或 .zshrc）的目录可能导致当其他用户或系统进程访问这些文件时在不同的安全上下文中执行代码。
• Linux 沙箱强度：Linux 实现提供强大的文件系统和网络隔离，但包括一个 enableWeakerNestedSandbox 模式，使其能够在 Docker 环境中工作而无需特权命名空间，或在禁用无特权用户命名空间的 Linux 主机上。此选项大大削弱了安全性，应仅在其他隔离被强制执行时使用。
• macOS 上的 Apple Events：macOS 沙箱默认阻止 Apple Events。allowAppleEvents 设置解除此限制，以便 open 和 osascript 等工具可以工作，但它移除了代码执行隔离：沙箱化命令可以在没有用户提示的情况下启动其他未沙箱化的应用程序，并可以向运行的应用程序发送 AppleScript 命令，受限于每个应用程序的 macOS 自动化同意提示 (TCC)。它仅从用户、托管或 CLI 设置中被遵守。项目设置无法启用它。

​

平台和工具兼容性

• 平台支持：支持 macOS、Linux 和 WSL2。不支持 WSL1 和原生 Windows。
• 性能开销：最小，但某些文件系统操作可能稍慢。
• 工具兼容性：某些需要特定系统访问模式的工具可能需要配置调整，或可能需要在沙箱外运行。

​

范围

• 内置文件工具：Read、Edit 和 Write 直接使用权限系统，而不是通过沙箱运行。请参阅 permissions。
• 计算机使用：当 Claude 打开应用程序并控制你的屏幕时，它在你的实际桌面上运行，而不是在隔离的环境中。每个应用程序的权限提示控制每个应用程序。请参阅 CLI 中的计算机使用 或 Desktop 中的计算机使用。
• 环境变量：沙箱化 Bash 命令默认继承父进程环境，包括在那里设置的任何凭证。使用 sandbox.credentials 为沙箱化命令取消设置或掩盖特定变量，或设置 CLAUDE_CODE_SUBPROCESS_ENV_SCRUB 以从所有子进程中删除凭证。
• 子代理：subagents 在与父会话相同的进程中运行，并使用相同的沙箱配置。当在父会话中启用沙箱时，子代理内的 Bash 命令被沙箱化。

​

另请参阅

• Sandbox environments：比较内置沙箱与开发容器、容器和虚拟机
• Security：全面的安全功能和最佳实践
• Permissions：权限配置和访问控制
• All settings：每个设置键
• CLI reference：命令行选项