Security

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

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": ["."]
    }
  }
}

最终结果可能同时包含项目目录和托管目录。这里的风险不是项目设置覆盖托管设置,而是项目设置继续增加可写范围。

排查时按以下顺序操作:

  1. 在 Claude Code 中运行 /status,确认当前加载了哪些配置来源。
  2. 运行 /permissions,查看权限规则实际来自哪个文件。
  3. 运行 /doctor,检查无效字段、格式错误和配置来源问题。
  4. 搜索所有层级中的 allowWrite、denyWrite、allowUnsandboxedCommands 和 failIfUnavailable。
  5. 检查环境变量和命令行参数,因为它们也可能影响当前会话。

/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 使用指南 评估登录、交付和回收流程,再决定是否租赁用于隔离验证。

常见问题

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

使用 ProxyMac 独立运行开发任务,将项目配置、权限规则与日常环境分隔开,降低自动化流程互相影响的风险。
无需购买和维护实体设备,按需租用远程 Mac,开通后即可连接使用,适合个人开发、团队托管与无人值守任务。