01 配置层级与合并优先级

01 配置层级与合并优先级

本节摘要:一个能跑的内核背后一定有一套能管的配置体系。OpenCode 的配置不是单一文件,而是多层合并——默认值、项目级、用户级、运行时注入,按优先级叠加,冲突时谁胜出有明确规则。本节讲清这套配置层级、合并优先级、以及为什么这么设计。

一、配置不是单一文件

先破除一个误解:OpenCode 的配置不是「一个文件管所有」。它是多层的,每层有不同的作用范围和优先级:

这四层从宽到窄、从通用到具体,叠加起来构成「本次运行最终生效的配置」。

二、合并优先级

四层叠加,冲突时谁胜出?优先级从低到高:

默认值(最低)
   → 用户级
      → 项目级
         → 运行时注入(最高)
​

也就是说:运行时注入 > 项目级 > 用户级 > 默认值。越具体的层级优先级越高——这符合「越具体的意图越该被尊重」的常识。

三、为什么这么设计优先级

这个优先级不是随意的,它反映了一个原则:具体胜过通用。

• 运行时注入(环境变量/命令行)最高:因为它是「这次我明确要这么干」,最具体。
• 项目级高于用户级:项目配置是「这个项目要这样」,比「我所有项目都这样」更具体。
• 用户级高于默认值:用户偏好比内置默认更该被尊重。
• 默认值最低:只是「没设时的兜底」。

💡 类比:就像法律——宪法(默认)给大原则,地方法规(用户级)细化,公司规章(项目级)更具体,这次的任务指令(运行时)最具体。具体覆盖通用。

四、各层做什么

逐层看它们各自管什么:

默认值

内核内置的「开箱默认」。比如默认 Agent 是 build、默认权限规则、默认模型参数。这层保证「不配也能跑」。

用户级

用户主目录下的配置文件,管「我的全局偏好」:

• 我默认用哪个模型
• 我的全局主题
• 我的全局权限微调
• 我的全局技能/命令路径

这层跨项目生效——不管在哪个项目,这些偏好都适用。

项目级

项目根的配置文件(第 11 章说的配置目录里的核心文件),管「这个项目的特定设置」:

• 这个项目的 Agent 配置(如覆盖 build、加专用 Agent)
• 这个项目的权限规则(如对某目录特殊限制)
• 这个项目的技能/命令/插件路径
• 这个项目相关的 Provider

这层只在当前项目生效——换个项目就不适用。

运行时注入

环境变量、命令行参数、平台(如 OpenWork)注入。管「这次运行的具体指令」:

• 环境变量(如某 Provider 的 API Key)
• 命令行参数(如 serve 的端口)
• 平台注入(OpenWork 托管时注入的配置,OpenWork 教程第 5 章)

五、合并的细节:按项合并

合并不是「整体替换」,而是按项合并——配置有很多项(模型、权限、技能路径......),每项单独按优先级取:

模型设置:
   默认: A
   用户级: B
   项目级: (没设)
   运行时: (没设)
   ──► 取 B(用户级是设了的最高优先级)

权限规则:
   默认: [规则1]
   用户级: [规则2]
   项目级: [规则3]
   ──► 取规则3(项目级最高,设了)
​

每项独立按「设了的最高优先级」取值。这种按项合并让各层能「各管各的」——用户级管模型,项目级管权限,互不覆盖不该管的。

六、配置与第 4 章权限的关系

值得提一下配置和权限的关系。第 4 章说的「权限三段合并」(defaults + 特定 + user)其实是配置合并在权限领域的具体应用:

• defaults = 默认值层
• 特定 = Agent 定义(可能在项目级或用户级)
• user = 用户配置(用户级或项目级)

所以理解了本节的配置层级,第 4 章的权限合并就自然懂了——它们是同一套合并思想在不同领域的体现。

七、本节要点回顾

1. 配置是多层:默认值 / 用户级 / 项目级 / 运行时注入,四层叠加。
2. 优先级:运行时 > 项目级 > 用户级 > 默认(具体胜过通用)。
3. 设计原则:越具体的层级优先级越高——运行时最具体,默认最通用。
4. 各层分工:默认兜底、用户级全局偏好、项目级特定设置、运行时本次指令。
5. 按项合并:每项独立取「设了的最高优先级」,各层各管各的。
6. 与权限合并呼应:第 4 章权限三段合并是配置合并在权限领域的应用。

配置层级清楚了,下一节讲这些配置怎么被源码管理——工作区编排。