Claude Code 的沙箱用于限制 Bash 命令对文件系统和网络的访问，但不同操作系统、容器和 CI Runner 不一定都具备可用的沙箱条件。如果配置要求启用沙箱，底层能力却无法启动，最危险的情况是任务在没有隔离的环境中继续运行，而维护者只看到作业"成功"。`sandbox.failIfUnavailable` 用于把这种隐性降级改成明确失败：沙箱不可用时直接退出，不允许无保护执行。它适合安全要求严格的 CI 和自动化任务，但上线前必须验证运行环境确实支持沙箱，否则会造成大面积构建中断。
一、什么叫沙箱不可用
沙箱不可用不等于某条命令被沙箱拒绝。前者是隔离机制本身无法创建，例如操作系统能力缺失、容器权限不足、依赖工具不可用或配置不受当前平台支持；后者是沙箱已正常启动，并按规则阻止了越界访问。
两类错误处理方向不同。机制无法启动要修复 Runner 和平台能力，命令被拒绝则应检查允许路径、网络域名和任务设计。错误日志中应保留发生阶段与错误码，避免只写一句"沙箱失败"。
二、failIfUnavailable 的作用
在沙箱配置中启用 `failIfUnavailable` 后，只要 Claude Code 无法建立所要求的隔离，就以错误结束，而不是退回未沙箱化执行。这个设置并不会扩大沙箱能力，也不会自动修复环境，只是让安全前提无法满足时采用拒绝策略。
对部署、依赖安装、处理外部代码和接触凭据的自动化，这种失败方式更容易审计。作业变红虽然影响进度，却比在未知权限下继续运行更可控。安全边界应该由明确状态表达，不能靠操作者猜测。
三、启用前先做兼容性测试
准备与正式 CI 相同的 Runner 镜像、用户权限、挂载方式和网络策略，运行一个最小 Bash 任务。确认沙箱能创建，允许目录可以读取，需要的输出目录可以写入，受限目录和禁止网络确实被阻止。测试成功路径和拒绝路径都不可缺少。
再人为制造沙箱不可用条件，在隔离测试环境中确认作业直接失败，且错误清楚显示原因。若仍继续执行，说明配置层级、版本或启动方式没有生效。不要在生产部署任务上第一次验证。
四、CI 为什么容易遇到启动失败
容器本身已经位于受限环境，可能缺少创建第二层隔离需要的系统调用或命名空间。托管 Runner 的安全策略也可能阻止某些机制。自建 Runner 则可能因为内核、依赖版本、挂载选项或安全模块配置不同而表现不一致。
另外，交互开发机能用不代表无头服务账号也能用。CI 使用的用户、HOME、临时目录和工作目录权限都不同。应在真正的作业身份下检查，而不是用管理员终端得到成功后直接上线。
五、配置放在哪里更合适
安全要求属于团队流程时，应放在受审查的项目或组织配置中，并让流水线日志显示沙箱要求已启用。个人本地实验可以使用用户设置，但不能依赖每位开发者自行开启。配置变更要与最低客户端版本一起发布，避免旧版本忽略未知字段。
如果大家想体验一线 AI 编程模型 codex 和 claude，用它们在受控环境中完成代码修改、测试和审查，可以参考以下教程文档进行接入配置，接入配置好后即可使用。文档教程：https://my.feishu.cn/wiki/NIgLwuuj1ibzJIkLGM0cgVNinzg
密钥、代理密码和平台凭据仍应由 Secret 系统注入，不能因为有沙箱就写入配置文件。沙箱降低进程访问范围，不会把明文凭据变安全。
六、启用后流水线全部失败怎么办
先停止高风险任务，不要立即关闭 failIfUnavailable 恢复通行。挑选一个最小作业，收集操作系统、Claude Code 版本、运行用户、容器配置和完整的非敏感错误。检查沙箱依赖、内核能力、临时目录与挂载权限。
若平台确实不支持，选择支持的 Runner 或增加外部隔离，例如一次性虚拟机和只读挂载。确需临时例外时，应限制任务范围、移除敏感凭据、关闭网络和写权限，并经过明确审批。例外要有截止时间，不能悄悄变成永久配置。
七、它不能替代哪些控制
沙箱不是完整的安全体系。任务仍需要最小权限账号、工具 allow/deny 规则、审批流程、Secret 管理、依赖校验和审计日志。允许写入的目录内仍可能发生破坏性修改，允许访问的网络目标仍可能接收数据。
提示注入也不会因为沙箱存在而消失。处理不可信仓库时，应限制可读文件和外部网络，不让代理接触部署凭据。沙箱负责强制边界，项目规则与人工审查负责业务判断，两者互相补充。
八、如何验证没有静默降级
每个 Runner 镜像发布时运行沙箱自检，记录成功创建、允许访问、拒绝访问和不可用失败四项结果。正式作业中保留版本、配置状态和退出码，但不打印完整环境。升级 Claude Code、容器基础镜像或宿主机后重新测试。
还可以设计一个只在无沙箱时才会成功的无害探针，例如读取专门准备的禁止路径。探针在正常作业中必须失败；若意外成功，应立即阻断流水线并调查边界变化。探针不能触碰真实敏感文件。
九、团队落地原则
先把"必须有沙箱"的任务分级，例如处理外部代码、自动修改仓库和部署前检查。为这些任务统一开启拒绝降级，并提供经过验证的 Runner。普通交互环境可根据风险采用不同策略，但不能让高风险流水线因兼容性问题自动放宽。
`sandbox.failIfUnavailable` 的核心价值是让安全前提变得可观察：能隔离就运行，不能隔离就停止。它不会让不兼容环境凭空获得沙箱，却能防止作业在维护者不知情时失去保护。配合兼容性测试、最小权限和明确例外流程，CI 才能既保持可用，也守住真正的执行边界。