OpenWork · 第 5 章 OpenCode 引擎托管与运行时配置注入

OpenWork · 第 5 章 OpenCode 引擎托管与运行时配置注入

章节摘要:OpenWork 不是一个从零造的 Agent 引擎——它基于一个开源 AI 编码 Agent 引擎(OpenCode)构建。但「基于」二字背后的工程远不简单:OpenWork 要接管这个引擎,让它按 OpenWork 的意志行事(用 OpenWork 定义的 Agent、插件、MCP、Provider),却又不能修改用户的引擎配置文件。这套看似矛盾的需求,被一个精巧的机制解决——运行时配置注入:服务端把 OpenWork 的 Agent 定义、插件、MCP、Provider 写入一个服务端管理的配置文件,通过环境变量交给引擎;引擎每次重建实例都重读该文件,配置新鲜度通过同步机制保持。再加上反向托管(服务端通过子进程生成引擎并注册为信任进程)与三方配置合并去重(legacy 配置 / 用户配置 / 服务端管理配置),OpenWork 就能在不动用户文件的前提下,让引擎「变成」OpenWork 想要的样子。本章要把这套机制讲透——这是理解「平台如何接管引擎而不篡改用户资产」的关键一章。

学习目标

阅读完本章,你应当能够:

1. 解释反向托管引擎:服务端如何通过子进程生成引擎、如何注册为信任进程、为什么需要「信任」。
2. 描述运行时配置注入:配置如何被写入服务端管理的文件、如何通过环境变量交给引擎、引擎何时重读。
3. 讲清三方配置合并去重:legacy 配置、用户配置、服务端管理配置如何叠加、冲突时谁胜出、如何去重。
4. 说明配置新鲜度同步:服务端运行时数据库写入后如何同步到配置文件、引擎如何感知变化。
5. 评价这套「接管而不篡改」的设计:它换来了什么(用户资产安全、可弹出),代价是什么(配置合并复杂度)。

核心概念速览

一句话总结:OpenWork 用「反向托管 + 环境变量注入配置 + 三方合并去重 + 新鲜度同步」四件套接管引擎——引擎按 OpenWork 的意志行事,但用户的配置文件一个字节都没动,这正是「平台可弹出(ejectable)」的工程根基。

子章节导航

01 反向托管引擎

讲服务端如何反向托管引擎:通过子进程生成引擎实例、如何注册为信任进程(让引擎接受服务端的某些特权操作)、信任进程的生命周期管理。重点说明「为什么需要信任」——某些操作(如配置注入)需要引擎信任服务端。

02 运行时配置文件注入

本章核心。讲 OpenWork 的 Agent 定义、插件、MCP、Provider 如何被写入一个服务端管理的配置文件,如何通过环境变量交给引擎,引擎何时重读(每次重建实例)。重点说明:为什么不直接改用户配置文件——为了「可弹出」,用户随时能回到原生引擎。

03 三方配置合并去重

讲三方配置如何合并:legacy 配置(老格式)、用户配置(用户自己的引擎配置)、服务端管理配置(OpenWork 注入的)。重点讲合并优先级、冲突解决、去重逻辑——为什么去重(避免同一配置被注入两次导致引擎报错)。

04 配置新鲜度同步

讲服务端运行时数据库写入后,如何通过同步机制保证配置文件新鲜(每次运行时 DB 写入后同步配置文件),引擎如何感知变化并重建实例。这一节解释了「改了能力后引擎如何实时生效」的部分机制(完整实时性见第 8 章 Reload 事件)。

子章节之间的逻辑关系

本章遵循「托管 → 注入 → 合并 → 同步」的引擎接管路径:

反向托管 (01)  ──引擎如何被生成与信任
   │
   ▼
配置注入 (02)  ──配置如何被交给引擎
   │
   ▼
三方合并 (03)  ──多源配置如何叠加
   │
   ▼
新鲜度同步 (04) ──配置变化如何生效
   │
   ▼
第 6 章:被注入的「能力」具体是什么
​

四节构成引擎接管的完整链路:生成(托管)、交付(注入)、消化(合并)、生效(同步)。理解了这四节,你才算真正理解 OpenWork 与引擎的关系——不是「用」,而是「托管且尊重」。

前置知识与后续延伸

前置知识:

• 第 2 章三进程模型(理解服务端与引擎的拓扑关系)
• 第 3 章引擎反向代理(理解服务端如何透传请求给引擎)
• 对引擎(OpenCode)的「实例」「配置」「会话」基本概念有耳闻即可(本章会回顾必要部分)

本章为后续章节奠定的基础:

• 注入的「能力」具体是什么 → 第 6 章能力体系展开
• 配置变化如何生效 → 第 8 章 Reload 事件系统补完实时性
• 「可弹出」哲学为第 13 章部署分发(用户可随时回到原生引擎)铺垫