1. 从一次连接被拒说起OpenClaw Gateway 到底在调度什么如果你正在读 OpenClaw 的源码大概率会在src/gateway这个目录里卡住。我第一次跑openclaw gateway的时候客户端连上去三秒就被踢掉日志里只有一行challenge verify failed当时完全不知道从哪里下手。后来把src/gateway下的文件逐个翻了一遍才明白Gateway 不是普通的 HTTP 服务器它是整个 OpenClaw 的控制平面所有外部交互、内部模块协同、工具调用请求都要经过它。它同时承担了 WebSocket 长连接管理、JSON-RPC 风格的消息分发、会话持久化、通道注册、定时任务触发这几件事任何一环出问题都会表现为“连不上”或“连上就断”。这篇内容聚焦src/gateway目录下的源码结构围绕 WebSocket 长连接与 JSON-RPC 消息分发两条主线把 Gateway 的调度逻辑拆开讲清楚。目标很具体给你一份可复制的 gateway 配置骨架带你在本地把服务跑起来用真实的 WebSocket 客户端完成一次connect → req → res的完整往返并且把 AI 工具联调时用到的统一 Key/API 通道接进来。适合已经能跑起 OpenClaw 主程序、想深入理解调度层、或者正在做二次开发自定义通道、插件、钩子的人。读完之后你应该能自己判断消息从客户端发出后在 Gateway 内部经过了哪几个模块卡在哪一步该看哪个日志。2. 前置准备TaoToken 统一通道与本地环境在动 Gateway 之前先把 AI 工具侧的调用通道准备好。OpenClaw 的 Gateway 本身只负责调度真正执行推理和工具调用的是 Agent 层而 Agent 层要访问模型能力时走的就是统一的 API 通道。我这边习惯用 TaoToken 来做这件事原因是它把 Key 管理和 API 入口统一了联调时不用在多个配置文件里来回改 base_url 和 token。你需要先拿到一个可用的 API Key。打开控制台创建即可https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite创建完 Key 之后在 API Keys 页面可以查看和管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteAPI 的基础入口是https://taotoken.net/api注意这个地址不带任何查询参数配置里直接写它就行。如果你要对照接口字段和请求格式接入文档在这里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite本地环境方面Node.js 版本建议 22 及以上因为 Gateway 依赖的sqlite-vec在新版本 Node 上安装更顺。包管理器用 pnpm和 OpenClaw 仓库保持一致。确认一下node -v # v22.x 或更高 pnpm -v # 9.x 或更高然后进入 OpenClaw 项目根目录安装依赖pnpm install这一步如果卡在sqlite-vec编译上先别急着怀疑 Gateway 代码大概率是构建工具链的问题后面第 5 节会专门讲。3. 可复制配置gateway 配置骨架与 src/gateway 关键文件3.1 配置文件骨架Gateway 的配置合并优先级是环境变量 用户配置~/.openclaw/config.yaml 默认配置。所以本地调试时最省事的做法是只写用户配置把要覆盖的字段填上。下面这份骨架可以直接复制改掉注释里标出的几项就能用# ~/.openclaw/config.yaml gateway: # 监听端口默认 18789 port: 18789 # 本地调试保持 127.0.0.1需要局域网访问再改 0.0.0.0 bindHost: 127.0.0.1 # 远程连接必须配置私钥本地连接可留空 auth: privateKey: # 认证失败后断开连接的等待时间毫秒 verifyTimeout: 3000 # 会话持久化基于 SQLite sessions: dbPath: ~/.openclaw/sessions.db # 自动持久化间隔分钟 flushInterval: 5 # 定时任务标准 cron 表达式 cron: timezone: Asia/Shanghai jobs: - name: daily-ping schedule: 0 8 * * * action: tool.invoke params: tool: weather city: Shanghai # AI 通道指向统一 API 入口 ai: baseUrl: https://taotoken.net/api apiKey: ${TAOTOKEN_API_KEY} model: claude-sonnetapiKey这里用了环境变量占位实际运行时通过export TAOTOKEN_API_KEY你的Key注入避免把密钥写进文件。这一点在多人协作或者把配置提交到仓库时特别重要。3.2 src/gateway 目录结构速览配置写完之后得知道这些字段分别被哪个文件读取。src/gateway下的核心文件职责如下文件核心职责调试关注点server.ts创建 WS/HTTP 服务管理 Connection 对象连接状态、最后活跃时间server-startup.ts启动流程总调度按序初始化模块配置合并、数据库初始化server-channels.ts扫描并注册所有通道通道加载失败日志auth/挑战-应答式身份认证私钥配置、超时时间sessions/会话 CRUD 与 SQLite 持久化过期会话清理tools-invoke-http.ts工具调用 HTTP 接口转发请求参数校验server-cron.ts基于 node-cron 的定时任务时区、表达式control-ui.tsWeb 控制台CSP 严格外域资源被拦截hooks.ts生命周期钩子管理钩子执行顺序server-plugins.ts插件扫描与初始化插件加载警告这里有个容易忽略的点server.ts只负责创建服务真正的初始化逻辑全在server-startup.ts。所以当你看到“服务起来了但通道没注册”这类现象应该去翻server-startup.ts的调用顺序而不是盯着server.ts。3.3 WebSocket 与 JSON-RPC 的消息形态Gateway 的通信核心是 WebSocket HTTP 双协议内部消息采用 JSON-RPC 风格。核心指令有四个connect、req、res、event。第一帧必须是connect并且携带challengeSig完成挑战验证否则连接会被直接拒绝。这就是我开头踩的那个坑。一个合法的connect帧长这样{ type: connect, id: c-001, payload: { challengeSig: 由私钥对 challenge 签名得到, client: local-debug } }验证通过后服务端会回一个res之后你才能发req。req用来发起请求比如工具调用res是对应响应event是服务端主动推送比如定时任务触发、通道状态变化。理解这四个指令的时序是读懂src/gateway调度逻辑的关键。4. 启动与验证跑通一次 connect → req → res4.1 启动 Gateway配置就绪后用调试模式启动日志会更详细openclaw gateway --debug正常启动后控制台会输出[gateway] config merged: default user env [gateway] database initialized at ~/.openclaw/sessions.db [gateway] channels loaded: 3 ok, 0 failed [gateway] plugins loaded: 1 ok, 0 failed [gateway] cron jobs registered: 1 Gateway started on port 18789如果卡在某一步没有继续先看logs/gateway.log再对照第 5 节的排查表。4.2 用 Node 脚本完成一次往返下面这段脚本可以直接复制运行它完成connect → req → res的完整流程。把challengeSig换成你本地生成的签名即可本地调试时如果auth.privateKey为空部分版本会跳过签名校验具体以你拉到的源码为准// debug-gateway.mjs import WebSocket from ws; const ws new WebSocket(ws://127.0.0.1:18789); ws.on(open, () { console.log([client] socket opened); ws.send(JSON.stringify({ type: connect, id: c-001, payload: { challengeSig: local-debug-sig, client: debug-script } })); }); ws.on(message, (raw) { const msg JSON.parse(raw.toString()); console.log([client] recv:, msg.type, msg.id); if (msg.type res msg.id c-001) { // 认证通过发起一次工具调用请求 ws.send(JSON.stringify({ type: req, id: r-001, payload: { method: tools.invoke, params: { tool: weather, city: Shanghai } } })); } if (msg.type res msg.id r-001) { console.log([client] tool result:, JSON.stringify(msg.payload)); ws.close(); } }); ws.on(close, () console.log([client] closed)); ws.on(error, (err) console.error([client] error:, err.message));运行node debug-gateway.mjs成功时你会看到类似输出[client] socket opened [client] recv: res c-001 [client] recv: res r-001 [client] tool result: {ok:true,data:{city:Shanghai,temp:24}} [client] closed这一步跑通说明 WebSocket 长连接、挑战验证、JSON-RPC 分发、工具调用转发四条链路都是通的。如果connect之后没有收到res问题在认证如果收到了res但req没有响应问题在tools-invoke-http.ts的转发或 Agent 层。4.3 接入 AI 工具联调工具调用链路通了之后把 AI 通道接进来。Gateway 本身不直接调模型它把请求转发给 Agent 层Agent 层再通过ai.baseUrl访问统一 API。联调时我一般先用模型对话页面确认 Key 和通道是通的https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite如果后面要做长期编码或者 Agent 类的持续任务可以看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteClaude Code 相关的接入方式在https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite联调时的顺序建议是先用模型对话确认通道可用再回到 Gateway 发req这样能把“通道问题”和“Gateway 调度问题”分开定位。5. 本篇常见错排查调试 Gateway 时遇到的报错大部分集中在下面几类。我按现象、原因、处理方式整理成表方便你直接对照。现象可能原因处理方式启动即崩溃日志YAML parse error配置文件缩进用了 tab 或特殊字符未加引号用 2 空格缩进字符串加引号过一遍 YAML 校验EADDRINUSE: address already in use :::18789端口被占用lsof -i:18789找到进程后 kill或改gateway.portCannot find module sqlite-vec依赖未装好或 Node 版本过低确认 Node ≥ 22pnpm add sqlite-vec --force重装连接后 3 秒被断开挑战验证失败检查auth.privateKey本地调试可临时放宽校验通道加载失败但服务正常单个通道依赖缺失看logs/gateway.log中channel load failed禁用该通道即可req发出后无响应工具调用转发异常在tools-invoke-http.ts打印请求参数确认 Agent 层是否收到控制台页面样式丢失CSP 拦截了外域资源这是预期行为改用本地资源或内联样式定时任务不触发时区或 cron 表达式错误检查cron.timezone用标准 5 段表达式有一个通用经验值得单独说Gateway 的启动流程是“串行初始化 容错降级”。配置和数据库属于核心步骤失败会直接终止启动通道和插件属于非核心步骤失败只降级不崩溃。所以当你看到服务起来了但某个功能不可用先去日志里找对应的failed记录而不是怀疑整个启动流程。另外--debug模式会打印配置合并的每一层来源当你分不清某个字段到底生效了没有直接看这行日志最快[gateway] config merged: default user env它告诉你最终值来自哪一层。环境变量优先级最高所以如果你在 shell 里 export 过同名变量配置文件里的值会被覆盖这一点在排查“配置改了没生效”时特别有用。6. 继续深入从 Gateway 到 Agent 执行引擎把 Gateway 跑通之后你会发现它做的事情其实是“接收、认证、分发、转发”真正的处理逻辑在 Agent 执行引擎里。src/gateway的调度逻辑可以概括为三条线WebSocket 负责连接生命周期JSON-RPC 负责消息语义server-startup.ts负责模块初始化顺序。这三条线理清楚二次开发时你就知道该往哪里加钩子、往哪里注册通道。如果你在联调过程中需要确认模型通道是否正常可以回到模型对话页面做一次快速验证https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite需要管理多个 Key 或者查看调用记录时控制台和 API Keys 页面是入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite接口字段和请求格式的细节以接入文档为准https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite下一步建议你直接打开src/gateway/server-startup.ts对照本文第 3 节的启动顺序表把每个初始化步骤和日志输出对应起来。当你能看着日志说出“现在走到第几步、下一步该初始化什么”Gateway 的调度逻辑就算真正读懂了。