Gateway 架构

Moltbot Gateway 是基于 WebSocket 的中央服务器，作为客户端与 AI 系统之间的通信枢纽

概述

Gateway 是 Moltbot 的控制平面，采用事件驱动的架构。它通过 WebSocket 协议与各类客户端（CLI、macOS App、iOS/Android Nodes、Web UI）通信，统一管理渠道连接、Agent 会话、配置和插件。

设计目标

  • 统一协议: 所有客户端通过 WebSocket 协议通信
  • 事件驱动: 异步消息处理和事件广播
  • 插件扩展: 支持动态加载 Channel、Provider、Tool 插件
  • 热重载: 配置变更时支持热重载（部分组件）
  • 安全认证: 设备签名、Token 认证、角色权限

启动流程

入口点

函数: startGatewayServer(port, opts)文件: src/gateway/server/server.impl.ts

配置加载

文件: src/gateway/server/server.impl.ts

// 读取配置快照
let configSnapshot = await readConfigFileSnapshot();

// 迁移遗留配置
if (configSnapshot.legacyIssues.length > 0) {
  const { config: migrated, changes } = migrateLegacyConfig(configSnapshot.parsed);
  await writeConfigFile(migrated);
}

// 应用插件自动启用
const autoEnable = applyPluginAutoEnable({ config: configSnapshot.config, env: process.env });
if (autoEnable.changes.length > 0) {
  await writeConfigFile(autoEnable.config);
}

// 最终配置
const cfgAtStart = loadConfig();

插件和通道注册

文件: src/gateway/server-channels.ts, src/gateway/server-plugins.ts

// 加载核心方法
const baseMethods = listGatewayMethods();

// 加载插件
const { pluginRegistry, gatewayMethods: baseGatewayMethods } = loadGatewayPlugins({
  cfg: cfgAtStart,
  workspaceDir: defaultWorkspaceDir,
  log,
  coreGatewayHandlers,
  baseMethods,
});

// 列出通道插件
const channelMethods = listChannelPlugins().flatMap(
  (plugin) => plugin.gatewayMethods ?? []
);

// 合并所有方法
const gatewayMethods = Array.from(new Set([
  ...baseGatewayMethods,
  ...channelMethods
]));

WebSocket

协议

协议版本

当前版本: PROTOCOL_VERSION = 3文件: src/gateway/protocol/schema/protocol-schemas.ts

消息帧类型

请求帧

{
  type: "req",
  id: string,          // 请求 ID
  method: string,      // 方法名
  params?: unknown,    // 方法参数
}

响应帧

{
  type: "res",
  id: string,          // 对应请求 ID
  ok: boolean,        // 是否成功
  payload?: unknown,  // 响应数据
  error?: {           // 错误信息对象
    code: string,
    message: string,
    details?: unknown,
    retryable?: boolean,
    retryAfterMs?: number,
  },
}

事件帧

{
  type: "event",
  event: string,      // 事件名
  payload?: unknown,  // 事件数据
  seq?: number,       // 事件序列号
  stateVersion?: {    // 状态版本
    presence?: number,
    health?: number,
  },
}

连接握手流程

支持的 RPC 方法

分类方法名说明
连接connect建立连接握手
健康health, last-heartbeat健康检查和心跳
Agentagent, agent.wait, agent.identity.get, agents.listAI Agent 操作
聊天chat.send, chat.abort, chat.history, chat.inject聊天会话管理
发送send发送消息到通道
配置config.get, config.set, config.patch, config.apply, config.schema配置管理
通道channels.status, channels.logout通道状态管理
模型models.list模型列表
技能skills.status, skills.install, skills.update, skills.bins技能管理
会话sessions.list, sessions.preview, sessions.patch, sessions.reset, sessions.delete, sessions.compact会话管理
Croncron.list, cron.status, cron.add, cron.update, cron.remove, cron.run, cron.runs定时任务
设备配对device.pair.list, device.pair.approve, device.pair.reject, device.token.rotate, device.token.revoke设备配对管理
节点node.list, node.describe, node.invoke, node.pair.*远程节点管理
执行批准exec.approvals.get/set, exec.approval.request, exec.approval.resolve命令执行批准

核心组件

WebSocket 服务器

库: ws (WebSocket) 文件: src/gateway/server-runtime-state.ts

const wss = new WebSocketServer({
  noServer: true,           // 不自动绑定 HTTP 服务器
  maxPayload: MAX_PAYLOAD_BYTES, // 512KB
});

// 绑定到 HTTP 服务器的升级事件
for (const server of httpServers) {
  attachGatewayUpgradeHandler({ httpServer: server, wss, canvasHost });
}

HTTP 服务器

文件: src/gateway/server-http.ts

支持的 HTTP 端点：

  • / - Control UI (如启用)
  • /__canvas-host - Canvas Host
  • /hooks - Web Hooks
  • /v1/chat/completions - OpenAI 兼容 API
  • /v1/responses - OpenResponses API
  • /plugins - 插件端点
  • /control-ui/* - Control UI 资源
  • /agent-avatar - Agent 头像

配置热重载

重载模式

type GatewayReloadMode = "off" | "restart" | "hot" | "hybrid";

const DEFAULT_RELOAD_SETTINGS = {
  mode: "hybrid",     // 推荐：混合模式
  debounceMs: 300,     // 防抖延迟
};

重载决策流程

关键设计决策

1. WebSocket 而非 REST API

原因：

  • 双向实时通信（Agent 进度、工具结果、事件推送）
  • 低延迟（相比 HTTP 轮询）
  • 统一的协议（req/res/event 模型）
  • 状态管理简化

2. 协议版本化

实现：

  • 客户端声明 minProtocol 和 maxProtocol
  • Gateway 返回协商的 protocol 版本
  • 支持未来兼容性检查

3. 设备签名

目的：防止设备仿冒攻击

代码路径引用

功能文件路径
服务器入口src/gateway/server/server.impl.ts
WebSocket 连接src/gateway/server/ws-connection.ts
运行时状态src/gateway/server-runtime-state.ts
消息处理src/gateway/server/ws-message.ts
HTTP 服务器src/gateway/server-http.ts
广播系统src/gateway/server-broadcast.ts
配置重载src/gateway/server/config-reload.ts
协议 Schemasrc/gateway/protocol/schema/