第 12 章：配置不是参数堆，而是运行时控制面
本章目标：讲清配置在 Agent 系统里到底控制什么，为什么它不是顺手补几个开关，而是在决定系统运行时能看到什么、能做什么、该怎么做。
本章对应总纲：docs/ebook-outline.md中“第 12 章正文写作提纲（2026-03-31 归档）”。
12.1 为什么很多人一提配置就自动变轻视
一说配置，很多人脑子里会自动把它归到“脏活累活”那一栏：
- 参数文件
- 环境变量
- 默认值
- 开关项
- 部署时顺手填一下的东西
这种理解很浅。
因为在 Agent 系统里，配置经常决定的不是“显示成蓝色还是绿色”，而是：
- 用哪个模型
- 开哪些工具
- 允许哪些权限
- 接哪些外部能力
- 走哪种审批策略
- 保留哪些记忆
- 暴露哪些行为入口
也就是说，配置不是边角料，而是在定义系统运行时的行为边界。
代码决定系统能做什么，配置决定这次运行到底让它做什么。
这不是到第 12 章才突然冒出来的新原则。前面工具分级、权限确认、停机出口这些分散出现的治理动作，到这里只是被集中命名成“运行时控制面”。
12.2 为什么 Agent 比普通应用更依赖配置
普通应用当然也有配置。
但 Agent 系统对配置更敏感，因为它本来就是一个高度运行时化的系统。很多关键差异都不体现在静态代码里，而体现在当前会话到底挂了什么能力、开了什么边界、选了什么策略。
例如同一套 Agent 代码，在不同配置下可能会表现成完全不同的系统：
- 一个只读，一个可写
- 一个只本地运行，一个能访问远程资源
- 一个默认谨慎确认，一个默认高自治
- 一个允许多 Agent 分工，一个强制单 Agent 收敛
所以在 Agent 场景里，配置不是修饰层，而是行为塑形层。
12.3 配置真正控制的，通常有四类东西
12.3.1 能力边界
最直接的一类就是：系统到底拥有哪些能力。
例如：
- 哪些工具可见
- 哪些 MCP 服务接入
- 哪些资源可以被发现
- 哪些外部连接允许建立
这类配置本质上是在决定 Agent 的行动半径。
12.3.2 风险边界
另一类配置控制的是：即使系统能做，也不代表它现在就该直接做。
例如：
- 哪些动作需要确认
- 哪些命令必须询问用户
- 哪些域名不允许访问
- 哪些工具默认禁用
这类配置决定的是自动化边界，不是功能存在与否。
12.3.3 策略边界
同一能力还可能有不同使用策略。
例如：
- 默认用哪个模型
- 失败后是重试、回退还是停机
- 长任务中是否启用压缩
- 是否允许调用子 Agent
这类配置决定的是系统怎么运行，而不是有没有运行资格。
12.3.4 环境边界
还有一类配置控制运行环境本身：
- 本地还是远程
- 沙箱是否开启
- 网络是否可出站
- 凭证从哪里注入
- 会话数据落到哪里
这类配置会直接影响系统与外部世界的接触方式。
12.4 为什么“把选项都做成配置”通常是坏品味
很多系统一发现配置重要，就立刻走向另一个极端：
- 什么都可配
- 什么都能改
- 什么都支持覆盖
- 什么都允许多层继承
最后结果不是灵活，而是失控。
因为配置一旦失去边界，系统很快就会出现这些烂味道：
- 默认行为看不懂
- 不同层级互相覆盖
- 同一行为有三四个入口可以改
- 问题一出现，没人知道实际生效的是哪一层
所以配置系统真正该追求的，不是“可配项尽可能多”，而是：
只把那些运行时真的需要改变、而且改变后仍然可理解的东西做成配置。
不能因为懒得做设计，就把复杂度丢给配置文件。
12.5 一个成熟配置系统，至少要回答哪几个问题
12.5.1 默认值是什么
如果没有明确默认值，系统的行为就会飘。
默认值不是补丁，而是系统立场：
- 默认保守还是默认激进
- 默认本地还是默认联网
- 默认可写还是默认只读
- 默认 ask 还是默认 allow
一个没有清晰默认值的 Agent 系统，基本等于没有稳定人格。
12.5.2 配置层级怎么叠加
现实系统里，经常会同时存在：
- 全局配置
- 项目配置
- 本地覆盖
- 会话级设置
如果叠加关系不清楚，系统就会很难预测。
所以必须说死：
- 谁覆盖谁
- 哪些字段可继承
- 哪些字段只能在高优先级层修改
- 哪些配置只在当前会话生效
12.5.3 非法组合怎么处理
配置系统不能只负责接收参数，还要负责拒绝垃圾组合。
例如：
- 要求联网，但网络被禁用
- 要求自动执行，但高风险工具全被封掉
- 要调用远程服务，但没有认证方式
- 要开子 Agent，但当前模式不允许
如果这些冲突不在配置层被拦住，最后就会把矛盾甩给运行时，变成更难调的错误。
12.5.4 可见性在哪里
用户和系统都必须能回答一个问题：
现在真正生效的配置到底是什么？
如果配置系统不能把当前有效状态说清楚，那它就不可信。
12.6 配置和代码的分工边界到底在哪
这里很容易糊。
一个够实用的划分方式是：
更适合进代码的
- 核心数据结构
- 关键执行逻辑
- 安全不变量
- 必须一致的行为约束
更适合进配置的
- 模型/工具选择
- 权限策略
- 环境地址
- 功能启停
- 会话级偏好
也就是说：
- 结构性正确性 应该尽量固化在代码里
- 运行时差异性 才应该交给配置
如果把安全不变量也做成可配项，那不是灵活，是给事故开门。
12.7 为什么配置系统会反过来塑造 Agent 的可用性
很多人觉得配置只是“工程运维问题”。
其实不是。
配置系统的质量，会直接决定 Agent 好不好用。
因为用户实际感受到的是：
- 我能不能看懂当前系统状态
- 我改一个行为要不要翻十层配置
- 我能不能预测这次操作会不会触发某个权限边界
- 我切换环境时系统会不会突然变脸
如果这些事情做不好，再强的模型也会被一个烂配置系统拖成体验垃圾。
所以配置的价值，不只是让系统更可部署，而是让系统更可理解。
12.8 用 Claude Code 看一个现实中的配置控制面
Claude Code 这种系统很适合用来理解配置为什么是控制面，而不是参数仓库。
从当前仓库就能直接看到配置在塑形运行时，而不是只在补默认值：
examples/settings/settings-strict.json直接把ask: ["Bash"]、deny: ["WebSearch", "WebFetch"]、allowManagedHooksOnly、allowManagedPermissionRulesOnly、sandbox写成策略对象，说明配置控制的是能力边界、风险边界和环境边界examples/settings/README.md还明确区分 lax / strict / bash-sandbox 三档样板，说明同一套代码在不同配置下可以长成明显不同的系统人格.vitepress/config.ts里的srcExclude、search、outline、editLink、lastUpdated又展示了另一类配置：它控制的不是安全权限，而是站点到底暴露什么、如何暴露、让用户看到什么plugins/security-guidance/CLAUDE.md和plugins/hookify/CLAUDE.md则说明 Hook 是否启用、拦截什么事件、规则从哪加载，本质上也都依赖配置层把运行时边界说清楚
你能从这些文件里抽出几条很明确的设计规则：
- 高风险能力默认不直接放开：例如 strict 样板里 Bash 需要审批，WebSearch / WebFetch 直接拒绝
- 治理规则优先于局部便利：
allowManagedHooksOnly和allowManagedPermissionRulesOnly这种字段，本质上是在限制“谁有资格改规则” - 环境约束要显式落盘：沙箱、网络、Unix socket、本地绑定这些边界都不是口头约定，而是配置对象
- 展示层也是控制面的一部分：
srcExclude说明“不给用户看什么”本身也是系统设计，不只是渲染细节
这说明现实里的 Agent 系统并不是“代码写完就定型了”。
真正运行起来的那个系统，是代码和配置一起决定的；而配置层真正承载的，是一套可复用、可审查、可下发的运行时规则。
12.9 一个坏配置系统通常会发出什么味道
有几种味道，闻到就该警惕。
第一种：层级太多
三层以上叠加还没人能说清优先级，这通常已经开始烂了。
第二种：字段太抽象
像 mode=smart、policy=advanced 这种名字，看着高级，实际没人知道会触发什么行为。
第三种：默认值不可信
文档说默认安全，实际运行默认放开；文档说默认禁用，实际某些路径又偷偷启用。
第四种：冲突不前置暴露
明明配置彼此矛盾，系统却不在启动时拦住，而是等运行到半路才炸。
第五种：用户无法知道当前生效状态
配置入口很多，但没有一个地方能清楚告诉你：现在真正起作用的是哪套规则。
这种系统早晚会把调试成本堆爆。
12.10 什么时候你该认真设计配置层
不是所有小项目都值得一开始就搞一套很重的配置系统。
但只要出现这些信号，就说明该认真了：
- 同一系统要跑在多个环境
- 不同用户需要不同权限边界
- 外部能力开始变多
- 运行策略开始出现明显分化
- 团队开始频繁改默认行为
- 你开始反复改代码，只为了切换运行模式
一旦走到这里，再把运行时差异硬写死在代码里，只会越来越难维护。
这时设计配置层不是形式主义，而是在给系统建立控制面。
12.11 本章小结
这一章真正想讲清的是：配置不是参数堆，而是 Agent 系统运行时的控制面。它控制的不只是值，而是能力边界、风险边界、策略边界和环境边界。
你现在应该记住六件事：
- Agent 系统比普通应用更依赖配置，因为它的关键差异大量发生在运行时。
- 配置真正控制的是能力、风险、策略和环境这四类边界。
- 不是所有东西都该配置化，过度配置只是在转移复杂度。
- 默认值、层级规则、冲突处理和生效可见性，是配置系统的核心质量点。
- 结构性正确性更适合放在代码里，运行时差异才适合交给配置。
- 一个好的配置系统本质上是在给 Agent 建立可理解、可治理的控制面。
下一章我们继续往下走，讲另一个非常现实的问题：当 Agent 不再只是本地 CLI 助手，而开始要接远程调用、长连接和多客户端时，为什么它迟早会走向服务化。