02 运行时配置文件注入

02 运行时配置文件注入

本节摘要:上一节讲了服务端如何反向托管引擎,这一节讲「让引擎听指挥」的具体手段——运行时配置注入。OpenWork 把自己定义的 Agent、插件、MCP、Provider 写入一个服务端管理的配置文件,通过环境变量交给引擎;引擎每次重建实例都重读这个文件。这套机制让 OpenWork 能让引擎「变成自己想要的样子」,却又不修改用户的引擎配置文件——这是「平台可弹出(ejectable)」的工程根基。本节是第 5 章的核心。

一、核心矛盾:要控制引擎,又不能改用户的文件

先精确描述 OpenWork 面对的矛盾。它想:

• ✅ 控制引擎的行为:让引擎用 OpenWork 定义的 Agent、加载 OpenWork 的插件、连 OpenWork 配的 MCP。
• ✅ 不修改用户的引擎配置文件:用户自己的引擎配置(如果有的话)一个字节都不动。

这两个目标看似冲突——「控制」通常意味着「改配置」,但「不改用户的文件」又堵死了这条路。OpenWork 怎么破?

二、解法:另起一份「服务端管理的配置」

解法很优雅:不改用户的配置文件,而是另起一份服务端管理的配置文件,通过环境变量让引擎优先读它。

用户的引擎配置文件(原封不动)
   │
服务端管理的配置文件(OpenWork 写的)
   │
   ▼ 通过环境变量(如 OPENCODE_CONFIG)告诉引擎「读这个」
引擎实例
   │
   ▼ 引擎优先用服务端管理的配置
   ├─ Agent 定义 = OpenWork 定义的
   ├─ 插件 = OpenWork 加载的
   ├─ MCP = OpenWork 配的
   └─ Provider = OpenWork 设的
​

关键点:

• 用户文件不动:用户的配置文件原封不动,随时可以「弹出」回原生引擎。
• 服务端文件可控:服务端管理的配置文件,OpenWork 想怎么写怎么写。
• 环境变量传递:通过环境变量告诉引擎「该读哪个配置」,引擎接受这个指引。

💡 为什么用环境变量:环境变量是「进程级」的配置传递方式——子进程(引擎)继承父进程(服务端)的环境变量。这正好契合「服务端生成引擎子进程」的托管关系(第 01 节)。服务端设环境变量,引擎子进程自然继承。

三、注入的内容:OpenWork 的四类定义

服务端管理的配置文件里写什么?主要是 OpenWork 想让引擎用的四类东西:

这些就是第 6 章「能力体系」里讲的能力(技能/插件/MCP/命令)+ Agent/Provider 配置。OpenWork 把它们写成引擎能读的格式,塞进服务端管理的配置文件。

四、引擎何时重读:每次重建实例

注入不是「一次性」的——引擎每次重建实例都会重读这份配置。这意味着:

• OpenWork 改了配置文件,引擎重建实例后立刻用新配置。
• 这就是「改了能力后引擎如何生效」的一部分机制(完整实时性见第 8 章 Reload 事件)。

OpenWork 改了配置文件
   │
   ▼ 触发引擎重建实例(第 8 章的 Reload 事件)
   │
   ▼ 引擎重建时重读服务端管理的配置文件
   │
   ▼ 新配置生效
​

⚠️ 注意:单纯的「改配置文件」不会立刻生效——要等引擎重建实例。这就是为什么需要第 8 章的 Reload 事件来「驱动引擎重建」。配置注入是「怎么写」,Reload 是「何时让引擎重读」,二者配合才完整。

五、「可弹出(ejectable)」的工程根基

这套设计最重要的副产品,是让 OpenWork 可弹出——用户随时能回到原生引擎,不依赖 OpenWork。

考虑这个场景:用户用了一阵 OpenWork,某天想直接用原生引擎(比如想用引擎的某个 OpenWork 还没支持的特性)。他怎么做?

• 因为 OpenWork 没改他的用户配置文件,他直接用引擎就行——引擎读自己的用户配置,跟 OpenWork 注入的服务端配置无关。
• 他不用「卸载 OpenWork 的修改」,因为根本没有修改——OpenWork 一直是在「另起一份」。

这就是「可弹出」:OpenWork 是个可叠加层,不是「劫持」引擎。用户随时能弹出去用原生引擎,OpenWork 不拦着。

💡 产品哲学:OpenWork 尊重用户对工具的所有权——它增强引擎,不绑架引擎。这种「可弹出」是它赢得用户信任的关键。

六、和第 01 节的衔接

把第 01 节(反向托管)和第 02 节(配置注入)合起来,你就理解了 OpenWork 接管引擎的核心:

• 第 01 节:服务端反向托管引擎(子进程 + 信任进程)——建立管理关系。
• 第 02 节:服务端注入运行时配置(环境变量 + 服务端管理文件)——让引擎听指挥。

二者合起来,实现了「不改用户文件、让引擎听指挥、可随时弹出」这三件看似矛盾的事。这是 OpenWork 作为「平台」的工程根基。

本节要点回顾

1. 核心矛盾:要控制引擎行为,又不能改用户的配置文件。
2. 解法:另起一份服务端管理的配置文件,通过环境变量(如 OPENCODE_CONFIG)让引擎优先读它。
3. 用环境变量的原因:契合「服务端生成引擎子进程」的托管关系——子进程继承父进程环境变量。
4. 注入四类:Agent 定义、插件、MCP 连接、Provider。
5. 引擎重建实例时重读:改配置要等引擎重建才生效(完整实时性见第 8 章)。
6. 可弹出:OpenWork 是可叠加层不绑架引擎,用户随时回原生引擎——这是赢得信任的关键。

注入的是「服务端管理的配置」,但用户可能也有自己的配置——两者怎么共存?这就是下一节的「三方配置合并」。