Claude Code CLI 2.1.235 Settings 解析、合并与热重载¶

版本：2.1.235 | 证据：Static + 精确二进制 Probe | 边界：服务端 entitlement、远端 feature 实时值和组织后台下发逻辑不在本地 bundle 内。

先回答最常见的问题¶

读者问题： 我已经修改了 settings，为什么当前 Claude Code 仍然沿用旧值，或者只改了一部分行为？

一句话模型： 2.1.235 由一个进程级 settings store 持有来源缓存和合并缓存；变更先经过文件稳定、来源识别与 ConfigChange，获准后才整体失效缓存，而每个消费者再按“重新读取、订阅重建、UI 重绘或启动时捕获”决定什么时候采用新值。

这张图的结论不是“settings 支持热更新”，而是：watcher 只负责制造一次可信的失效事件，真正的生效时间由下游状态 owner 决定。

一个贯穿场景¶

假设当前进程已经启动：

• user settings 选择 model=claude-haiku-4-5；
• project settings 增加 hooks 和 MCP；
• local settings 把 model 改成 claude-opus-4-5；
• --settings 又提供 claude-opus-4-6；
• 企业 policy 固定 sandbox、MCP allowlist 和可用模型。

此时修改 .claude/settings.json 不会直接改写一个全局 JavaScript object。客户端先等文件稳定，判断是不是自己刚写出的回声，执行 ConfigChange Hook，然后把整个 settings store 的派生缓存失效。下一次读取时，五层来源重新解析和合并；sandbox 订阅者会重建配置，React/TUI 订阅者会重绘，plugin hooks 只在 plugin 相关快照真的变化时 reload，而已经发出的 API request、已经运行的工具、已有 subagent 或启动时构造的 client 不会被倒推重写。

变更前后到底改变了什么¶

1. 真正的状态 owner：Dko¶

reverse/javascript/cli.readable.js:1303-1360 的 Dko 不是普通配置对象，而是 settings 系统的进程级状态容器。

invalidateAll() 的动作是固定的：

epoch++
mergedSettings = null
perSource.clear()
parsedFiles.clear()
policy = {}
emit invalidated

它没有删除磁盘文件，也没有主动重建每个 provider client。它只宣布：旧派生状态不能再作为权威结果。

epoch 解决的竞态¶

文件解析可能异步完成。seedParsedFile(path, source, parsed, epoch) 只在调用方携带的 epoch 仍等于当前 epoch 时写回；如果期间又发生一次配置变更，旧解析结果会被拒绝。否则一次慢读就可能在新文件已经生效后重新塞回旧内容。

2. 五层来源不是五次简单覆盖¶

普通来源选择¶

source 顺序在 readable JS 39176-39215：

userSettings
< projectSettings
< localSettings
< flagSettings
< policySettings

--setting-sources 只接受 user,project,local。构造 enabled sources 时，flagSettings 和 policySettings 会被无条件补回，因此：

• --setting-sources user 会排除 project/local；
• 它不会移除 --settings/inline flag 层；
• 它不会移除 managed policy；
• flagSettings 没有文件 watcher，因为它来自本进程参数或 control request，不是外部文件生命周期。

精确二进制 Probe 已观察到：flag model 压过 local/project/user；去掉 flag 后 local 胜出；限定 user 后只发送 user model。完整输入、请求模型和 exit status 在 settings-resilience.json。

project 与 user 指向同一路径时¶

loader 会记录已处理的 resolved path；同一真实路径不会因为两个 source 名称重复 merge。专用最高优先级 resolver 也会在 project/user 路径重合时跳过 project 视图。这个细节防止一个文件被计算两次，但也意味着诊断时不能只按 source 名推断“加载了两份”。

policy 内部还有 tier¶

policySettings 自身不是单一来源。41421-41676 的组合路径至少区分：

这里有两个容易误读的点：

1. admin winner 通常取 remote -> MDM/registry -> managed file 中第一个有效对象，但某些限制性位和 env 可以跨 tier 组合；不能只展示 winner 文件名。
2. parent merge 只提取 deny/ask、managed-only 开关、sandbox 收紧项、MCP deny 等限制性子集。它不是把 parent 任意设置覆盖到设备 policy 上。

3. 解析顺序：alias、salvage、schema、fail-closed¶

alias 在 schema 之前改写¶

40951-40967 固定了两个 alias：

additionalMarketplaces -> extraKnownMarketplaces
allowedMarketplaces    -> strictKnownMarketplaces

解析单个文件时：

• 只有 alias：把值搬到 canonical key，再删除 alias；
• alias 与 canonical 同时存在：canonical 保留，alias 忽略，并产生 warning；
• alias 不会作为第二份独立设置进入 merge。

所以跨版本比较必须同时记录 schema surface 和 parse-time canonicalization。仅比较最终对象会误以为 alias 从未存在；仅比较 schema 又会误以为两者可同时生效。

