Claude Code 沙箱环境深度解析
一、为什么需要沙箱？
Claude Code 是一个能直接操作文件系统、执行 Shell 命令的 AI 编程助手。这意味着它天然具备\”破坏力\”——一条错误的 rm -rf 或一次意外的网络请求，都可能造成不可逆的损失。
沙箱（Sandbox）的核心目标是：在不影响正常开发工作流的前提下，将 AI 的执行权限限制在可控边界内。
Claude Code 的沙箱体系分为两个独立层次，各自解决不同粒度的安全问题：
#mermaid-svg-zNrMXBUVrhZX5XfL{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-zNrMXBUVrhZX5XfL .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-zNrMXBUVrhZX5XfL .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-zNrMXBUVrhZX5XfL .error-icon{fill:#552222;}#mermaid-svg-zNrMXBUVrhZX5XfL .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-zNrMXBUVrhZX5XfL .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-zNrMXBUVrhZX5XfL .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-zNrMXBUVrhZX5XfL .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-zNrMXBUVrhZX5XfL .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-zNrMXBUVrhZX5XfL .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-zNrMXBUVrhZX5XfL .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-zNrMXBUVrhZX5XfL .marker{fill:#333333;stroke:#333333;}#mermaid-svg-zNrMXBUVrhZX5XfL .marker.cross{stroke:#333333;}#mermaid-svg-zNrMXBUVrhZX5XfL svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-zNrMXBUVrhZX5XfL p{margin:0;}#mermaid-svg-zNrMXBUVrhZX5XfL .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-zNrMXBUVrhZX5XfL .cluster-label text{fill:#333;}#mermaid-svg-zNrMXBUVrhZX5XfL .cluster-label span{color:#333;}#mermaid-svg-zNrMXBUVrhZX5XfL .cluster-label span p{background-color:transparent;}#mermaid-svg-zNrMXBUVrhZX5XfL .label text,#mermaid-svg-zNrMXBUVrhZX5XfL span{fill:#333;color:#333;}#mermaid-svg-zNrMXBUVrhZX5XfL .node rect,#mermaid-svg-zNrMXBUVrhZX5XfL .node circle,#mermaid-svg-zNrMXBUVrhZX5XfL .node ellipse,#mermaid-svg-zNrMXBUVrhZX5XfL .node polygon,#mermaid-svg-zNrMXBUVrhZX5XfL .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-zNrMXBUVrhZX5XfL .rough-node .label text,#mermaid-svg-zNrMXBUVrhZX5XfL .node .label text,#mermaid-svg-zNrMXBUVrhZX5XfL .image-shape .label,#mermaid-svg-zNrMXBUVrhZX5XfL .icon-shape .label{text-anchor:middle;}#mermaid-svg-zNrMXBUVrhZX5XfL .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-zNrMXBUVrhZX5XfL .rough-node .label,#mermaid-svg-zNrMXBUVrhZX5XfL .node .label,#mermaid-svg-zNrMXBUVrhZX5XfL .image-shape .label,#mermaid-svg-zNrMXBUVrhZX5XfL .icon-shape .label{text-align:center;}#mermaid-svg-zNrMXBUVrhZX5XfL .node.clickable{cursor:pointer;}#mermaid-svg-zNrMXBUVrhZX5XfL .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-zNrMXBUVrhZX5XfL .arrowheadPath{fill:#333333;}#mermaid-svg-zNrMXBUVrhZX5XfL .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-zNrMXBUVrhZX5XfL .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-zNrMXBUVrhZX5XfL .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-zNrMXBUVrhZX5XfL .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-zNrMXBUVrhZX5XfL .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-zNrMXBUVrhZX5XfL .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-zNrMXBUVrhZX5XfL .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-zNrMXBUVrhZX5XfL .cluster text{fill:#333;}#mermaid-svg-zNrMXBUVrhZX5XfL .cluster span{color:#333;}#mermaid-svg-zNrMXBUVrhZX5XfL div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-zNrMXBUVrhZX5XfL .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-zNrMXBUVrhZX5XfL rect.text{fill:none;stroke-width:0;}#mermaid-svg-zNrMXBUVrhZX5XfL .icon-shape,#mermaid-svg-zNrMXBUVrhZX5XfL .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-zNrMXBUVrhZX5XfL .icon-shape p,#mermaid-svg-zNrMXBUVrhZX5XfL .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-zNrMXBUVrhZX5XfL .icon-shape .label rect,#mermaid-svg-zNrMXBUVrhZX5XfL .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-zNrMXBUVrhZX5XfL .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-zNrMXBUVrhZX5XfL .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-zNrMXBUVrhZX5XfL :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}
Layer 1: 进程级沙箱 (BashTool Sandbox)
Layer 2: 容器级沙箱 (DevContainer)
Docker 容器
iptables 防火墙(init-firewall.sh)
ipset 域名白名单
BashTool 执行层
权限系统(PermissionManager)
网络域名限制sandbox.network
文件系统限制sandbox.filesystem
Linux: bubblewrap (bwrap)
macOS: sandbox-exec
用户 / Claude Agent
| 进程级 | bubblewrap / sandbox-exec | 仅 BashTool 执行的命令 | settings.json 的 sandbox.* |
| 容器级 | Docker + iptables + ipset | 整个容器的所有出站流量 | .devcontainer/init-firewall.sh |
二、架构全景：两层防御纵深
三、进程级沙箱：BashTool Sandbox
3.1 配置项全解
所有配置均位于 settings.json 的 sandbox 字段下，以下是完整的配置结构（来自官方示例）：
{
\”allowManagedPermissionRulesOnly\”: true,
\”sandbox\”: {
\”enabled\”: true,
\”autoAllowBashIfSandboxed\”: false,
\”allowUnsandboxedCommands\”: false,
\”excludedCommands\”: [],
\”network\”: {
\”allowUnixSockets\”: [],
\”allowAllUnixSockets\”: false,
\”allowLocalBinding\”: false,
\”allowedDomains\”: [],
\”httpProxyPort\”: null,
\”socksProxyPort\”: null
},
\”enableWeakerNestedSandbox\”: false
}
}
| sandbox.enabled | bool | false | 总开关，开启后所有 Bash 命令进入沙箱 |
| sandbox.autoAllowBashIfSandboxed | bool | false | 沙箱内命令自动放行，跳过权限弹窗 |
| sandbox.allowUnsandboxedCommands | bool | true | 是否允许命令在沙箱外执行 |
| sandbox.excludedCommands | string[] | [] | 豁免列表，这些命令绕过沙箱直接执行 |
| sandbox.network.allowedDomains | string[] | [] | 沙箱内可访问的域名白名单（支持通配符） |
| sandbox.network.allowUnixSockets | string[] | [] | 允许访问的 Unix Socket 路径列表 |
| sandbox.network.allowAllUnixSockets | bool | false | 允许访问所有 Unix Socket |
| sandbox.network.allowLocalBinding | bool | false | 允许绑定本地端口 |
| sandbox.network.httpProxyPort | int|null | null | HTTP 代理端口（用于流量审计） |
| sandbox.network.socksProxyPort | int|null | null | SOCKS 代理端口 |
| sandbox.failIfUnavailable | bool | false | 沙箱依赖缺失时报错退出，而非静默降级 |
| sandbox.bwrapPath | string | 自动检测 | Linux/WSL 下 bubblewrap 二进制路径 |
| sandbox.socatPath | string | 自动检测 | Linux/WSL 下 socat 二进制路径 |
3.2 权限决策流程
当 Claude 生成一条 Bash 命令时，系统经历以下决策链：
\”Shell (/bin/bash)\”
\”Sandbox Runtime\”
\”PermissionManager\”
\”BashTool\”
\”Agent (Claude)\”
\”Shell (/bin/bash)\”
\”Sandbox Runtime\”
\”PermissionManager\”
\”BashTool\”
\”Agent (Claude)\”
#mermaid-svg-AQTBjwtbz9eIkv04{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{str
