小龙虾(OpenClaw)源码分析3：Gateway启动内幕，控制平面是怎么立起来的

…
编程, 读源代码, AI, OpenClaw
文章目录

前一篇我们走完了CLI链路，这一篇终于进入核心区域：Gateway。
如果说CLI是“入口大厅”，那Gateway就是“总控室”。

入口函数：startGatewayServer

网关启动核心入口在：

  • src/gateway/server.ts（薄封装）
  • src/gateway/server.impl.ts（真实实现）

关键函数就是：

startGatewayServer(port, opts)

这个函数非常长，但别慌，按阶段拆就不难。

启动阶段拆分（建议你照这个顺序读）

我把它拆成7步：

  1. 读取并准备配置快照（含启动期修复）
  2. 处理鉴权与安全相关初始化
  3. 插件启动前准备（bootstrap）
  4. 解析运行时配置（bind/auth/tailscale/control-ui等）
  5. 创建HTTP/WS服务与运行时状态
  6. 启动通道、订阅、定时服务、配置热更新
  7. 暴露close()，处理优雅关闭

这个分层设计很像大型服务框架的启动管线：
先配置，再依赖，再监听，再副作用服务。

为什么它叫“控制平面”

看server.impl.ts你会发现，Gateway不只是“收发消息”：

  • 管鉴权（token/password等模式）
  • 管连接（WS客户端、节点、预算限制）
  • 管健康与可观测性（health/readiness/diagnostic）
  • 管插件与通道生命周期
  • 管定时任务和会话相关运行状态

这就是典型控制平面职责：把系统里的“控制逻辑”集中管理。

WS和HTTP是一体化的

OpenClaw里HTTP与WS挂在同一服务进程里，带来几个好处：

  • 控制UI和API可以共享配置/鉴权上下文
  • 节点连接和控制请求在同一状态域里
  • 运行时状态（队列、会话、健康）可统一观察

这种设计对“单机自托管助手”场景非常实用。

关闭逻辑同样重要

很多人读源码只看“怎么启动”，忽略“怎么关闭”。
startGatewayServer返回的是一个带close()的对象，这个close()会做很多善后：

  • 停止通道和插件服务
  • 停止定时器和维护任务
  • 关闭WS/HTTP服务
  • 执行gateway_stop插件钩子

这意味着它把服务生命周期完整闭环了，不是“只管拉起不管下线”。

阅读建议：别一次读完server.impl.ts

这个文件很大，我建议分三轮读：

  1. 第一轮：只看函数调用顺序（启动骨架）
  2. 第二轮：重点看配置/鉴权分支
  3. 第三轮：看插件与通道管理细节

如果第一轮就钻细节，很容易迷路。

小结

这一篇核心收获：

  • startGatewayServer是启动总管，分阶段非常清晰
  • Gateway承担的是控制平面职责，不只是消息中转
  • 优雅关闭与启动同等重要，生命周期是完整设计

下一篇我们接“消息主链路”：一条消息从入站到最终回复，具体经过哪些关键节点。

参考链接