普通配置允许局部 salvage¶

普通 settings 会尽量保留可解释部分：

• permission 数组中的非字符串或非法规则逐项删除；
• 未知 Hook event 或错误 Hook 结构被删除并产生诊断；
• marketplace/MCP 列表可以逐项过滤非法 entry； -某些字段使用 catch -> undefined，非法值等于该层未设置；
• 整个 JSON 语法错误或根对象不可解析时，该文件无法提供有效 settings。

这就是为什么“settings 有 warning”不一定等于整层失效。诊断必须读取 error 的 file 和 path，再确认 effective/sources 中是否还包含剩余字段。

managed policy 有更严格的失败语义¶

policy 不能把所有错误都静默当 unset。availableModels、enforceAvailableModels、managed-only lock、静态 policyHelpers.defaultSettings 等路径存在 fail-closed 或 startup-fatal 处理。尤其 per-OS static default payload 一旦结构非法，客户端会拒绝启动，避免 helper 失败时落到一份无法验证的“默认政策”。

4. 通用 merge 的四条真实规则¶

通用 cascade 使用带 customizer 的深合并。41697-41703 的 HOe 给出三条显式例外，其余对象继续走深合并：

合并完成后，policy 的 availableModels 和 enforceAvailableModels 会再次 pin 回 admin 值，防止普通深合并路径稀释模型治理。

更重要的是，很多安全设置根本不使用这个通用结果：

• J0e 只从 policy -> flag -> user 读取可信设置，排除 project/local；
• permissions、hooks、MCP allow/deny、sandbox 子字段有自己的集合和裁决顺序；
• disableClaudeAiConnectors 使用 any-source-true；
• managed-only 开关只能收紧，普通层不能反向关闭； -最终 model、effort、advisor、provider、env 还会在 request/client/session 层二次解析。

因此“effective JSON 看起来是什么”与“这次 API request/工具调用真正采用什么”是两个问题。

5. 外部文件变更的精确状态机¶

核心 watcher 在 readable JS 137179-137355。

固定阈值¶

普通 change/add¶

文件稳定
-> 解析 canonical path / symlink target
-> 若命中 5000ms internalWrites：吞掉回声
-> 执行 ConfigChange(source, file_path)
-> Hook 阻断：当前进程保留旧 cache
-> Hook 放行：Nw() 全局失效
-> emit changed(source)

ConfigChange 阻断的是当前进程采纳，不是磁盘回滚。文件已经被外部编辑器写成新内容；新进程、另一个 session 或下一次未被阻断的变更仍可能读取它。把这个 Hook 描述成“撤销配置修改”是错误的。

delete/unlink¶

删除先进入 grace timer。若文件在窗口内重建，timer 被取消并按 change 处理；若持续缺失，客户端再执行 ConfigChange。这正是兼容编辑器 write temp -> rename old -> rename temp 的关键，否则每次保存都会短暂清空配置。

policy 变更的例外¶

Hook 协议允许普通 ConfigChange 用 blocking result 阻止当前 session 采纳，但 policy_settings 会被强制改成 non-blocking。管理员 policy 不能由普通 Hook veto。MDM poll 检测到 hash 变化后直接失效 policySettings。

symlink 与目录监听¶

watcher 会同时保存 realpath -> canonical path 映射，并监听 symlink target 所在目录，从而捕捉编辑器对目标文件做 atomic save 的场景。macOS 收到 unlink 后还会重新把父目录加入 watcher，避免 rename 序列后丢失监听。

6. 程序写 settings 的路径¶

42766-42863 的写 API 与外部 watcher 不是同一路径：

1. policySettings 和 flagSettings 直接拒绝通过这个文件写 API 修改；
2. 每个目标文件进入串行队列，避免两个 UI 操作交错覆盖；
3. 优先读取已验证对象；若字段验证失败但原始 JSON 仍是 object，可用 raw object 作为 patch seed，尽量不毁掉未知/暂时非法字段；
4. JSON 语法本身无效时停止写入；
5. patch 对数组采用高层数组替换，对 marketplace map 采用 key merge；
6. 写前记录 internalWrites[path]=now；
7. Storage v5 使用对应 write discipline，普通文件使用 staging/atomic write 和 symlink/parent 检查；
8. 写成功后 Nw()，随后发出 source-specific changed；
9. watcher 稍后收到的文件事件在 5000 ms 内被识别为自身回声，不再触发第二轮 Hook/重载。

写入成功只说明目标文件和当前 settings cache 已更新。legacy local revocation、gitignore 维护、订阅者 rebuild 仍有自己的失败结果，不能压成一个 boolean。

7. 消费者为什么不会同时刷新¶

把所有字段写成“支持热更新”会掩盖真实差异。2.1.235 至少存在五种消费模式：

