实战 SOP
实战 SOP

不给 agent root:Claude Code 沙箱装机实操指南

给 agent 加沙箱但别给 root:Anthropic 开源沙箱工具 srt(anthropics/sandbox-runtime,Apache-2.0,6,615 stars,仓库 2025-10 已建)装机实操。npm 全局安装逐字实录、~/.srt-settings.json 配置原文、三平台原语差异与默认策略三层级(原生/默认/宽松),Windows 三层真相如实呈现:srt CLI 仍是 Alpha、Schannel 属硬限制无解、Claude Code 原生 Windows 不运行沙箱须 WSL2;84% 拦截率为官方自报口径,附 8 条社区坑清单(#139/#160/#122 已修、Ubuntu 24.04 sysctl 等)。

发布于 2026年10月26日9 分钟阅读
<!-- claude-code-sandbox-runtime-sop | sop | 不给 agent root:Claude Code 沙箱装机实操指南 -->

用 Claude Code 干活的人都熟悉这个画面:agent 想跑一条命令,终端弹出权限确认;跑下一条,又弹一条。半小时下来你点了二三十次「允许」,手指已经开始机械地按 1——而 Anthropic 自家遥测显示,用户批准了约 93% 的权限提示【官方,出自其工程博客姊妹篇《How we contain Claude》】。批准率高到这个程度,说明提示这道门已经形同虚设:要么是你在无脑放行,要么你早就一路关掉了确认。两种结局都等于把机器的钥匙交给了模型。

有没有办法从根上换个思路——不给 agent root,而是在操作系统层面精确地开几个口子,其余全堵死?Anthropic 的答案是一个独立于 Claude Code 的命令行工具:sandbox-runtime。它用 OS 原语给任意进程套上文件系统和网络限制,不需要容器。仓库地址:github.com/anthropics/sandbox-runtime。本文只做一件事:把它装到你机器上跑起来,并把每个平台真实的坑讲清楚。至于「要不要给 agent 上隔离」和「容器方案怎么选」,那是另一个问题,见文末延伸阅读。

先澄清时间线:这不是「本周新开源」

最近一波媒体热传,容易让人以为这是刚开源的新项目。时间线不是这样:

  • 仓库 created_at 为 2025-10-20,到今天已经一年多【官方,GitHub API 实抓】;
  • Anthropic 官方工程博客《Making Claude Code safer with sandboxing》发布于 2026 年 5 月【官方】;
  • 近期(2026-10 下旬)的媒体集中报道,是对一篇二手转述(MarkTechPost 10-24 文)的再次转述,「新开源」的说法不准确【二手】。

本文定位是装机实操,不追「新闻热度」。为什么要现在装?因为 Claude Code 的沙箱能力已经从「可选实验」走到了「默认推荐」的门口,而大量教程还停留在「逐条审批」的旧工作流——工具换代期的窗口,正是装机实操的价值所在。截至 2026-10-25 实测口径【官方,GitHub API】:6,615 stars、303 open issues、TypeScript、Apache-2.0 许可证、最新版本 v0.0.81、默认分支 main。README 顶部挂着状态声明:Beta Research Preview,"APIs and configuration formats may evolve"。也就是说这仍然是一个会改 API 的研究预览版,装之前要有心理预期:配置格式可能随版本演进,升级后回看一眼变更记录是必要动作。

srt 是什么:OS 原语,不是容器

README 的自我描述原文是:"A lightweight sandboxing tool for enforcing filesystem and network restrictions on arbitrary processes at the OS level, without requiring a container."【官方】拆开说三点:

第一,它管的是「任意进程」。 你可以用它包住 Claude Code 的 Bash 调用,也可以包住任何你不信任的命令行工具,不限于 agent 场景。

第二,它建立在 OS 原语上,不用 Docker、不用微虚拟机。 三平台各有一条实现路径【官方,README】:macOS 用 sandbox-exec(Seatbelt)加自定义 profile,无额外依赖;Linux 用 bubblewrap(bwrap)做容器化隔离;Windows 用 WFP(Windows Filtering Platform)做出站围栏。官方工程博客的表述是 "built on top of OS level primitives such as Linux bubblewrap and MacOS seatbelt"【官方】。社区对比表【二手,MarkTechPost】把同层对手列得更直白:Docker Sandboxes 走 microVM per sandbox,E2B 走 Firecracker——都是虚拟化路线,srt 是最轻的 OS 原语路线。

第三,它的理念是 secure-by-default。 README 原文:"processes start with minimal access, and you explicitly poke only the holes you need"【官方】——进程默认几乎没有权限,你需要什么就显式开什么。这句理念直接决定了下一节的默认策略表。

三平台安装实况

安装命令(README 逐字):

bash
npm install -g @anthropic-ai/sandbox-runtime

装完即可试跑【官方,README 示例】:

bash
srt "curl anthropic.com"    # 允许列表内,成功返回
srt "curl example.com"      # Connection blocked by network allowlist

两条命令,一条通一条堵,说明网络围栏已经生效。试跑的价值在于它把抽象的「沙箱」变成了肉眼可见的行为差异:允许列表内的域名照常返回,列表外的一行报错拒之门外。把这两条命令换成你工作流里真实的高频域名,就能快速验证配置是否符合预期。另外提醒一点:有二手来源【MarkTechPost】称需要 Node.js ≥22.12+,但这个要求未在 README 中得到确认,装机前请自行核对仓库 package.json。

macOS:零额外依赖,装完即用。这是三平台里最顺的路径。

Linux:需要 bubblewrap、socat、ripgrep 三件套(Ubuntu/Debian 用 apt-get install bubblewrap),bwrap 版本 ≥0.4.0;只有「非普通文件的 denyRead/凭证掩码」功能需要 ≥0.5.0,旧版本只给 warning 不拒绝【官方】。Ubuntu 24.04+ 有一个额外步骤:默认 AppArmor 限制了非特权用户命名空间,需要执行:

bash
sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0

bubblewrap 免 root 运行,走的正是 unprivileged user namespaces——所以在 Ubuntu 24.04 上不做这条 sysctl 调整,沙箱会直接起不来【官方】。

Windows:Alpha 状态。机制是创建专用 srt-sandbox 本地用户账户 + WFP 出站围栏(按 SID)+ write-restricted token + 显式 ACE,需一次性以管理员执行 npx @anthropic-ai/sandbox-runtime windows-install,之后无额外依赖【官方】。

Windows 的三层真相,一层都不能少

媒体笼统说「支持 Windows」,这里有误导,而且不止一层。完整真相分三层【官方,README 与 Claude Code 官方文档】:

第一层:srt CLI 本身在 Windows 是 Alpha。 WFP 方案能用,但成熟度远低于 macOS/Linux 两条线。

第二层:Schannel 是硬限制,无解。 README 原文:"What does not work inside the sandbox: Schannel." 具体来说,System32 自带的 curl、PowerShell 的 Invoke-WebRequest/Invoke-RestMethod、.NET HttpClient(连带 dotnet restore/NuGet)、winget、http.sslBackend=schannel 的 git、Windows 上的 cargo——这些依赖 Windows Schannel TLS 栈的工具,在沙箱内全部无法完成 HTTPS 握手。README 原话:"There is no workaround for these inside the sandbox: run such a tool outside it." 自带 TLS 栈的工具(Node、Python、Go)不受影响。

第三层:Claude Code 的沙箱在原生 Windows 上完全不运行。 Claude Code 官方文档原文:"On native Windows, Claude Code runs commands unsandboxed. To use the sandbox on a Windows machine, run Claude Code inside a WSL2 distribution." 也就是说在原生 Windows 上跑 Claude Code,命令是无沙箱执行的;要用沙箱,必须把 Claude Code 放进 WSL2 发行版,WSL1 不支持("Sandboxing requires WSL2")。WSL2 里走的是和 Linux 相同的 bubblewrap 路线。

三层合起来读:Windows 用户想真正用上这套沙箱,路径是「WSL2 + bubblewrap」,而不是「原生 Windows 装个 CLI 就完事」。第二层的 Schannel 限制在 WSL2 场景下自然绕开,但如果你在原生 Windows 上用 srt CLI 包别的进程,Schannel 问题躲不掉。

默认策略与 ~/.srt-settings.json

srt 的默认策略可以压缩成一张三行表【官方,README】:

维度模式默认值
网络allow-only全部禁止,需显式放行域名;"An empty allowedDomains list means no network access"
写入allow-only全部禁止;空数组 = 无写权限;denyWrite 优先于 allowWrite
读取deny-then-allow全部放行;allowRead 优先于 denyRead

注意三个方向默认值不对称:网络和写是「默认全禁」,读是「默认全放」。这个不对称是有逻辑的——可执行文件、系统库、框架源码都靠读,默认全禁会让任何进程都跑不起来;而网络出口和文件写入是 agent 闯祸的两大主通道,所以默认焊死。代价是:凭据文件的隔离要靠你显式 denyRead,而不是它自动帮你藏好。

配置文件默认在 ~/.srt-settings.json(可用 --settings 指定别的路径)。README 给的示例逐字如下:

json
{
  "network": {
    "allowedDomains": ["github.com", "*.github.com"],
    "deniedDomains": ["malicious.com"],
    "allowUnixSockets": ["/var/run/docker.sock"],
    "allowLocalBinding": false
  },
  "filesystem": {
    "denyRead": ["~/.ssh"],
    "allowWrite": [".", "src/", "/tmp"],
    "denyWrite": [".env", "config/production.json"]
  }
}

两个细节值得划重点。其一,配置文件存在但无效时会报错退出,而不是静默回退到默认策略——这是新版本行为,背后有一次安全修复(见坑清单第 3 条)。其二,allowUnixSockets 里放行 docker.sock 这种条目要格外小心,有第三方深度分析【二手】转述 README 的说法:这"effectively access to the host"——等于把宿主机交出去,Docker 的 socket 不是普通网络端口。

接入 Claude Code:/sandbox 与设置项

Claude Code 从 0.x 起原生集成了这套沙箱能力,官方文档(code.claude.com/docs/en/sandboxing)给出的启用方式有两种【官方】:会话内运行 /sandbox 命令,或在设置文件(如 ~/.claude/settings.json)里把 sandbox.enabled 设为 true。命令行模式示例(文档原文):

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

关键设置项(文档原文列举):

  • sandbox.autoAllowBashIfSandboxed:命令在沙箱内运行时自动放行 Bash——这正是省掉 84% 弹窗的开关位;
  • sandbox.allowUnsandboxedCommands:是否允许沙箱外命令,安全起见设为 false;
  • sandbox.failIfUnavailable:沙箱不可用时直接报错而不是静默回退到无沙箱运行,建议开启;
  • sandbox.excludedCommands:排除在沙箱外的命令名单;
  • sandbox.filesystem.* 与 sandbox.network.*:文件系统与网络策略,语义与 srt 裸配置一致;
  • sandbox.credentials.files / sandbox.credentials.envVars:凭证掩码。

环境变量侧:HTTP_PROXY/HTTPS_PROXY/ALL_PROXY 用于注入代理出口;CLAUDE_CODE_SUBPROCESS_ENV_SCRUB 用于强制保留文件系统隔离;CLAUDE_CODE_TMPDIR 控制临时目录。Linux/WSL2 下依赖照装:sudo apt-get install bubblewrap socat(Fedora 用 dnf)。

一个必须分清的默认值差异:srt 裸用默认「禁止一切写入」,但 Claude Code 集成层的默认访问表是【官方,文档】:写入 = 工作目录 + 每用户临时目录;读取 = 包括 ~/.ssh、~/.aws/credentials 在内的大部分机器;网络 = "No direct route out",代理允许列表初始为空。也就是说集成层替你放行了工作目录的写入(否则 agent 没法干活),读的默认面比 srt 裸默认宽得多。对凭据有洁癖的,用 sandbox.filesystem.denyRead 显式补上。

关于 84% 这个数字:官方工程博客原话是 "In our internal usage, we've found that sandboxing safely reduces permission prompts by 84%."【官方】但口径要说清——这是 Anthropic 内部使用数据、自报,没有外部评测,也没有公开方法论细节【官方自报】;MarkTechPost【二手】也确认它是 "self-reported number, not an external benchmark"。它说明的是「方向有效」,不是「你的弹窗一定少八成」。实际节省量取决于你的允许列表配置得多宽:列表越宽弹窗越少,但约束也越松,安全与顺手的平衡点要自己调。背景数字:其遥测显示用户批准了约 93% 的权限提示【官方】,批准疲劳确实普遍存在,这也是沙箱默认自动放行的产品逻辑起点。

坑清单:来自 issues 的实锤

以下均为主仓库 issues 一手信息【官方,2026-10-25 实抓】,按热度排:

  1. #139「dotfiles 泄漏」(2026-02-18 开,34 条评论,全仓最热):运行命令时与被 SIGKILL 时会泄漏 dotfiles 和目录。相关 #85 已关闭、#171(Linux 上 allowRead 目录无法 mkdir)。给 ~/.ssh 之类目录上锁的,盯紧这个 issue 的修复进度。
  2. #160「可读其他进程的 env/args」(2026-03-02 开):沙箱开启状态下仍可读到其他进程的环境变量和参数——凭据如果放在环境变量里,暴露面比你想的大。
  3. #122「配置回退静默禁用读限制」:旧版本在配置无效时静默回退、连带禁掉文件系统读限制,已由 PR #124 修复;现在 README 写的「无效配置报错退出」就是这个修复的结果。老版本务必升级。
  4. Ubuntu 24.04+ 的 AppArmor 限制:不开 unprivileged userns,bubblewrap 起不来,解法见前文 sysctl 命令;容器内无 CAP_SYS_ADMIN 时 seccomp 会报 EPERM(#417)。
  5. 平台网络机制不一致:Linux 走 Unix socket bind-mount、macOS 的 Seatbelt 只放行一个 localhost 端口、Windows 走 WFP fence【官方】。媒体笼统说「所有流量强制走宿主代理」掩盖了实现差异。
  6. 「强制走代理」不完全成立:不读代理环境变量的工具(ssh、多数数据库驱动)不是被强制代理,而是完全连不上;QUIC/UDP/ICMP(含 ping)出不去。
  7. 文档列名的不兼容工具:watchman、docker;macOS 上 git over SSH 会失败、Go 系 CLI(gh/gcloud/terraform)TLS 可能失败。
  8. 独立技术分析的两条提醒【二手,ai.thesatyajit.com,作者自跑 Linux 端到端】:enableWeakerNestedSandbox 会 "considerably weakens security";另外 srt 若装在项目目录内,可能被沙箱内进程改写——建议全局安装。

常见问题

Q1:装好后需要 root 或管理员权限吗? A1:日常运行不需要。Linux 上 bubblewrap 走非特权用户命名空间,免 root;唯一的例外是 Ubuntu 24.04+ 需要一条一次性的 sysctl 调整(需 sudo)。Windows 上 windows-install 创建 srt-sandbox 账户和 WFP 围栏需要一次管理员权限,之后不再需要。

Q2:我已经用 Docker 跑 agent 了,还需要 srt 吗? A2:两件事。容器给你的是共享内核的命名空间隔离,防「把环境弄脏」够用,防「主动越权」偏弱;srt 是进程级的细粒度权限控制,两者可以叠用。但注意 allowUnixSockets 放行 docker.sock 等于交出宿主机【二手转述官方说法】,两者混用时配置要格外小心。容器与 OS 原语两条路线的完整对比,见延伸阅读的五强横评。

Q3:Windows 上到底能不能用? A3:分三层回答。srt CLI 本身:Alpha 可用,但 Schannel 系工具(System32 curl、IWR、NuGet、winget、schannel 后端的 git)在沙箱内无法 HTTPS 握手且无解。Claude Code 沙箱:原生 Windows 上完全不运行(unsandboxed 回退),必须进 WSL2,WSL1 不支持。所以 Windows 用户的正确路径是 WSL2 + bubblewrap。

Q4:84% 减弹窗这个数字可信吗? A4:它是 Anthropic 官方工程博客的原话,但属于内部使用数据、自报口径,无外部评测、无方法论细节。可以理解为官方对「方向有效」的背书,不要当成对你工作负载的预测。背景数字:其遥测显示用户批准了约 93% 的权限提示,说明弹窗疲劳确实普遍。

Q5:为什么 srt 裸用默认禁一切写入,接进 Claude Code 后又能写工作目录? A5:两层默认值不同。srt 作为独立工具按 secure-by-default 全禁;Claude Code 集成层为了让 agent 能干活,默认放行工作目录和每用户临时目录的写入,读取默认面也宽得多(含 ~/.ssh)。有更高安全要求时,用 sandbox.filesystem.denyRead/denyWrite 和 sandbox.credentials.files 显式收紧,并打开 sandbox.failIfUnavailable。

延伸阅读

本文基于公开资料整理(仓库数据与 issues 状态为 2026-10-25 实测口径),安装命令与配置均引自官方 README 与官方文档,二手来源已逐处标注,不构成安全合规建议。

本文由 AI 辅助生成,经人工审核编辑。最后更新:2026-10-26

常见问题

装好后需要 root 或管理员权限吗?
A1:日常运行不需要。Linux 上 bubblewrap 走非特权用户命名空间,免 root;唯一的例外是 Ubuntu 24.04+ 需要一条一次性的 sysctl 调整(需 sudo)。Windows 上 `windows-install` 创建 srt-sandbox 账户和 WFP 围栏需要一次管理员权限,之后不再需要。
我已经用 Docker 跑 agent 了,还需要 srt 吗?
A2:两件事。容器给你的是共享内核的命名空间隔离,防「把环境弄脏」够用,防「主动越权」偏弱;srt 是进程级的细粒度权限控制,两者可以叠用。但注意 `allowUnixSockets` 放行 docker.sock 等于交出宿主机【二手转述官方说法】,两者混用时配置要格外小心。容器与 OS 原语两条路线的完整对比,见延伸阅读的五强横评。
Windows 上到底能不能用?
A3:分三层回答。srt CLI 本身:Alpha 可用,但 Schannel 系工具(System32 curl、IWR、NuGet、winget、schannel 后端的 git)在沙箱内无法 HTTPS 握手且无解。Claude Code 沙箱:原生 Windows 上完全不运行(unsandboxed 回退),必须进 WSL2,WSL1 不支持。所以 Windows 用户的正确路径是 WSL2 + bubblewrap。
84% 减弹窗这个数字可信吗?
A4:它是 Anthropic 官方工程博客的原话,但属于内部使用数据、自报口径,无外部评测、无方法论细节。可以理解为官方对「方向有效」的背书,不要当成对你工作负载的预测。背景数字:其遥测显示用户批准了约 93% 的权限提示,说明弹窗疲劳确实普遍。
为什么 srt 裸用默认禁一切写入,接进 Claude Code 后又能写工作目录?
A5:两层默认值不同。srt 作为独立工具按 secure-by-default 全禁;Claude Code 集成层为了让 agent 能干活,默认放行工作目录和每用户临时目录的写入,读取默认面也宽得多(含 ~/.ssh)。有更高安全要求时,用 `sandbox.filesystem.denyRead/denyWrite` 和 `sandbox.credentials.files` 显式收紧,并打开 `sandbox.failIfUnavailable`。

相关文章

实战 SOP

不会写代码也能做游戏:49 个 AI 员工的工作室

用 Claude Code Game Studios(github.com/Donchitos/Claude-Code-Game-Studios,MIT,约 33,837 星)把单个 Claude Code 会话变成 49 个 AI 员工的游戏工作室:三层架构总监/主管/专家、72 个技能命令、12 个自动钩子拦截硬编码与误推送,协作协议保证每个决策由你拍板;附五分钟安装三步、Demo 精简流程、第三方 API 跑法与"适合谁/不适合谁"的自检清单。

2026年11月3日9 分钟阅读
实战 SOP

录音转文字还在按分钟付费?本地 59 秒转完

本地语音转文字五步实战(faster-whisper 主引擎,仓库 github.com/SYSTRAN/faster-whisper):按显存选型(24GB 卡 large-v3+float16+beam 5;8GB 卡 int8_float16 不够降 medium;纯 CPU small/base+int8)→ 安装(GPU 需 CUDA 12 cuBLAS + cuDNN 9,旧组合降级 ctranslate2 3.24.0/4.4.0)→ 最小转写脚本 → 提速省显存三招(精度 fp16 转 int8 省约 1.6GB、批量 batch 8 多花约 1.5GB 提速约 3.7 倍、beam 第三位再动)→ 进阶(Silero VAD、词级时间戳、自拼 SRT、WhisperX 说话人分离)。基准口径全文统一注明:large-v2、beam_size=5、13 分钟音频、RTX 3070 Ti 8GB——原版 2 分 23 秒/4708MB,faster-whisper int8 59 秒/2926MB,批量化 16 秒/4500MB;纯 CPU 档如实写 whisper.cpp fp32(2m05s/1049MB)比 faster-whisper fp32 更快更省,不写全面碾压。陷阱清单含 GPU 忌纯 int8(CTranslate2 文档:需计算能力 7.0/6.1 以上,老卡静默回退 float32)。结尾单段带过 NVIDIA Nemotron 3.5 Transcribe 新引擎选项,与开源列那篇分工不重复跑分。

2026年10月29日9 分钟阅读
实战 SOP

3B 小模型日吞 20 万页文档:DeepSeek-OCR 部署实录

DeepSeek-OCR 本地部署实录:视觉侧把整页压成几十到几百个 vision token,解码侧 3B MoE 激活仅约 570M,官方论文口径单张 A100-40G 日产 20 万页以上训练数据,24GB 消费卡即可入场。两代官方仓库路线不同:环境与 Transformers 推理走二代(Apache-2.0),上游 vLLM 与 API 服务化走一代(MIT)成熟生态;cuda11.8+torch2.6.0+flash-attn 2.7.3 环境逐字实录,五种分辨率模式 token 账本(64 到 400+),NGram 防复读处理器与 128821/128822 表格白名单,附显存社区口径警示(官方未公布)与 10 条排障清单。

2026年10月25日9 分钟阅读