Claude Code 本地 Agent 的安全栈：沙盒、权限、规则与分类器

编码 Agent 一旦拥有 shell，就能改文件、安装依赖、调用网络接口。此时风险不仅是“回答错”，还包括误删、提示注入和凭证泄露。安全设计需要知道：哪些操作受程序检查，哪些受操作系统限制，哪些还在边界外。

下面按 2026 年 10 月的公开文档说明 Claude Code。功能、默认值和平台实现会变化，应以安装版本及生效设置为准，不能把某条配置当作全平台保证。

三种约束不是同一个东西

权限规则由程序检查，不能说它们只靠模型自觉。 但 Bash 命令规则与 OS 级文件边界的覆盖也不同，一条复杂 shell 命令需要考虑子进程、重定向与命令替换。

图 1 · 这是约束覆盖关系，不是每条命令必然经过相同顺序的四道流水线。

沙盒包裹什么，默认允许什么

Claude Code 的内置沙盒主要约束 shell 命令及其子进程。内置 Read/Edit/Web 工具走各自权限规则；hooks、MCP 和其他辅助进程可能在 Bash 沙盒之外运行。官方沙盒文档^[1]

当前文档描述的默认读范围较广，包含机器上的凭证文件；写范围主要是工作目录和允许路径，受保护路径另有约束。网络通过代理检查允许域，环境变量可能继承秘密。限制写入不等于防止秘密被读取或外传。

macOS 使用 Seatbelt，Linux/WSL2 使用 bubblewrap 等机制；原生 Windows 的支持范围不同。网络工具是否可用取决于代理、协议和平台，不能笼统声称所有 SSH、数据库客户端都能通或都不能通。

文件 denyRead 不自动限制内置 Read 工具，网络域策略也不自动限制 WebFetch。需要把整个 Agent 与插件进程一起隔离时，应评估容器、虚拟机或外层运行边界。

权限模式和沙盒模式分别看

default、acceptEdits、plan、auto 和 bypassPermissions 改变权限处置；沙盒是否启用及是否自动允许边界内命令，是另一组配置。auto 的分类器也不等于 OS 沙盒，它对操作意图的判断可能误报或漏报。权限模式文档^[2]

例如对推送设置内容级 ask 规则，可让本地验证自动进行而推送仍进入审批。具体匹配语法和优先级以权限文档为准，不能把模型获得的自然语言授权等同于永久修改机器策略。

沙盒失败后的非沙盒重试、excludedCommands 和放宽隔离的开关要单独检查。把解释器、容器管理命令排除，可能间接允许执行新写的脚本；例外应按实际可获得能力评估，而非只看命令名字。

受保护路径：防止下一轮扩权

Agent 配置、shell 启动文件、Git hooks 和配置会影响未来执行。它们需要专门保护；不同工具、权限模式和版本的保护方式不同，不能统一说“所有路径永远不可写”。

仓库中的规则、依赖 README、网页和工具报告可能带恶意指令。它们是需要阅读的数据，不能成为修改权限、导出密钥或联系外部服务的授权来源。输出扫描有帮助，但不是提示注入已被彻底解决的证明。

凭证掩码：能使用不意味着能看见

支持的凭证 mask 用每会话哨兵占位符替代真实值；受控代理在指定目标上替换回真值，以便认证。目标限定、TLS 处理和配置来源共同构成这个机制的信任边界。

图 2 · 仅说明支持配置下的机制；不能推导出所有文件、平台和认证协议均可掩码。

当前文档明确：macOS 凭证文件 mask 会退化为拒绝读取，Linux/WSL2 才有相应哨兵文件行为。环境变量与文件是不同路径；提取模式没有匹配到秘密时，也要检查是否会跳过掩码。AWS 重签有支持范围和版本条件，不能当作任意签名请求都可用。凭证配置细节^[1]

拒绝读取更简单，但会影响需要认证的工具；掩码增加代理和配置复杂度。无论选择哪种，都尽量使用短期、最小范围的凭证；目标允许使用某个 token 也不代表该 token 在远端只有最小权限。

与 Codex 对照：概念相似，配置独立

Codex 同样将沙盒范围与审批策略区分：前者限制操作可触达哪里，后者控制哪些操作需要审批。具体网络和路径行为取决于平台、宿主及配置，不能从 Claude Code 推断 Codex 的默认值。Codex 官方说明^[5]

缓存网页搜索降低部分实时来源风险，但缓存内容仍可携带恶意指令；“缓存索引”不是信任认证。对两种工具都应检查真实生效策略，而不是只记住模式名称。

用无秘密探针验证边界

使用临时目录、假凭证和可控测试目标验证：工作区内写入成功、禁止路径写入失败；shell 读取与内置 Read 分别验证；允许域、禁止域和直连尝试分别验证；掩码认证与目标不匹配分别验证。不要通过读取真实密钥来证明保护有效。

同样测试沙盒不可用、被排除命令、插件与 hook 的执行位置，以及符号链接是否改变访问范围。记录客户端版本、平台、设置来源和期望结果，升级后重复检查。失败时收紧边界或修配置，不能把每次失败都自动扩大允许范围。

落地检查

1. 区分提示、工具规则和 OS 边界，查看生效配置而非仅看仓库文件。
2. 文件、环境变量和网络分别控制；写保护不代替读保护。
3. 单独管理 hooks、MCP、LSP 等边界外组件。
4. 谨慎评估排除命令与非沙盒重试，CI 有明确失败策略。
5. 使用假数据探针验证平台差异，升级后回归。

参考资料