OpenClaw 深度解析与源代码导读 · 第3篇：Gateway——常驻控制面、单端口多协议与进程骨架

摘要Gateway网关是 OpenClaw 的常驻控制进程。它在一个端口上同时处理多种协议WebSocket用于实时控制和远程调用RPCHTTP提供 OpenAI 兼容的 API 接口还有管理界面UI和画布Canvas功能。无论是即时通讯IM渠道、桌面客户端还是自动化脚本都必须先连接到 Gateway然后才能使用 Router路由、Brain大脑和 Hands执行器等功能。本文结合官方Gateway Runbook运行手册和Network model网络模型文档讲解三个核心概念单实例锁定通过独占端口实现、默认身份验证、健康检查与配置热重载。同时我们将基于源码固定 commit走读启动流程从openclaw gateway命令行到runGatewayLoop处理锁和信号再到startGatewayServer组装运行时为下一篇 Router 做好铺垫。关键词OpenClawGateway网关WebSocketHTTP 多路复用单实例openclaw gatewaystartGatewayServer健康检查源码走读系列文章OpenClaw 深度解析与源代码导读 · 第1篇系列导读——术语、版本与读源码方法OpenClaw 深度解析与源代码导读 · 第2篇Skills——能力扩展平面与源码中的「目录即技能」源码版本说明本文引用路径基于 openclaw/openclaw 仓库本地阅读使用的 commit 为0dd4958bc8a78d26b3b526b1f2e63b15110c64a22026-04-11。GitHub 上可按该 SHA 查看对应版本的源码避免main分支变动导致的差异。1 OpenClaw 架构全景与 Gateway 的位置在深入 Gateway 之前先通过一张架构图理解Gateway 在 OpenClaw 整体中的位置延续第1篇的餐厅比喻1.1 各组件职责速查表组件餐厅比喻技术职责与 Gateway 的关系Gateway前台/入口单进程常驻控制面单端口多协议WebSocket HTTP身份验证健康检查本文主角—— 所有流量的第一站Router订单分发员决定消息流向进 Brain走快捷路径直接回包Gateway 收到请求后交给 Router 决策Brain主厨/大脑LLM 推理、上下文管理、工具调用循环经 Gateway → Router 后进入Hands端锅/执行Shell、文件操作、浏览器控制被 Brain 调用通过 Gateway 返回结果Skills预制酱料包SKILL.md 扩展能力按需加载经 Gateway 目录扫描后暴露给 BrainMemory台账/便签墙持久化存储、会话状态、长期记忆各组件通过 Gateway 协调访问Channels外卖平台/电话线IM 渠道长连接管理WhatsApp/Slack 等挂载在 Gateway 上Gateway 保持长连接1.2 数据流向示例场景用户发送一条 WhatsApp 消息给 Agent理解要点Gateway 是“一夫当关”的入口但它不处理业务逻辑——只负责“接进来、送出去、保安全、管连接”。2 为什么要单独写一篇 Gateway在第1篇里我们把 Gateway 比作餐厅的前台它不亲自炒菜Brain 负责也不端盘子Hands 负责但所有顾客渠道消息、外卖订单HTTP API、排号屏幕控制 UI都必须先经过它。如果跳过 Gateway 直接研究auto-reply或某个具体渠道插件很容易混淆几个关键问题谁负责维持长连接谁在做身份验证谁在检查服务是否存活本文解答三个核心问题产品定位Gateway 进程负责什么、不负责什么与多 Agent、workspace 隔离的关系在第1篇已有本文补充网络边界和进程边界。运维操作如何启动 / 检查健康状态 / 排查故障以及为什么默认开启身份验证、为什么独占端口。源码结构从openclaw gateway命令到startGatewayServer建立后续 Router 篇需要的“入口函数地图”。理解要点本文刻意不展开每一条 WebSocket RPC 协议细节那是协议层内容见 D1 bridge-protocol本文聚焦进程模型 端口模型 启动调用链。3 运行时模型一个进程、一个端口、多种功能官方 RunbookD1Gateway runbook用几句话概括了运行时模型核心要点如下一个常驻进程负责消息路由、控制面和渠道的长连接管理。同一个端口同时承载多种协议WebSocket用于实时控制和远程调用RPCHTTP提供 OpenAI 兼容接口如/v1/models、/v1/chat/completions、/v1/responses、/v1/embeddings、/tools/invoke等管理 UI、Canvas 相关路由等。默认绑定地址loopback回环地址即 127.0.0.1默认身份验证开启通过共享密钥gateway.auth.token/password或环境变量OPENCLAW_GATEWAY_*非回环地址场景可使用trusted-proxy可信代理等模式见 D1 configuration、trusted-proxy-auth。实际例子默认地址是ws://127.0.0.1:18789端口可修改。本地命令行工具CLI、终端界面TUI、桌面客户端都通过同一个 WebSocket 地址进行远程调用Open WebUI 这类客户端通常会先GET/v1/models获取模型列表再 POST 聊天请求——这些请求都落在同一个 Gateway 端口上由 HTTP 和 WebSocket 分别处理。3.1 与网络模型文档的关系docs/gateway/network-model.md提示部分内容已并入站点Network总页但核心结论值得深入理解为什么建议每台主机运行一个 Gateway核心原因是WhatsApp Web 等渠道的技术限制。这些 IM 渠道使用QR 码扫码登录机制且一个手机号同一时间只能有一个活跃的 Web 会话。如果同一主机上运行多个 Gateway 进程它们会互相竞争 WhatsApp Web 连接导致频繁掉线后启动的 Gateway 会踢掉先登录的会话消息丢失正在处理的对话可能中断状态混乱多个进程同时尝试维持心跳触发平台的风控其他渠道Discord、Slack、Telegram 等 Bot Token 机制无此限制但为统一管理OpenClaw 仍建议单主机单 Gateway作为默认部署模式。什么是强隔离何时需要多 Gateway当以下场景出现时需要在一台物理机上运行多个完全独立的 Gateway 实例场景隔离需求实现方式多用户/多租户用户 A 和用户 B 的数据绝不能互通不同的OPENCLAW_HOME目录测试 vs 生产测试环境的故障不能影响生产服务不同的profile如--profile test多 WhatsApp 号一个公司需要同时运营多个 WhatsApp 业务号不同的端口 不同的工作目录不同网络环境部分服务走 VPN部分走公网不同的绑定地址 路由规则“多 profile、多端口、多OPENCLAW_HOME” 详解这三个是正交维度可以组合使用1. Profile配置档案作用隔离不同的配置集合生产配置、测试配置、开发配置使用openclaw gateway --profile productionvs--profile staging存储位置~/.openclaw/profiles/profile-name/2. 端口Port作用网络层隔离避免端口冲突使用openclaw gateway --port 18789默认vs--port 18790注意每个端口对应一个独立的Gateway 单实例锁§43.OPENCLAW_HOME主目录作用彻底隔离所有数据配置、会话存储、日志、技能目录使用export OPENCLAW_HOME/opt/company-a/openclaw效果两个 Gateway 实例即使运行在同一用户下也看不到彼此的数据典型部署模式示例模式一单用户单机默认# 一个 Gateway默认端口 18789openclaw gateway模式二开发/测试分离# 终端 1生产环境echoPRODOPENCLAW_HOME/home/user/openclaw-prod openclaw gateway--port18789--profiledefault# 终端 2测试环境echoTESTOPENCLAW_HOME/home/user/openclaw-test openclaw gateway--port18790--profiletest模式三多租户隔离伪代码# 租户 A - 电商客服sudo-utenant-aOPENCLAW_HOME/var/tenants/a openclaw gateway--port18001# 租户 B - 内部 IT 支持sudo-utenant-bOPENCLAW_HOME/var/tenants/b openclaw gateway--port18002每个租户有独立的 Linux 用户tenant-avstenant-b独立的$OPENCLAW_HOME/var/tenants/{a,b}独立的端口18001vs18002独立的 WhatsApp 登录会话理解要点“单主机单 Gateway” 是建议而非强制。当业务需要隔离时通过profile × port × OPENCLAW_HOME的组合可以在同一台机器上构建出逻辑上完全独立的多个 Gateway 实例每个实例有自己的进程边界、网络边界、存储边界。详见 D1 Multiple gateways 完整文档。4 单实例不靠 PID 文件靠谁先占用端口谁运行D1 Gateway lock 文档解释得很清楚目的同一主机、同一端口上只能运行一个Gateway第二个实例必须立即失败并给出清晰的错误提示。机制启动时立即在 WebSocket 监听地址上建立独占的 TCP 监听exclusive TCP listen如果端口已被占用EADDRINUSE错误抛出GatewayLockError——不需要额外的 lock 文件进程崩溃或被强制终止SIGKILL后操作系统会自动回收端口。运维如果端口被非 OpenClaw的程序占用错误表现与第二个 Gateway相同需要通过openclaw gateway --port port更换端口或释放占用该端口的程序。这与传统守护进程写/var/run/foo.pid文件的方式不同锁就是监听套接字socket本身排查故障时直接用netstat或端口诊断工具即可。4 生命周期用户视角启动、检查健康、看日志Runbook 的5-minute local startup可直接作为本文的验收清单启动 Gatewayopenclaw gateway --port 18789或使用openclaw gateway --force强制释放占用端口后再启动。检查状态openclaw gateway status/openclaw status—— 确认看到Runtime: running和RPC probe: ok等基础信息。检查渠道openclaw channels status --probe—— 当 Gateway可访问时对各渠道进行在线探测如果 Gateway 不可达命令行工具会降级为仅显示配置摘要Runbook 已说明这种分叉行为。更深入的健康检查见 D1 health.mdopenclaw health、openclaw status --deep等命令会向运行中的 Gateway 请求快照或实时探测——注意openclaw health默认不直接连接各渠道的套接字而是通过WebSocket 询问 Gateway由 Gateway 侧协调探测。配置热重载Runbook 的Note说明Gateway 监听活动配置文件路径OPENCLAW_CONFIG_PATH或 profile 默认路径gateway.reload.mode默认值为hybrid——首次成功加载后进程持有内存中的配置快照成功重载时原子化切换快照。这样 Gateway 可以在不完全重启的情况下应用部分配置变更具体支持哪些配置项以 D1 文档为准。5 源码走读从命令行到startGatewayServer下面是一条可放入脑图的主路径供你在本地用rg或跳定义功能跟随走读。5.1 命令行注册gateway子命令是什么src/cli/gateway-cli/register.ts把子命令注册到 Commander 框架上描述直接点题WebSocket Gateway的运行、巡检与发现功能// src/cli/gateway-cli/register.ts节选exportfunctionregisterGatewayCli(program:Command){constgatewayaddGatewayRunCommand(program.command(gateway).description(Run, inspect, and query the WebSocket Gateway)// … 帮助示例gateway run / status / discover …理解要点openclaw gateway不是另一个 REST 小工具而是同一套运行时的运维入口——与openclaw status等命令共享“如何找到正在运行的那个进程”这一语境。5.2 运行循环runGatewayLoop—— 处理锁、信号、重启src/cli/gateway-cli/run-loop.ts在真正启动startGatewayServer之前调用acquireGatewayLock持有锁期间创建server并处理SIGINT/SIGTERM/SIGUSR1等优雅停机和重启包括清空队列、释放锁后再生成子进程等细节文件后半部分继续展开。// src/cli/gateway-cli/run-loop.ts节选exportasyncfunctionrunGatewayLoop(params:{start:(params?:{startupStartedAt?:number})PromiseAwaitedReturnTypetypeofstartGatewayServer;runtime:RuntimeEnv;lockPort?:number;}){letlockawaitacquireGatewayLock({port:params.lockPort});letserver:AwaitedReturnTypetypeofstartGatewayServer|nullnull;// … 注册信号关机时 releaseLock重启路径可能生成新进程 …读这里的目的把“GatewayLockError 端口冲突”与源码入口对齐——文档里的锁机制对应代码里acquireGatewayLockstart失败路径而不是散落在各渠道插件里。5.3 服务器组装startGatewayServer—— 配置、插件、渠道、WebSocketsrc/gateway/server.ts只是薄转发层thin re-export实现位于server.impl.ts。startGatewayServer(port, opts)一进来就把端口写入环境变量OPENCLAW_GATEWAY_PORT随后流水线大致如下加载配置快照loadGatewayStartupConfigSnapshot→prepareGatewayStartupConfig包含身份验证引导auth bootstrap、可能生成并持久化 token诊断心跳、SIGUSR1 重启策略、控制 UI 的 allowedOrigins 种子等横切关注点prepareGatewayPluginBootstrap整理插件 / 渠道相关注册表和gatewayMethods列表resolveGatewayRuntimeConfig、startGatewayEarlyRuntime、attachGatewayWsHandlersWebSocket 运行时、createChannelManager、startManagedGatewayConfigReloader……直到 HTTP/WebSocket监听建立。节选只看头部在做什么// src/gateway/server.impl.ts — startGatewayServer节选exportasyncfunctionstartGatewayServer(port18789,opts:GatewayServerOptions{}):PromiseGatewayServer{constminimalTestGatewayprocess.env.VITEST1process.env.OPENCLAW_TEST_MINIMAL_GATEWAY1;process.env.OPENCLAW_GATEWAY_PORTString(port);constconfigSnapshotawaitloadGatewayStartupConfigSnapshot({minimalTestGateway,log});constauthBootstrapawaitprepareGatewayStartupConfig({configSnapshot,authOverride:opts.auth,tailscaleOverride:opts.tailscale,activateRuntimeSecrets,});constcfgAtStartauthBootstrap.cfg;// … 诊断 / 重启策略 / 控制 UI 种子 …constpluginBootstrapawaitprepareGatewayPluginBootstrap({cfgAtStart,startupRuntimeConfig:applyConfigOverrides(configSnapshot.config),minimalTestGateway,log,});// … resolveGatewayRuntimeConfig → attachGatewayWsHandlers / channels / reload …实际例子如果启动日志出现“生成了 runtime token 但未写入配置”这类警告对应authBootstrap分支里对persistedGeneratedToken的判断——这直接影响“重启后 token 是否会变化”排查故障时应回到D1 configuration secrets文档确定持久化策略。5.4 一张总图把 §5.1§5.3 串起来6 与第2篇Skills的边界Skills子系统解决“磁盘上的SKILL.md如何变成模型可见的available_skills”见第2篇Gateway解决“谁长期在线、谁在哪个端口上同时接受 WebSocket/HTTP、谁去拉起渠道和健康探测”。二者在运行时交汇会话快照、配置重载、RPC但职责不混写读 Skills 不必深入 HTTP 路由读 Gateway 也不必读完整个SKILL.md解析器。7 Gateway 安全隐患与加固建议Gateway 作为所有流量的入口和常驻进程其配置直接决定了系统的攻击面大小。以下是基于文档设置的关键安全风险及应对建议更全面的安全分析将在第14篇安全与成本展开。7.1 网络暴露风险与bind设置相关Gateway 设置安全风险文档出处默认loopback127.0.0.1仅本机可访问风险最低§2改为0.0.0.0或公网 IP任何人可尝试连接若身份验证配置不当则完全暴露§2trusted-proxy模式依赖上游代理做鉴权若代理配置错误如未过滤伪造头攻击者可绕过§2实际风险场景如果将 Gateway 绑定到0.0.0.0:18789且使用弱 token或关闭鉴权攻击者可直接调用/v1/chat/completions消耗你的 API Key或通过 WebSocket 接口操纵 Agent。7.2 身份验证绕过与auth设置相关文档提到的鉴权方式§2gateway.auth.token/password共享密钥环境变量OPENCLAW_GATEWAY_TOKEN/OPENCLAW_GATEWAY_PASSWORDtrusted-proxy可信代理风险最高隐患若使用password且密码强度不足或 token 泄露如提交到 GitHub攻击者可在任何能访问该端口的主机上伪装为合法客户端。7.3 单实例锁的副作用与端口占用相关文档§3说明“锁就是监听套接字socket本身”。安全隐患若 Gateway 崩溃后未正确释放端口极少数内核异常或恶意程序故意占用18789端口并伪装成 Gateway客户端可能连接到假 Gateway导致中间人攻击MITM。7.4 配置热重载的风险与reload.mode相关§4提到gateway.reload.mode默认hybrid支持不完全重启即可应用配置变更。安全隐患如果攻击者通过某种方式如配置文件注入、环境变量篡改修改了gateway.auth.tokenGateway 可能在不中断服务的情况下应用新配置导致合法用户被踢出或非法用户获得访问权。7.5 健康检查信息泄露与health端点相关§4提到openclaw health、openclaw status --deep等命令会返回健康快照health snapshot。隐患这些快照可能包含渠道连接状态、运行时配置片段、会话统计信息。如果 Gateway 的鉴权被绕过攻击者可借此进行信息收集为后续攻击做准备。7.6 安全加固建议基于文档设置层级建议配置对应文档网络层保持默认loopback如需远程访问使用Tailscale/SSH 隧道而非直接暴露§2, §2.1认证层使用强随机 tokengateway.auth.token定期轮换避免password模式§2进程层使用--force重启确保旧进程完全终止监控GatewayLockError日志§3, §4配置层限制配置文件权限~/.openclaw/目录 600谨慎使用hybridreload§4监控层定期检查openclaw gateway status和日志确认无异常连接§4理解要点Gateway 的绑定地址bind、身份验证模式auth mode、端口占用策略共同构成了 OpenClaw 的第一道防线。文档§2-§4 的所有设置项都应从安全视角重新审视——它们既是功能配置也是安全策略。8 D3 参考阅读与扩展学习8.1 OpenClaw 官方视角博客OpenClaw Gateway Explaineddench.com —— 架构层面的 Gateway 解读适合理解设计哲学。How to Set Up an OpenClaw AI Gateway in 2026getclawhosting.com —— 运维部署向含端口配置、systemd 服务设置等实操内容。注意核对其端口/路径描述是否与你本机openclaw.json一致。8.2 AI Gateway 安全通用参考跨项目借鉴以下资源虽非 OpenClaw 专属但讨论了 AI Gateway 共性的安全挑战LLM API Gateway Security PatternsCloudflare Blog—— 讨论 API Key 轮换、速率限制、提示词过滤等通用模式可借鉴到gateway.auth配置思路。AI Infrastructure Security: Gateway Proxy PatternsMITRE/OWASP—— 模型供应链攻击、提示词注入防御可与第14篇安全内容对照阅读。Tailscale AI Tools 安全实践Tailscale Blog—— 与本文§2.1提到的Tailscale 替代直接暴露思路一致提供具体组网方案。8.3 安全专项内容预告更全面的安全分析将在第14篇安全与成本展开包括多 Agent 攻击面与OPENCLAW_HOME强隔离沙箱逃逸风险与 Hands 权限边界按 Agent 选择模型的成本与安全权衡9 本篇小结与下一篇预告小结Gateway 单进程控制面单端口多协议独占 bind绑定 单实例锁身份验证默认开启健康与渠道探测由 Gateway 侧协调启动主链registerGatewayCli→runGatewayLoop→startGatewayServer。安全方面需重点关注bind 地址、auth 模式、token 生命周期。下一篇第4篇Router路由器——入站消息进入 Gateway 之后如何分发到 Brain / 快捷路径 / 渠道回包与官方 Data flow 第 2 步对齐。10 参考文献与链接OpenClaw 主仓库https://github.com/openclaw/openclawArchitecture OverviewD2http://clawdocs.org/architecture/overviewGatewayD2http://clawdocs.org/architecture/gatewayGateway RunbookD1https://github.com/openclaw/openclaw/blob/0dd4958bc8a78d26b3b526b1f2e63b15110c64a2/docs/gateway/index.mdNetwork modelD1https://github.com/openclaw/openclaw/blob/0dd4958bc8a78d26b3b526b1f2e63b15110c64a2/docs/gateway/network-model.mdGateway lockD1https://github.com/openclaw/openclaw/blob/0dd4958bc8a78d26b3b526b1f2e63b15110c64a2/docs/gateway/gateway-lock.mdHealth checksD1https://github.com/openclaw/openclaw/blob/0dd4958bc8a78d26b3b526b1f2e63b15110c64a2/docs/gateway/health.mdGateway configurationD1https://github.com/openclaw/openclaw/blob/0dd4958bc8a78d26b3b526b1f2e63b15110c64a2/docs/gateway/configuration.mdBridge protocolD1WS/RPChttps://github.com/openclaw/openclaw/blob/0dd4958bc8a78d26b3b526b1f2e63b15110c64a2/docs/gateway/bridge-protocol.md