OpenMausBot架构深度解析：一个harness server如何统一Claude、Codex、Grok的协议流

OpenMausBot架构深度解析：一个harness server如何统一Claude、Codex、Grok的协议流

【免费下载链接】OpenMausBotOpen Source Alternative to Grok Bot with a virtual machine that bots can use项目地址: https://gitcode.com/gh_mirrors/op/OpenMausBot

OpenMausBot 是一款开源的 Grok Bot 替代品，它的核心是一个harness server（协议统一层）：无论你给 Bot 接的是 Claude Code、Codex 还是 Grok CLI，服务端看到的都是同一套事件流和工具契约。对新手来说，理解这个统一层就理解了整个项目 80% 的架构。🧩

为什么需要 harness server？

三大引擎的"原生协议"完全不同：

如果每个前端都直接对接一种引擎，UI、审批、日志、MCP 工具挂载就得写三遍。OpenMausBot 的做法是：把所有引擎"压平"进同一个对话运行时，即 harness server 中的统一契约。

核心契约定义在 server/contracts.ts，其中ProviderAdapter接口只要求每种引擎实现 5 个能力：

• sendTurn()：发送一轮对话（携带文本、图片、系统提示、MCP 集成描述符）
• interruptTurn()：打断当前回合
• respondToRequest()：回答"是否允许执行"这类审批请求
• steer()：在回合运行中追加用户输入（可选能力）
• onEvent()：订阅统一事件流

引擎的差异全部被隔离在各自的 driver 文件里，互不干扰。

三大协议流：同一份契约，三种实现

1️⃣ Claude 流：stream-json 双向管道

Claude 驱动（server/drivers/claude.ts）为每一轮启动一个 CLI 进程，通过 stdin 写入提示词，用 stream-json 双向通信；跨轮次对话靠--resume游标续接。它还会把 Bot 的集成（云电脑、Composio 连接应用、手机工具）转成 MCP server 挂到 CLI 上，让 Claude 能直接调用。

2️⃣ Codex 流：自读 config.toml

Codex 驱动（server/drivers/codex.ts）有自己的目录解析（server/drivers/codex-catalog.ts）、设备授权流（server/drivers/codex-device-auth.ts）和身份模型。它直接读取用户本地的config.toml，harness 不重复注入 MCP 配置，只负责把统一事件转发出去。

3️⃣ Grok 流：CLI + ACP 双通道

Grok 有两条路径：原生 CLI 驱动（server/drivers/grok.ts），以及走 ACP 协议的 agent 版（server/drivers/acp/grok.ts）。ACP 是 Agent Client Protocol，OpenMausBot 把 Gemini、Kimi、Cursor、Qwen 等 10 余种引擎也统一挂在这套 ACP 桥接下（见 server/drivers/acp/ 目录）。

所有内置驱动在一个静态数组中注册（server/drivers/builtIn.ts）——注释里写得直白："添加一个驱动 = 写一个drivers/<x>.ts，然后追加进数组"。

事件总线：把 N 条协议流合成一条

统一后的事件流由 harness 的 EventBus 负责汇聚：

1. 每个引擎实例的adapter.onEvent()回调把事件交给总线；
2. 总线给每个事件盖上providerInstanceId时间戳（事件只能来自自己的驱动，跨驱动事件直接丢弃）；
3. 事件先脱敏（redactSecrets），再落盘到每个线程的canonical NDJSON 日志（<threadId>.ndjson），这就是排查问题时可以整份贴进 issue 的文件；
4. 最后分发给 SSE 端点和消息存储，UI 实时刷新。

实例的生命周期则由 ProviderRegistry 管理：配置项 → 活实例。设计上有两个亮点值得新手注意：

• 影子快照（shadow snapshot）：未知驱动或配置解析失败不会导致启动崩溃，而是降级为"不可用"快照——旧配置在新版本上能安全降级；
• 按实例隔离销毁：某个引擎的配置变更只会重建它自己，不影响同机的其他引擎。

从事件到界面：审批与能力门控

统一事件流让"执行前审批"变成一份全局体验：任何引擎想执行危险操作，都走同一张审批卡片，用户点击允许/拒绝后，harness 调用respondToRequest()把决定送回对应引擎。

另一个新手容易忽略的设计是能力门控（capabilities 字段，见 server/contracts.ts）：界面"永远不会展示引擎转不动的旋钮"。例如某驱动不支持queueing，输入框就不会开放"中途插话"；不支持图片输入，粘贴图片的入口自动消失。这套规则让多引擎混用的 Bot 不会出现"说了有电脑却找不到工具"的尴尬。

想继续深入？推荐阅读路径 📖

一句话总结：harness server 用一份契约（contracts）+ 一个总线（bus）+ 一个注册表（registry），把 Claude、Codex、Grok 乃至十余种 ACP 引擎，统一成了同一个可审批、可日志化、可热插拔的事件流——这正是 OpenMausBot 能同时兼容这么多引擎，还能让 Bot 直接使用虚拟机的架构底座。

【免费下载链接】OpenMausBotOpen Source Alternative to Grok Bot with a virtual machine that bots can use项目地址: https://gitcode.com/gh_mirrors/op/OpenMausBot