Openclaw Gateway 启动流程完整教程

目录

• Gateway 启动流程详解
• 总览：调用链
• 第一阶段：CLI 参数解析
• 第二阶段：预检与配置验证
• 第三阶段：进程锁 + 信号管理
• 第四阶段：Gateway 服务器完整初始化
• 阶段 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：侧车服务启动（重要）
• 阶段 24：热重载处理器
• 阶段 25：配置重载监听
• 阶段 26：关闭处理器创建
• 第五阶段：通道启动（startChannels 展开）
• 第六阶段：稳定运行态
• 关键文件索引

以 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()

入口文件：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)

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

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

• 设置 OPENCLAW_GATEWAY_PORT 供子进程使用
• 记录已接受的环境变量选项（OPENCLAW_RAW_STREAM 等）

• readConfigFileSnapshot() 读取配置快照
• 检测遗留配置（legacyIssues），自动调用 migrateLegacyConfig() 迁移并写回
• Nix 模式下拒绝自动迁移，抛出错误
• 验证配置 schema 有效性

• applyPluginAutoEnable() 根据环境变量自动激活插件
• 有变更时写回配置并记录日志

• loadConfig() 加载最新配置
• 按需启动诊断心跳（startDiagnosticHeartbeat()）
• setGatewaySigusr1RestartPolicy() 设置重启策略
• initSubagentRegistry() 初始化子 Agent 注册表
• resolveDefaultAgentId() / resolveAgentWorkspaceDir() 解析默认 Agent 工作目录
• loadGatewayPlugins() 加载所有插件，合并 Gateway RPC 方法

• 为每个已注册渠道（Telegram、Discord、WhatsApp 等）创建独立子日志器
• 为每个渠道创建 RuntimeEnv
• 合并渠道 RPC 方法与核心方法

• resolveGatewayRuntimeConfig() 综合解析：
  • 绑定地址（bindHost）
  • 是否启用 Control UI
  • 是否启用 OpenAI 兼容端点
  • 认证配置（resolvedAuth）
  • Tailscale 配置（tailscaleMode）
  • TLS 运行时（gatewayTls）
  • Hooks 配置（hooksConfig）

• 如有自定义 controlUi.root，验证路径是否存在
• 否则调用 resolveControlUiRootSync() 自动定位前端资源
• 找不到时触发 ensureControlUiAssetsBuilt() 自动构建

• createWizardSessionTracker() 创建 onboarding wizard 会话管理器

• loadGatewayTlsRuntime() 加载 TLS 证书
• createGatewayRuntimeState() 创建核心运行时（最重要的子阶段）：
  • 创建 HTTP/WebSocket 服务器并绑定端口
  • 初始化 WebSocket 客户端集合（wss、clients）
  • 创建广播函数（broadcast、broadcastToConnIds）
  • 初始化聊天运行状态缓冲区（chatRunState、chatRunBuffers）
  • 按需启动 Canvas Host（A2UI 服务器）
  • 注册 Control UI 路由、OpenAI 兼容端点、OpenResponses 端点

• new NodeRegistry() 创建分布式节点注册表
• createNodeSubscriptionManager() 创建节点事件订阅管理器
• 定义 nodeSendEvent / nodeSendToSession / nodeSendToAllSubscribed 等通信函数
• applyGatewayLaneConcurrency() 应用车道并发配置

• buildGatewayCronService() 创建 cron 服务，支持定时 AI 任务

• createChannelManager() —— src/gateway/server-channels.ts
• 封装通道生命周期管理：startChannels / startChannel / stopChannel / markChannelLoggedOut
• 每个通道账号独立维护 ChannelRuntimeStore（aborts / tasks / runtimes）

• getMachineDisplayName() 获取机器显示名称
• startGatewayDiscovery() 启动 mDNS/Bonjour 局域网广播
• 按配置支持广域发现和 Tailscale 发现模式

• setSkillsRemoteRegistry(nodeRegistry) 注册技能远程节点注册表
• primeRemoteSkillsCache() 预热远程技能缓存
• 注册技能变更监听器（防抖 30 秒）

• startGatewayMaintenanceTimers() 启动：
  • tickInterval：定时广播 presence 版本和心跳事件
  • healthInterval：定期刷新健康状态快照
  • dedupeCleanup：定期清理去重缓存

• createAgentEventHandler() 绑定 Agent 运行事件到广播
• 将 Agent 输出（stream delta、工具事件等）实时推送给已连接客户端

• onHeartbeatEvent() 将心跳事件广播给所有客户端
• startHeartbeatRunner() 启动周期性心跳产生器
• cron.start() 启动 cron 服务

• new ExecApprovalManager() 创建命令执行审批管理器
• createExecApprovalForwarder() 创建执行请求转发器

• attachGatewayWsHandlers() 将所有 RPC 方法和事件处理器绑定到 WebSocket 服务器
• 注入完整上下文：cron、节点注册表、聊天状态、wizard、通道管理器等

• logGatewayStartup() 打印服务器监听地址、TLS 状态、配置路径等启动信息

• scheduleGatewayUpdateCheck() 异步检查是否有新版本可用

• startGatewayTailscaleExposure() 按配置执行 tailscale serve 或 tailscale funnel 命令

• startGatewaySidecars() —— src/gateway/server-startup.ts
• 按顺序启动 9 个配套服务（单个失败不阻断后续）：

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]

环境变量开关：

• OPENCLAW_SKIP_GMAIL_WATCHER=1 — 跳过 Gmail Watcher
• OPENCLAW_SKIP_CHANNELS=1 / OPENCLAW_SKIP_PROVIDERS=1 — 跳过通道启动

• createGatewayReloadHandlers() 创建配置热重载和重启请求处理器

• startGatewayConfigReloader() 监听 ~/.openclaw/config.json 文件变化
• 智能判断：小改动触发热重载（applyHotReload），大改动触发重启（requestGatewayRestart）

• createGatewayCloseHandler() 构建优雅关闭函数，注册所有需要清理的资源：
  • 停止 mDNS/Bonjour 广播
  • 清理 Tailscale 配置
  • 停止所有通道
  • 关闭 cron、心跳、维护定时器
  • 关闭 WebSocket 连接
  • 关闭 HTTP 服务器

调用链：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 控制生命周期

生命周期管理：

• 每个账号的 task 存入 store.tasks，AbortController 存入 store.aborts
• 账号异常退出时自动记录 lastError 并标记 running=false
• stopChannel() 调用 abort.abort() 通知通道优雅退出
• 可选的 plugin.gateway.stopAccount() 提供额外清理逻辑

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

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

文件	职责
src/cli/gateway-cli/run.ts	CLI 参数定义与预检（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.ts	WhatsApp 通道账号启动示例

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