2026 Claude Code 配置会被 Agent 改写吗?SBPL 防篡改

不要把 Agent 可写的项目级配置当作不可突破的安全边界:个人受监督任务可用 denyWrite 与失败关闭收紧权限,团队或无人值守任务应把核心策略移到 managed settings,高风险场景再用 SBPL 包住整个 Claude Code 进程或迁入独立 Mac 环境。这个判断就是 Claude Code 配置防篡改的起点。
这篇文章适合三类人:把 .claude/settings.json 放进代码仓库、同时允许 Claude Code 自动编辑文件的开发者;需要确保团队安全策略不能被项目配置削弱的 DevSecOps 工程师;以及准备在远程 Mac 上长期运行终端 Agent 的研发平台负责人。
⚠️ 本文按 2026 年 9 月 15 日 的官方文档和当前 Xcode man page 核对。Claude Code、Sandbox Runtime 或 macOS 更新沙箱机制后,字段名称和默认行为应重新复核。
项目配置能协作,但不能负责自我保护
典型失败模型不是“Agent 突然拥有了管理员权限”,而是更普通的路径关系:
项目目录/
├── src/
├── .claude/
│ ├── settings.json
│ ├── hooks/
│ └── skills/
└── package.json
如果 Claude Code 能通过 Edit、Write 或 Bash 修改项目目录,而权限规则又保存在同一个 .claude 目录,那么定义权限的文件和执行任务的 Agent 就处在同一可写边界。此时,配置优先级高,只代表读取配置时谁胜出,不代表文件本身不能被写入。
Claude Code 的工具权限是分开的:文件读取、文件修改和 Bash 命令分别进入权限流程;文件修改并不是 Bash 的自动别名。官方权限文档还明确,规则按 deny → ask → allow 评估,先匹配的规则生效。(code.claude.com)
因此,策略文件至少要检查以下路径:
.claude/settings.json与.claude/settings.local.json;.claude/hooks/、.claude/skills/及会影响后续会话的命令文件;- 项目父目录中可能被自动发现的配置;
- 通过
Bash、脚本或符号链接间接写入配置的路径。
项目级设置仍然有价值。它适合保存团队共享的工作流、Hooks、MCP 配置和业务约束,也方便代码审查。但它不应该独立承担“禁止关闭沙箱”“沙箱失败必须停止”“禁止读取密钥”这类安全底线。
第一张表:不同配置层级,防篡改能力并不相同
| 配置层级 | 典型位置 | 适合保存什么 | 能否作为最终安全边界 |
|---|---|---|---|
| User | ~/.claude/settings.json |
个人偏好、跨项目工具配置 | ❌ 不适合团队强制策略 |
| Project | .claude/settings.json |
仓库共享规则、Hooks、团队工作流 | ⚠️ 可审查,但可能处于 Agent 可写目录 |
| Local | .claude/settings.local.json |
本机实验、个人覆盖项 | ❌ 不适合无人值守任务 |
| Managed | 系统级托管文件、MDM 或服务端策略 | 强制权限、沙箱和合规规则 | ✅ 适合核心安全底线 |
| SBPL | 启动 Claude Code 时加载的 macOS Profile | 进程级文件系统限制 | ⚠️ 能包住进程,但工具已弃用 |
官方配置层级中,managed 位于最高优先级,项目和本地设置不能覆盖它;macOS 文件型托管配置通常位于 /Library/Application Support/ClaudeCode/managed-settings.json。(code.claude.com)
换句话说,业务配置可以留在仓库,安全策略不应全部留在仓库。最小分界线是:
仓库内:
- 项目级工作流
- 可审查的权限申请
- 团队共享的 Hooks
受保护位置:
- 禁止绕过沙箱
- 沙箱不可用时退出
- 禁止写入策略目录
- 禁止读取密钥和系统配置
配置合并不是简单覆盖,数组可能带来隐性扩权
很多排查只打开一个 JSON 文件,看见了 allowWrite,就以为知道最终边界。这种判断不可靠。
当前配置优先级从高到低包括 managed、命令行参数、local、project 和 user。更需要注意的是,数组型设置可能跨层级合并,而不是由高优先级文件完全替换低优先级内容。官方文档特别说明,filesystem.allowWrite、权限规则等数组会合并并去重。(code.claude.com)
例如:
// managed settings
{
"sandbox": {
"filesystem": {
"allowWrite": ["/opt/company-build"]
}
}
}
// project settings
{
"sandbox": {
"filesystem": {
"allowWrite": ["."]
}
}
}
最终结果可能同时包含项目目录和托管目录。这里的风险不是项目设置覆盖托管设置,而是项目设置继续增加可写范围。
排查时按以下顺序操作:
- 在 Claude Code 中运行
/status,确认当前加载了哪些配置来源。 - 运行
/permissions,查看权限规则实际来自哪个文件。 - 运行
/doctor,检查无效字段、格式错误和配置来源问题。 - 搜索所有层级中的
allowWrite、denyWrite、allowUnsandboxedCommands和failIfUnavailable。 - 检查环境变量和命令行参数,因为它们也可能影响当前会话。
/status、/permissions 和 /doctor 的作用不同,不能只运行其中一个。官方调试文档也提醒,某个设置没有生效,常见原因是被其他作用域或环境变量覆盖。(code.claude.com)
沙箱失败时继续运行,防篡改假设会失效
Claude Code 的原生沙箱主要约束 Bash 及其子进程。它不是自动包住整个 Claude Code 主进程的 macOS Sandbox,也不能因为 Bash 被限制,就推断 Edit、Write、Hooks 和其他进程行为都拥有同一层隔离。官方沙箱文档明确把沙箱描述为命令执行边界,并说明某些工具会回退到普通权限流程。(code.claude.com)
至少要区分三种情况:
| 失败类型 | 实际行为 | 对策略文件的影响 | 应对方式 |
|---|---|---|---|
| 初始化失败 | 依赖缺失或平台不支持 | 可能继续无沙箱执行 | 设置 sandbox.failIfUnavailable 为 true |
| 命令不兼容 | 沙箱拒绝网络、工具或系统调用 | 进入普通权限确认流程 | 明确允许的例外,不要默认放开 |
| 显式非沙箱执行 | 使用 dangerouslyDisableSandbox |
命令可能离开沙箱 | 设置 allowUnsandboxedCommands 为 false |
官方文档说明,沙箱默认不可用时会警告并继续执行;将 sandbox.failIfUnavailable 设为 true 后,沙箱启动失败应成为硬失败。文档还说明,allowUnsandboxedCommands: false 会关闭 dangerouslyDisableSandbox 逃生口。(code.claude.com)
一个更稳妥的托管策略片段可以从下面开始:
{
"sandbox": {
"enabled": true,
"failIfUnavailable": true,
"allowUnsandboxedCommands": false,
"filesystem": {
"denyWrite": [
".claude",
".claude/**"
]
}
}
}
这段配置不应直接复制到项目设置中作为最终防线。它应放在受保护的 managed settings,并根据当前官方 schema 核验字段路径。不同版本可能使用 sandbox 或相关嵌套结构,不能只依据旧文章或单个示例判断。
经验判断:如果任务可以因为“命令不兼容”而自动离开沙箱,那么“策略文件没有被改写”并不等于“任务始终受隔离”。防篡改验收必须同时测试初始化失败、普通权限回退和显式逃生口。
SBPL 与 Bash Sandbox 不是同一层
macOS Sandbox、Seatbelt、sandbox-exec、手写 SBPL 和 Claude Code 官方 Bash Sandbox 经常被混在一起,实际层级不同:
- Claude Code 工具权限:决定
Edit、Write、Bash是否需要批准。 - 官方 Bash Sandbox:主要限制 Bash 命令及其子进程的文件和网络操作。
- Sandbox Runtime:为任意进程生成并加载平台级限制;macOS 实现使用
sandbox-exec和自定义 Profile。 - Seatbelt / SBPL:macOS 内核沙箱规则和 Profile 语言。
- sandbox-exec:从进程外启动目标命令,并加载 SBPL 文件。
Sandbox Runtime 的公开说明显示,macOS 使用 sandbox-exec,写入规则采用默认拒绝、再通过 allowWrite 放行的思路;它可以用于 Agent、MCP Server、Bash 命令和其他任意进程。(github.com)
第二步:先用虚构目录验证 SBPL
下面的 Profile 只用于验证临时目录和虚构策略文件。它不测试真实密钥、系统配置或生产仓库。
(version 1)
(deny default)
(allow process-exec
(literal "/bin/sh")
(literal "/bin/mkdir")
(literal "/usr/bin/touch")
(literal "/usr/bin/ls"))
(allow file-read*
(subpath "/tmp/claude-sbpl-demo"))
(allow file-write*
(subpath "/tmp/claude-sbpl-demo/work"))
(deny file-write*
(subpath "/tmp/claude-sbpl-demo/policy"))
准备测试目录:
mkdir -p /tmp/claude-sbpl-demo/work
mkdir -p /tmp/claude-sbpl-demo/policy
touch /tmp/claude-sbpl-demo/policy/fake-settings.json
保存为 ~/claude-demo.sb 后,先测试普通命令:
sandbox-exec -f "$HOME/claude-demo.sb" \
/bin/sh -c 'touch /tmp/claude-sbpl-demo/work/ok.txt && touch /tmp/claude-sbpl-demo/policy/blocked.txt'
预期结果是 work/ok.txt 可以创建,而 policy/blocked.txt 被拒绝。Profile 中没有放行 Claude Code 所需的完整网络、动态库、终端和用户目录规则,因此不要直接把这个示例当作生产启动文件。
如果需要做可撤销的启动入口,可以先用 Shell 函数,而不是覆盖原始命令:
claude_sbpl_demo() {
sandbox-exec -f "$HOME/claude-demo.sb" claude "$@"
}
完成验证后,删除函数或关闭当前 Shell 即可撤销。真正包住整个 Claude Code 进程时,应从只读策略文件开始,逐项加入必要的动态库、终端、网络和临时目录权限,每增加一项都记录原因。
SANDBOX-EXEC 的当前 man page 仍将该命令标记为 DEPRECATED,同时保留 -f 加载 Profile 文件的调用形式。公开的 Sandbox Runtime 仍在 macOS 上调用它,这说明当前系统通常还能运行,但不能把“现在可调用”写成“未来长期受支持”。(keith.github.io)
全进程保护适合过渡,高风险任务应升级环境
手写 SBPL 的价值在于:它从 Claude Code 进程外部限制主进程及其子进程。这样,策略文件不只受到 Bash Sandbox 约束,整个启动链也能被限制在指定目录范围内。
但它仍有边界:
- Profile 过严,Claude Code 可能无法启动或无法访问必要的运行时文件;
- Profile 过宽,实际写权限可能超出原本的策略文件范围;
sandbox-exec已弃用,后续 macOS 版本的兼容性不能假设;- 启动包装器本身、Profile 文件和环境变量也必须受保护;
- 沙箱不等于密钥管理,进程已经获得的文件描述符不一定会被事后规则收回。macOS 沙箱概览文档明确指出,新进程会继承父进程沙箱,但已经打开的写入文件描述符可能继续可用。(keith.github.io)
因此,判断标准应从“能不能写某个文件”升级为“策略文件落在哪里、谁能改、失败后会怎样、恢复是否独占”。
| 任务类型 | 推荐边界 | 策略文件落点 | 是否需要独立 Mac |
|---|---|---|---|
| 受监督个人开发 | 项目设置 + denyWrite + 手动确认 |
仓库规则与用户规则分开 | 通常不需要 |
| 团队共享任务 | managed settings + 失败关闭 | 系统级或服务端托管 | 视共享权限而定 |
| 无人值守 Agent | managed settings + 禁止逃生口 + 全进程保护 | Agent 无法写入的受保护位置 | 建议评估 |
| 高风险自动化 | 独立环境、最小目录、可恢复快照 | 独占 Mac 或虚拟化环境 | ✅ 优先考虑 |
如果团队需要在远程 Mac 上长期运行 Agent,先整理三项信息:策略文件位置、任务是否无人值守、允许写入的目录。之后再对照 ProxyMac 的帮助文档 了解远程 Mac 的交付与使用边界,并结合 美国区域方案说明 核对适合的环境路径。这里的重点不是购买更高规格,而是让执行环境与开发者日常工作区分离,便于回收、重置和复现。
最终分流:什么时候该继续用项目设置
可以用下面的条件做最后判断:
- ✅ 任务有人实时监督,Agent 只改业务目录:保留项目配置,但禁止写
.claude和策略文件。 - ✅ 团队规则必须统一,开发者不能自行关闭:把核心策略升级到 managed settings。
- ⚠️ 沙箱缺失时仍继续执行:启用
failIfUnavailable,并关闭allowUnsandboxedCommands。 - ⚠️ Agent 需要写项目,但不能写权限配置:将
.claude、Hooks、Skills 和策略文件加入受保护范围。 - ✅ 需要包住 Claude Code 主进程:可以用 SBPL 做短期验证和过渡,但保留弃用风险记录。
- ✅ 任务长期、无人值守、失败后影响大:优先评估独立 Mac 或虚拟化执行环境,不要把单一项目 JSON 文件当作隔离方案。
常见问题
Claude Code 能不能修改自己的 settings.json?
能否修改取决于工具权限、工作区写权限和文件所在配置层级。项目目录中的 .claude/settings.json 可能处于 Agent 可写范围内,因此不能仅凭“它是配置文件”获得保护。需要用 denyWrite 或权限拒绝规则保护路径,并把不可绕过的策略放到 managed settings。
怎样禁止 Claude Code 写入 .claude 目录?
可在受保护的设置来源中加入文件写入拒绝规则,覆盖项目中的 .claude 路径,同时检查 Edit、Write 与 Bash 是否分别存在可用入口。仅在项目 settings.json 中写禁止规则不够稳妥,因为该文件本身可能被修改。无人值守任务还应关闭非沙箱逃生口。
managed settings 比项目设置更安全吗?
对于必须强制执行的策略,managed settings 更安全。官方配置层级中,managed 位于最高优先级,项目和本地设置不能覆盖它;项目设置适合团队协作和可审查的业务规则,但不适合承担防绕过、失败关闭和核心路径保护。
SBPL 能限制整个 Claude Code 进程的写权限吗?
可以从进程外为 Claude Code 及其子进程增加 macOS Seatbelt 规则,限制指定目录的读写。但 sandbox-exec 已被标记为弃用,当前可调用不等于长期受支持。SBPL 适合临时验证和过渡防护,高风险无人值守任务应评估独立 Mac 或虚拟化环境。
对多数开发者而言,当前方案是“项目级设置 + Agent 运行在日常 Mac 上”。它的问题很具体:策略文件可能与业务代码处在同一可写目录;沙箱失败时可能回退到普通权限流程;个人配置和项目配置容易通过数组合并扩大写入范围。需要长期运行 Claude Code 时,把任务放进隔离、可重置的 Mac 环境,通常比继续给同一工作区叠加例外规则更容易验收。若需要临时算力或独立测试环境,可先通过 ProxyMac 的远程 Mac 使用指南 评估登录、交付和回收流程,再决定是否租赁用于隔离验证。