Claude Code 沙箱（sandbox）是什么：限制命令能读写哪些文件、访问哪些网站，怎么开、有哪些限制

本文根据 Claude Code 官方文档《Configure the sandboxed Bash tool》整理，资料核对于 2026-11-05。配图为本站整理的示意图，不是界面截图。本站（bigolab.com）不是 Anthropic 官方网站。

适用于谁

• 搜「claude code 电脑安全」「claude code 智能体安全」，担心它乱改文件、乱联网的人；
• 不想一直点确认，又希望命令有边界的人；
• 在 Windows 上用 Claude Code，想知道能不能开沙箱的人。

结论先说

1. 沙箱是操作系统层面的边界，限制的是 Claude 运行的 shell 命令（Bash、PowerShell、Monitor）以及它们启动的进程，能读写哪些文件、连哪些网络域名。
2. 默认关闭。在会话里运行 /sandbox 开启，或在设置文件里把 sandbox.enabled 设为 true。
3. 只管 shell 命令：Claude 自带的 Read、Edit、Write、WebFetch、WebSearch 工具，以及钩子、本地 MCP 服务器、状态栏命令等，都不在沙箱里，它们受权限规则管理。
4. 平台：macOS、Linux、WSL2 支持；原生 Windows 上命令不受沙箱限制，官方建议在 WSL2 发行版里运行 Claude Code。
5. 不是绝对安全：官方明确说它降低风险但不是完整的隔离边界。

图：本站根据 Claude Code 官方文档：Sandboxing 整理的示意图

一、沙箱默认的边界

官方表格的大意：

• 写：工作目录、每用户临时目录，以及你用 --add-dir、/add-dir 或 permissions.additionalDirectories 加入的目录；「受保护路径」始终不可写；
• 读：机器上的大部分位置，包括 ~/.ssh、~/.aws/credentials 这类凭据文件。要收紧用 filesystem.denyRead 或 credentials 设置；
• 网络：命令没有直接出网路径，连接经过本机上的代理，代理按「允许的域名」逐个检查，这份名单一开始是空的；
• 环境变量：继承 Claude Code 的环境，包括里面的密钥；可用 credentials 设置或 CLAUDE_CODE_SUBPROCESS_ENV_SCRUB 处理。

受保护路径包括：.claude 下的设置文件和 skills、agents、commands、hooks 目录，.mcp.json，以及 .bashrc、.zshrc、.gitconfig、.vscode、.idea 和 .git 里的 hooks、config 等。官方的理由是：能改这些文件的命令可能给自己加权限，或添加由 Claude Code 在沙箱外执行的钩子、MCP 服务器。

二、怎么开启

图：本站根据 Claude Code 官方文档：Sandboxing 整理的示意图

1. Linux 和 WSL2 先装依赖：沙箱依赖 bubblewrap 和 socat。Ubuntu / Debian 用 sudo apt-get install bubblewrap socat，Fedora 用 sudo dnf install bubblewrap socat。macOS 用系统自带的 Seatbelt，不用装。没装也可以先运行 /sandbox，面板会告诉你缺什么；
2. 运行 /sandbox：面板有 Mode、Overrides、Config 三个标签，缺依赖时会有 Dependencies 标签；如果只有 Dependencies 一个标签，说明沙箱还不能启动；
3. 选模式（见下节）；
4. 让 Claude 跑一条命令，比如构建或测试。第一次需要新的网络域名时，Claude Code 会提示你批准；
5. 验证：官方建议让 Claude 执行 touch ~/sandbox-probe，在沙箱内应失败（macOS 报 Operation not permitted，Linux 和 WSL2 报 Read-only file system）。注意你自己在 ! 提示符下输入的命令通常不在沙箱里，所以不能用来测试。

选择的模式会保存到项目的 .claude/settings.local.json；要对所有项目启用，把 sandbox.enabled 写进 ~/.claude/settings.json。设置文件的位置见 /guides/claude-code-settings-json。单次会话也可以用 --settings 传入 JSON。

官方有一条重要警告：平台不支持或启动时依赖检查失败时，默认会不加沙箱直接运行命令。 想让它直接退出，把 sandbox.failIfUnavailable 设为 true。

三、两种模式

官方说两种模式下沙箱的限制完全相同，区别只在是否自动批准：

• 自动允许（auto-allow）：在沙箱内运行的命令不再弹出确认。但仍有例外：被 Bash 拒绝规则匹配的命令照样被拦；rm 或 rmdir 指向关键路径时仍走常规权限流程；Bash(git push *) 这类按内容限定的 ask 规则仍会提示；
• 常规权限：即使命令在沙箱里，仍保留常规权限提示。

这也是减少确认弹窗的一种方式，对照 /guides/claude-code-stop-asking-permission 和 /guides/claude-code-permission-modes。

四、两个要小心的点

1. 沙箱外重试（unsandboxed retry）。命令在沙箱里失败时，Claude 可能会带 dangerouslyDisableSandbox 参数重试，此时命令不受沙箱限制。谁来批准取决于权限模式：bypassPermissions 下不提示直接运行；手动和 acceptEdits 模式会弹出标题为「Bash command (unsandboxed)」的确认；自动模式由分类器判断；dontAsk 模式拒绝。官方还说，如果有匹配的 allow 规则（如 Bash(curl *)），它也会批准这次重试。想完全禁止，可以把 allowUnsandboxedCommands 设为 false，例如：

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

2. 凭据保护。sandbox.credentials 可以声明要保护的文件和环境变量，官方示例是拒绝读取 ~/.aws/credentials 和 ~/.ssh，并从沙箱命令的环境里移除 GITHUB_TOKEN、NPM_TOKEN：

json
{
  "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" }
      ]
    }
  }
}

五、官方列出的限制

• 网络过滤只看域名：内置代理默认不解密也不检查 TLS，内容不被检查。官方警告：放行 github.com 这类宽泛域名可能留下数据外泄的通道，沙箱内的代码可能用域前置（domain fronting）等手段访问名单外的主机；更强的保证需要自建能终止 TLS 并检查流量的代理；
• Unix socket：allowUnixSockets 配置不当可能造成权限提升；
• 命令之外的东西不受保护（见开头第 3 点）；想把所有工具和进程放在同一条边界里，官方建议把 Claude Code 进程本身放进容器、虚拟机或沙箱运行时。

更多关于密钥与权限的通用习惯见 /guides/ai-coding-security-secrets-permissions。想长期使用 Claude Code，可了解 /chongzhi/claude-code。

常见问题

Q：Windows 上能用沙箱吗？

原生 Windows 不行；官方说要在 WSL2 里运行 Claude Code。WSL 的相关说明见 /guides/claude-code-install-methods-git-npm-official。

Q：开了沙箱，命令一直报网络错误？

默认允许域名为空，需要把需要的域名加入 network.allowedDomains，或在提示时批准。官方的 Configure sandboxing 一节有细节。

Q：沙箱能拦住 Claude 的 Edit 工具吗？

不能，文件工具受权限规则管理，沙箱只管 shell 命令。

相关教程

• /guides/claude-code-permission-modes：权限模式
• /guides/claude-code-stop-asking-permission：少弹确认
• /guides/ai-coding-security-secrets-permissions：AI 编程的密钥与权限

参考资料

• Claude Code 官方文档：Configure the sandboxed Bash tool — https://code.claude.com/docs/en/sandboxing