openclaw

关注公众号 jb51net

关闭
AI > openclaw >

Openclaw Gateway 启动流程完整教程

weixin_37747029

Gateway 启动流程详解

以 openclaw gateway run 命令为入口，追踪从 CLI 到 WebSocket 服务就绪的完整初始化链路。

总览：调用链

openclaw gateway run
  └─ src/cli/gateway-cli/run.ts         # CLI 参数解析与预检
       └─ runGatewayCommand(opts)
            └─ runGatewayLoop(params)   # 进程锁 + 信号管理 + 主循环
                 └─ src/cli/gateway-cli/run-loop.ts
                      └─ startGatewayServer(port, opts)
                           └─ src/gateway/server.impl.ts
                                │
                                ├─ createChannelManager()         # 通道管理器
                                │    └─ src/gateway/server-channels.ts
                                │
                                └─ startGatewaySidecars(...)      # 配套服务
                                     └─ src/gateway/server-startup.ts
                                          └─ startChannels()
                                               └─ for plugin of listChannelPlugins():
                                                    startChannel(plugin.id)
                                                      └─ for id of accountIds:
                                                           plugin.gateway.startAccount(...)
                                                             └─ extensions/whatsapp/src/channel.ts
                                                                  startAccount()
                                                                    └─ monitorWebChannel()
                                                                         └─ monitorWebInbox()

第一阶段：CLI 参数解析

入口文件：src/cli/gateway-cli/run.ts

addGatewayRunCommand() 将以下选项挂载到 Commander CLI：

选项说明
--port <port>WebSocket 端口（默认 18789）
--bind <mode>绑定模式：loopback / lan / tailnet / auto / custom
--token <token>共享 token（也可通过 OPENCLAW_GATEWAY_TOKEN 环境变量设置）
--auth <mode>认证模式：token 或 password
--password <pw>password 模式下的密码
--tailscale <mode>Tailscale 暴露模式：off / serve / funnel
--force启动前强制杀死占用端口的进程
--dev开发模式：自动创建配置和 workspace
--verbose详细日志输出
--ws-log <style>WebSocket 日志样式：auto / full / compact

第二阶段：预检与配置验证

函数：runGatewayCommand(opts) —— src/cli/gateway-cli/run.ts

按顺序执行以下检查：

  1. 开发模式检测：OPENCLAW_PROFILE=dev 或 --dev 时进入开发模式，调用 ensureDevGatewayConfig()
  2. 日志配置：启用时间戳前缀、设置 verbose 等级、配置 WebSocket 日志样式
  3. 端口解析：--port 优先，否则读取 config.gateway.port，默认 18789
  4. 强制释放端口：--force 时调用 forceFreePortAndWait() 尝试 SIGTERM → SIGKILL
  5. 认证配置解析：
    • 合并 config + 命令行参数
    • 调用 resolveGatewayAuth() 解析最终的 token / password / tailscale 认证
  6. 配置存在性检查：非 local 模式必须存在 ~/.openclaw/config.json
  7. 绑定模式验证：非 loopback 绑定必须配置 token 或 password
  8. 进入主循环：调用 runGatewayLoop() 进入下一阶段

第三阶段：进程锁 + 信号管理

函数：runGatewayLoop(params) —— src/cli/gateway-cli/run-loop.ts

runGatewayLoop()
  │
  ├─ 1. acquireGatewayLock()            # 获取文件锁，防止多实例
  │       └─ src/infra/gateway-lock.ts
  │            写入 .pid 锁文件，并持有独占句柄
  │
  ├─ 2. 注册信号处理器
  │       ├─ SIGTERM → request("stop")   # 容器/系统关机
  │       ├─ SIGINT  → request("stop")   # Ctrl+C
  │       └─ SIGUSR1 → request("restart") # 热重启（需授权令牌）
  │
  ├─ 3. while (true) 主循环
  │       ├─ server = await params.start()   # 启动服务器（见第四阶段）
  │       └─ await new Promise(resolve => { restartResolver = resolve })
  │               # 挂起等待信号；SIGUSR1 触发时 restartResolver() 解除
  │
  └─ 4. finally 清理
          ├─ lock.release()              # 释放文件锁
          └─ cleanupSignals()            # 移除所有信号处理器

超时保护：信号触发后 5 秒若未完成关闭，强制 process.exit(0)

第四阶段：Gateway 服务器完整初始化

函数：startGatewayServer(port, opts) —— src/gateway/server.impl.ts

共 26 个子阶段，按顺序执行：

阶段 1：环境变量准备

阶段 2：配置加载和迁移

阶段 3：插件自动启用

