Claude Code 开启 sandbox 后 curl 无法访问局域网：excludedCommands 配置与验证

1. 问题现场sandbox 一开curl 就打不通局域网了Claude Code 的 sandbox 模式是个好东西它把 Bash 工具执行环境关进一个受限容器里文件读写、网络出口都按settings.json里的规则走避免 AI 在自动执行命令时误删文件或者把数据发到不该去的地方。但很多人第一次开启 sandbox 之后会遇到一个很具体的坑在 Claude Code 里让模型跑curl去访问宿主机所在局域网里的设备比如 192.168.1.50 上的测试服务、内网 API、树莓派面板命令直接失败终端里刷出一行Uses proxy env variable no_proxy localhost,127.0.0.1,::1,*.local,.local,169.254.0.0/16,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16的提示请求根本没发出去。这个现象在 WSL2 NAT 网络模式下尤其常见。宿主机是 Windows 11WSL2 里跑 UbuntuClaude Code 装在 WSL 中局域网设备在 Windows 那一侧。sandbox 启动后会自动注入http_proxyhttp://localhost:3128、https_proxyhttp://localhost:3128同时把no_proxy/NO_PROXY设成上面那一长串私有网段。按理说192.168.0.0/16已经在no_proxy里curl 应该绕过代理直连才对但实际表现是请求被 sandbox 的网络层拦下自动化测试脚本直接挂掉。我试过在~/.claude/settings.json的env字段里把no_proxy和NO_PROXY显式设为空字符串重启 Claude Code 后没有任何变化——因为这两个变量是 sandbox 运行时自己覆盖写入的用户层的env优先级不够。真正能解决这个问题的入口是excludedCommands把curl从 sandbox 里排除出去让它以普通进程身份执行自然就不受代理和网络白名单约束了。但这里还埋了第二个坑直接写excludedCommands: [docker, curl]是不生效的。Claude Code 官方文档早期给的示例就是这种裸命令名写法实际匹配逻辑要求带通配符。必须写成curl:*这种形式命令才会被正确识别为排除项。这个细节在仓库 issue 里被反复提到属于文档和实现不一致的 bug。这篇就围绕excludedCommands这个配置点把 settings.json 骨架、验证命令、以及几个容易踩的错一起讲清楚。适合正在用 Claude Code 做内网联调、自动化测试、或者本地服务探测的开发者。2. 前置准备TaoToken 接入与 Claude Code 环境确认在动settings.json之前先把模型接入这条链路理顺。Claude Code 本身是个 CLI 客户端它需要一个能响应 Anthropic 协议的后端。我用的是 TaoToken 的 Coding Plan专门给长期编码和 Agent 场景用的套餐走https://taotoken.net/api这个入口不需要额外折腾网络层的东西。接入步骤不复杂核心是拿到 API Key 并写进 Claude Code 的配置。你可以先到控制台创建一个 Key控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsole创建完 Key 之后在 Claude Code 里配置环境变量。如果你用的是 Claude Code 原生的 Anthropic 接入方式可以这样设export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的key如果你更习惯用 Claude Code 的 Coding Plan 模式直接在~/.claude/settings.json里配也行。不过要注意settings.json同时承载 sandbox 配置和模型配置字段别写串了。下面是一个把两者放在一起的骨架你可以按需删减{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的key }, sandbox: { enabled: true, autoAllowBashIfSandboxed: true, allowUnsandboxedCommands: false, excludedCommands: [docker:*, curl:*], filesystem: { allowWrite: [//tmp/build], denyRead: [ ~/.config/opencode, ~/.codex, ~/.local/share/opencode, ~/.ssh ] }, network: { allowedDomains: [github.com], allowUnixSockets: [/var/run/docker.sock] } } }这里excludedCommands就是本篇的主角。注意docker:*和curl:*都带了:*后缀这是让排除规则生效的关键。allowUnsandboxedCommands设为false表示除了排除列表里的命令其他命令一律在 sandbox 内执行安全边界更清晰。环境确认方面先在 WSL 里跑一下版本确保 Claude Code 是较新的版本2.1.x 以上对 excludedCommands 的匹配逻辑才稳定claude --version # 输出示例2.1.81 (Claude Code)再确认 WSL 的网络模式。如果你在.wslconfig里设了networkingModemirrored局域网访问行为和 NAT 模式不一样排查思路要调整。NAT 模式下 WSL 有自己的虚拟网卡访问 Windows 宿主机所在局域网需要经过 NAT 转发sandbox 的代理层更容易在这里插一脚。3. 可复制配置excludedCommands 的正确写法与匹配规则excludedCommands的语义是列表中的命令在执行时跳过 sandbox 包装直接以当前用户身份运行。这意味着这些命令不会继承 sandbox 注入的http_proxy、https_proxy、no_proxy也不会受network.allowedDomains白名单限制。对于curl这种需要访问任意内网地址的调试工具这正是我们想要的。匹配规则这块要重点说。Claude Code 内部对命令的匹配不是简单的字符串相等而是按「命令 参数」的模式去比对。裸写curl只能匹配到不带任何参数、单独执行的curl而实际使用中你几乎总是带参数比如curl -v http://192.168.1.50:8080/health。所以必须用通配符形式excludedCommands: [curl:*, docker:*, wget:*, nc:*]curl:*里的:*表示「命令名后面跟任意参数都匹配」。这个写法在官方 issue 里被确认是当前版本的预期行为文档示例没跟上实现导致很多人照着文档写curl然后发现不生效。如果你还想排除其他网络调试命令可以一起加进去。下面是一个更完整的排除列表覆盖常见的联调场景{ sandbox: { enabled: true, autoAllowBashIfSandboxed: true, allowUnsandboxedCommands: false, excludedCommands: [ docker:*, curl:*, wget:*, nc:*, telnet:*, ping:*, ssh:*, scp:* ], filesystem: { allowWrite: [//tmp/build], denyRead: [~/.ssh, ~/.aws, ~/.config/gcloud] }, network: { allowedDomains: [github.com, registry.npmjs.org], allowUnixSockets: [/var/run/docker.sock] } } }这里有个权衡要提醒排除的命令越多sandbox 的保护范围就越小。curl:*被排除后AI 理论上可以用 curl 把数据发到任意地址。所以建议只在确实需要内网联调的开发阶段这么配生产环境或者处理敏感仓库时把curl:*去掉改用network.allowedDomains精确放行。另外excludedCommands和network.allowedDomains是两条独立的路径。前者是「整个命令不进沙箱」后者是「命令在沙箱内但允许访问这些域名」。如果你只是想让 curl 访问某个固定的内网域名理论上可以走allowedDomains但内网 IP 段和端口组合往往很灵活用excludedCommands更省事。配置改完后Claude Code 需要重启才能重新加载settings.json。在 WSL 里直接exit再重新claude即可不需要重启整个 WSL 实例。4. 验证请求确认 curl 真的绕过了 sandbox 代理配置写完怎么确认它生效了最直接的办法是在 Claude Code 的 Bash 工具里跑一条带-v的 curl观察输出里有没有代理相关的行。先准备一个局域网目标。假设你 Windows 宿主机所在局域网里有一台设备跑着 HTTP 服务地址是192.168.1.50:8080。在 Claude Code 里让它执行curl -v --max-time 5 http://192.168.1.50:8080/health如果excludedCommands生效你会看到类似这样的输出没有Uses proxy env variable的提示连接直接打到目标 IP* Trying 192.168.1.50:8080... * Connected to 192.168.1.50 (192.168.1.50) port 8080 GET /health HTTP/1.1 Host: 192.168.1.50:8080 User-Agent: curl/8.5.0 Accept: */* HTTP/1.1 200 OK Content-Type: application/json {status:ok}如果配置没生效输出里会先出现代理提示然后连接localhost:3128失败* Uses proxy env variable no_proxy localhost,127.0.0.1,::1,*.local,.local,169.254.0.0/16,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16 * Uses proxy env variable http_proxy http://localhost:3128 * Trying 127.0.0.1:3128... * connect to 127.0.0.1 port 3128 failed: Connection refused * Failed to connect to 192.168.1.50 port 8080看到Uses proxy env variable就说明 curl 还在 sandbox 里跑excludedCommands没匹配上。这时候回去检查是不是漏了:*后缀。除了看 curl 自己的输出还可以在命令里直接打印环境变量确认代理变量是否被清掉env | grep -i proxy在排除生效的情况下这条命令在 Claude Code 的 Bash 工具里执行时http_proxy和https_proxy应该不存在或者为空。如果还能看到http_proxyhttp://localhost:3128说明命令仍在 sandbox 内。再补一个更贴近自动化测试的验证写一个循环探测多个内网端口确认批量请求都能通。for port in 8080 8081 9090; do code$(curl -s -o /dev/null -w %{http_code} --max-time 3 http://192.168.1.50:$port/health) echo port $port - $code done预期输出每个端口都返回200或至少是一个 HTTP 状态码而不是000连接失败。如果全是000回到上一节检查配置。5. 常见错排查为什么改了还是不生效这一节把几个高频坑列出来基本都是我在实际调试中撞过的。错误一excludedCommands写了裸命令名。这是最常见的。curl不生效必须curl:*。同理docker要写成docker:*。官方文档早期示例是裸名很多人直接抄了。错误二改的是项目级 settings 而不是用户级。Claude Code 会读多个层级的settings.json用户级在~/.claude/settings.json项目级在项目根目录的.claude/settings.json。如果你在项目级改了但用户级有覆盖或者反过来实际生效的可能不是你以为的那份。排查时先确认当前加载的是哪个文件可以在 Claude Code 里执行cat ~/.claude/settings.json | grep -A 5 excludedCommands错误三JSON 语法错误导致整个 sandbox 配置被忽略。多一个逗号、少一个引号Claude Code 可能静默跳过 sandbox 段。改完配置后用jq校验一下jq . ~/.claude/settings.json /dev/null echo JSON OK || echo JSON ERROR错误四WSL2 网络模式是 mirrored 但按 NAT 思路排查。如果你在.wslconfig里设了networkingModemirroredWSL 和 Windows 共享网络接口局域网访问路径完全不同。这时候 curl 失败可能不是 sandbox 的问题而是 Windows 防火墙拦了。先确认网络模式cat /mnt/c/Users/你的用户名/.wslconfig错误五allowUnsandboxedCommands设为true后以为万事大吉。这个字段设为true表示允许命令在 sandbox 外执行但它不等于自动排除。命令是否走 sandbox 还是由excludedCommands和autoAllowBashIfSandboxed共同决定。把它设true只是给了「可以逃逸」的许可具体逃不逃还得看排除列表。错误六改了配置没重启 Claude Code。settings.json是启动时加载的运行中修改不会热生效。改完必须退出重进。如果以上都排查完还是不行可以到 TaoToken 的接入文档里对照一下 API 配置部分确认模型接入层没有引入额外的代理设置接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc6. 按场景选入口排障、验证、长期编码各走各的路excludedCommands这个配置点解决的是 sandbox 和局域网调试的冲突属于接入排障范畴。如果你在配 Key、调 Base URL、或者遇到 401/403 这类接入层报错直接去 API Keys 页面重新生成一个 Key 对照排查最快API Keyshttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys如果你只是想快速验证某个模型在当前配置下能不能正常响应不想动 Claude Code 的本地配置用模型对话页面直接发一条测试消息就行省去 CLI 层的变量干扰模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentchat而如果你像我一样日常大量时间花在 Claude Code 里跑 Agent、做多轮编码任务那 Coding Plan 的长期套餐更划算额度模型和并发策略都是按编码场景调的Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan回到 sandbox 这个话题最后给一个实用建议把excludedCommands当成开发阶段的临时开关而不是永久配置。内网联调结束后把curl:*从列表里拿掉让 sandbox 恢复完整保护。如果确实需要长期保留内网访问能力考虑在network.allowedDomains里精确放行目标域名或 IP 段比整个命令逃逸更可控。配置这东西宽一分方便窄一分安全按当前任务的实际需要来调就行。