已确认例子：

• sandbox 在 139109-139115 订阅 settings change，并调用 runtime update；
• plugin hooks 在 185468-185483 先比较 plugin-affecting snapshot，不变则明确跳过 reload；
• quota、skills、多个 UI selector 另有 vL.subscribe；
• Agent SDK get_settings 同时返回 effective、raw sources、parse errors 和可选 applied。applied 才接近 model/effort/advisor 等当前 session 真正采用的值。

不能承诺热更新的对象¶

• 已经发送到 API 的 request body；
• 正在执行的 tool 或 hook；
• 已完成的文件/网络/进程副作用；
• 已复制上下文和工具集的 subagent；
• 已建立连接的 remote/cloud session；
• 初始化时缓存环境或凭据的第三方 SDK client。

8. Remote managed settings 的本地恢复路径¶

remote settings 同时支持 Storage v5 view 和磁盘 probe。40764-40883 的顺序是：

1. 尝试订阅 Storage v5 state/remote-settings；
2. subscription 被拒、读取失败或 view stand down 时，继续使用 disk probe；
3. 单次读取上限 2 MiB，多于 2,097,152 bytes 的 cache 直接 stand down；
4. cache file 命中 ELOOP 时按 absent 处理，而不是跟随 symlink；
5. account change 增加 reset epoch、清空 session/verified/consented payload，并让旧 backend view stand down；
6. 未验证 remote payload 的 env 只保留 allowlist，危险代理、认证、HOME/config 路径等变量被剥离；
7. shell/helper/hook/claudeMd 等危险内容只有在 verification 和 consent 状态匹配时才能进入更高权限路径。

关键等式是：

sessionCache === verifiedPayload === consentedPayload

只有三者是同一个 payload，remote-armed helper 才满足执行前提。账号变化、payload 变化或用户撤销 consent 都会破坏这个等式。

9. Policy helper 的执行与恢复状态机¶

helper 默认值和边界在 41850-42466：

首次运行与 refresh 不是同一种失败¶

remote-armed helper 的 TOCTOU 防护¶

helper 启动前记录 remoteArmGeneration。执行期间若 payload/consent 改变，generation 会推进；即便子进程已经返回成功 JSON，输出仍被丢弃。后续 refresh 也会持续比较当前 consented subject 与 helper config，不再匹配就停 timer、清状态并失效 policy。

这套机制防的是“用户同意了 A，执行或刷新时却变成 B”。它仍不能证明 helper 本身可信；helper 是管理员/用户明确授予的本地代码执行边界。

10. 156 个 direct setting 的消费者家族¶

完整逐字段语义在 Settings 全字段参考。下表不是重新堆 key，而是说明九组字段由谁拥有、主要采用哪种刷新方式。九组字段数严格相加为 156。

证据等级也必须互斥：

11. 故障诊断：按状态 owner 查，不按文件名猜¶

12. 成本、安全与恢复边界¶

• 延迟：settings cache 减少重复磁盘和 policy 组合；代价是必须精确失效，不能直接读取旧 object。
• 安全：project/local 来源隔离阻止仓库关闭 sandbox、启动危险 helper 或开启远控；managed pin 又阻止普通层放宽。
• 可用性：删除 grace、Storage v5 -> disk fallback、helper refresh 保留当前 policy 都是为了避免瞬时故障清空配置。
• 一致性：全局 epoch 防旧异步读回灌；per-file 写队列防本进程交错覆盖；它们不解决多个独立进程同时编辑同一文件的所有冲突。
• 隐私：remote 未验证 env 被 allowlist 过滤；helper stdout、Hook、claudeMd 和 settings env 仍可能携带敏感数据，日志和文档不能复制真实值。
• 不可回滚副作用：settings 失效、Hook 阻断和 session restart 都不能撤销已经执行的命令、文件写入、MCP 调用、网络请求或远端状态变化。

证据索引¶

• Store 与失效：readable JS 1303-1360。
• source selector 与 internal write TTL：39176-39228。
• remote payload trust、Storage v5、2 MiB 与 env filter：40495-40883。
• alias 与 parse salvage：40951-41179。
• source path、policy tier composition：41400-41676。
• 通用 merge 与惰性 cache：41697-41760。
• policy helper 选择、refresh、fallback、执行 envelope：41850-42466。
• programmatic write：42766-42863。
• trusted-source resolver：42936-43103。
• watcher 与 ConfigChange：137179-137355。
• sandbox subscriber：139109-139115。
• plugin hooks snapshot reload：185468-185483。
• exact-binary source precedence 与 fallback：settings-resilience.json。

客户端可以证明这些本地状态和分支。当前组织远端究竟下发了什么、服务端 feature/entitlement 如何求值、Anthropic 账户风控如何裁决，仍然是 Boundary。