阶段 4：基础运行时初始化

阶段 5：渠道插件日志器初始化

阶段 6：运行时配置解析

阶段 7：Control UI 资源准备

阶段 8：Wizard 会话跟踪器

阶段 9：创建 Gateway 运行时状态

阶段 10：节点注册和订阅管理

阶段 11：定时任务服务

阶段 12：渠道管理器

阶段 13：服务发现

阶段 14：技能远程注册

阶段 15：维护定时器

阶段 16：Agent 事件处理器

阶段 17：心跳事件处理器

阶段 18：执行审批管理器

阶段 19：WebSocket 处理器绑定

阶段 20：启动日志输出

阶段 21：更新检查调度

阶段 22：Tailscale 暴露

阶段 23：侧车服务启动（重要）

startGatewaySidecars()
  │
  ├─ 1. 浏览器控制服务器    startBrowserControlServerIfEnabled()
  ├─ 2. Gmail Watcher      startGmailWatcher()
  ├─ 3. Gmail 模型验证     getModelRefStatus()
  ├─ 4. 内部 Hook 处理器   clearInternalHooks() + loadInternalHooks()
  ├─ 5. 通信渠道           startChannels()   ← 见第五阶段
  ├─ 6. Hook 事件触发      triggerInternalHook("gateway:startup") [+250ms]
  ├─ 7. 插件服务           startPluginServices()
  ├─ 8. 内存后端           startGatewayMemoryBackend()  [异步，不等待]
  └─ 9. 重启哨兵恢复       scheduleRestartSentinelWake() [+750ms]

环境变量开关：

阶段 24：热重载处理器

阶段 25：配置重载监听

阶段 26：关闭处理器创建

第五阶段：通道启动（startChannels 展开）

调用链：startGatewaySidecars → startChannels() → server-channels.ts

startChannels()
  └─ for (plugin of listChannelPlugins())      # 遍历所有已注册通道插件
       └─ startChannel(plugin.id)
            │
            ├─ loadConfig()                    # 加载最新配置
            ├─ plugin.config.listAccountIds()  # 获取该通道的账号 ID 列表
            │
            └─ for (id of accountIds)          # 并发启动所有账号
                 │
                 ├─ plugin.config.isEnabled()  → 禁用则标记 running=false
                 ├─ plugin.config.isConfigured() → 未配置则标记 running=false
                 │
                 ├─ new AbortController()      # 创建中止控制器
                 ├─ setRuntime(running=true)   # 标记账号为运行中
                 │
                 └─ plugin.gateway.startAccount({
                        cfg, accountId, account,
                        runtime, abortSignal, log,
                        getStatus, setStatus
                    })
                      │
                      └─ [以 WhatsApp 为例]
                           extensions/whatsapp/src/channel.ts
                             startAccount()
                               └─ monitorWebChannel()
                                    └─ monitorWebInbox()
                                         # 轮询/监听 WhatsApp Web 收件箱
                                         # 通过 abortSignal 控制生命周期

生命周期管理：

第六阶段：稳定运行态

Gateway 服务就绪后持续运行，处理以下任务：

任务触发方式说明
WebSocket RPC 调用客户端请求处理 send、status、channel.* 等 RPC 方法
Agent 事件广播onAgentEvent将 AI 输出实时推送给已连接客户端
心跳广播定时器维持客户端连接活跃
配置热重载文件监听配置文件变化时自动应用新配置
健康状态刷新定时器定期刷新 /health 端点快照
Cron 任务执行定时器按计划执行 AI 定时任务
mDNS 广播Bonjour局域网内持续广播服务信息
SIGUSR1 热重启进程信号无需重启进程，原地重新初始化服务器

关键文件索引

文件职责
src/cli/gateway-cli/run.tsCLI 参数定义与预检（506 行）
src/cli/gateway-cli/run-loop.ts进程锁 + 信号处理 + 主循环（203 行）
src/gateway/server.impl.ts服务器完整初始化（791 行，26 个子阶段）
src/gateway/server-channels.ts通道生命周期管理器（309 行）
src/gateway/server-startup.ts配套服务启动编排（417 行，9 个配套服务）
src/gateway/auth.ts认证解析与连接授权
src/infra/gateway-lock.ts文件锁机制，防止多实例
src/gateway/config-reload.ts配置热重载监听器
extensions/whatsapp/src/channel.tsWhatsApp 通道账号启动示例

到此这篇关于Openclaw Gateway 启动流程完整教程的文章就介绍到这了,更多相关Openclaw Gateway 启动内容请搜索脚本之家以前的文章或继续浏览下面的相关文章，希望大家以后多多支持脚本之家！