Gateway：OpenClaw 的入口层和调度中心——从 WebSocket 到 Session 的配置骨架

1. 先把 Gateway 的角色摆正它不是端口是入口层和调度中心OpenClaw 的 Gateway 到底是什么一句话说它是整个系统的入口层、会话调度中心和事件总线负责接住外部世界的输入再把 Agent 的输出送回正确的地方。适合谁看适合已经在本地把 OpenClaw 跑起来、准备接 CLI、Dashboard、消息平台或远程节点的开发者。如果你只把 Gateway 当成“一个转发请求的服务”那后面 Session 串号、事件丢失、队列打架的问题会一个接一个冒出来。我自己的理解路径是这样的CLI、Dashboard、API、消息平台、Node 这些入口全部指向 GatewayGateway 再往下对接 Session、Queue、Agent Runtime、Tools、Hooks最后把流式事件、最终回复、渠道发送、状态持久化分发回去。没有 GatewayOpenClaw 就退化成一个本地 CLI Agent有了 Gateway它才能同时面对多个入口和多个会话。所以这篇不讲空概念直接给你一份能跑的config.toml骨架把 WebSocket 连接、Session 管理、Agent Runtime 的协作链路串起来再配一套可复制的连通性验证动作。中间涉及模型调用通道的地方我用 TaoToken 的统一 Key 和 API 通道来接入这样你本地部署时不用为每个模型单独维护一套凭证。2. 前置准备TaoToken 统一 Key 与 API 通道在动config.toml之前先把模型侧的通道准备好。OpenClaw 的 Agent Runtime 最终要调用模型如果你本地同时接多个模型供应商凭证管理会很快变成一团乱麻。TaoToken 的思路是给你一个统一的 Key 和统一的 API 入口OpenClaw 侧只认一个 base_url 和一个 api_key切换模型时改模型名就行。你需要做两件事第一拿到 API Key。登录后进入控制台在 API Keys 页面创建一个新 Key复制保存。这个 Key 就是后面config.toml里api_key字段的值。第二确认 API 入口地址。OpenClaw 的模型调用走 OpenAI 兼容协议时base_url 填https://taotoken.net/api即可注意这个地址不带任何查询参数。如果你还没创建 Key可以直接走这个入口https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite想先验证模型通道是否通可以用模型对话页面发一条测试消息https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite长期跑编码类 Agent 任务的话Coding Plan 会更省心https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite注意API Key 属于敏感凭证不要写进会提交到 Git 的配置文件里。本地部署建议用环境变量注入或者把config.toml加入.gitignore。3. Gateway 的 config.toml 骨架WebSocket、Session、Agent Runtime 三段式下面这份骨架是我实测下来结构比较清晰的一版分成三段[gateway]管 WebSocket 监听和认证[session]管会话路由和队列[agent]管 Agent Runtime 和模型通道。字段名按你本地 OpenClaw 版本的实际 schema 微调结构逻辑是通用的。# config.toml —— OpenClaw Gateway 骨架 [gateway] # WebSocket 监听地址默认只绑本地回环避免暴露到公网 host 127.0.0.1 port 18789 # 连接认证shared secret token # 生产环境务必替换并从环境变量读取 auth_mode token auth_token ${OPENCLAW_GATEWAY_TOKEN} # 允许的入口角色控制面客户端 节点 allow_roles [control, node] # 健康检查与心跳 heartbeat_interval_ms 15000 health_path /health [session] # 会话路由按 channel account peer 映射到 session route_by [channel, account, peer] # 队列模式steer 进入当前 runfollowup 等当前 run 结束 queue_mode steer # 单 session 并发上限防止同一会话任务打架 max_concurrent_runs 1 # transcript 持久化 persist_transcript true transcript_dir ./data/transcripts [agent] # Agent Runtime 使用的模型通道 provider openai-compatible base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} model claude-sonnet-4-20250514 # 工具循环上限防止 Agent 无限调用工具 max_tool_iterations 12 # 流式事件回推 stream_events true几个关键点展开说。host绑127.0.0.1是默认安全姿势只有本机进程能连如果你要让局域网内的节点接入再改成0.0.0.0并配合认证。auth_mode token对应第一帧connect时携带的凭证Gateway 校验通过才建立会话。route_by决定 Session 的边界这三个字段任何一个映射错都会出现上下文串号。queue_mode是很多人忽略但很关键的一项。真实用户不会等 Agent 完美结束才说下一句他们会补充、打断、纠正。steer让新输入进入当前 run 的下一次模型调用followup则等当前 run 完成后再处理。选错模式长任务里 Agent 很容易乱套。[agent]段就是 Agent Runtime 的入口配置。base_url指向 TaoToken 的 API 通道api_key从环境变量注入model换成你要用的模型名。这样 Gateway 负责连接和路由Agent Runtime 负责 prompt、context、model、tool loop职责边界清晰。4. 可复制验证WebSocket 连通性与 Session 建立配置写完别急着接消息平台先用最小动作验证两件事WebSocket 能不能连上Session 能不能建立。4.1 验证 WebSocket 连通性用websocat或 Python 的websockets库都行。这里给一个 Python 脚本直接跑# check_gateway.py import asyncio import json import websockets GATEWAY_URL ws://127.0.0.1:18789 TOKEN 你的_gateway_token async def main(): async with websockets.connect(GATEWAY_URL) as ws: # 第一帧connect await ws.send(json.dumps({ type: connect, role: control, token: TOKEN })) resp await ws.recv() print(connect resp:, resp) # 发一个 req查询 gateway 状态 await ws.send(json.dumps({ type: req, id: req-1, method: gateway.health, params: {} })) while True: msg await ws.recv() data json.loads(msg) print(recv:, data) if data.get(id) req-1: break asyncio.run(main())跑通的话你会先看到connect的响应里面带 session 或连接标识然后gateway.health返回一个结构化状态包含 uptime、连接数、session 数之类的字段。如果卡在connect没响应八成是 token 不对或端口没监听。4.2 验证 Session 建立Session 的验证要发一个带路由信息的请求看 Gateway 是否把它映射到预期 session。下面这个请求模拟一条来自 CLI 的 agent 调用# check_session.py import asyncio import json import websockets async def main(): async with websockets.connect(ws://127.0.0.1:18789) as ws: await ws.send(json.dumps({ type: connect, role: control, token: 你的_gateway_token })) await ws.recv() await ws.send(json.dumps({ type: req, id: req-2, method: agent.run, params: { channel: cli, account: local, peer: dev-user, input: 用一句话说明 Gateway 的作用 } })) session_key None while True: msg await ws.recv() data json.loads(msg) if data.get(type) event: print(event:, data.get(event), data.get(payload, {}).get(text, )) if data.get(id) req-2: session_key data.get(result, {}).get(session_key) print(session_key:, session_key) break # 再发一条同 peer 的请求验证是否复用同一 session await ws.send(json.dumps({ type: req, id: req-3, method: agent.run, params: { channel: cli, account: local, peer: dev-user, input: 刚才那句话再短一点 } })) while True: msg await ws.recv() data json.loads(msg) if data.get(id) req-3: print(second session_key:, data.get(result, {}).get(session_key)) break asyncio.run(main())成功的结果是两次请求返回的session_key一致说明 Gateway 按channel account peer正确复用了会话同时你会收到agent.accepted、lifecycle.start、assistant.stream、lifecycle.end这类事件证明事件流是通的。如果两次session_key不同检查route_by配置和请求里的路由字段是否对齐。5. 本篇常见错排查5.1 connect 帧被拒认证失败现象是 WebSocket 连上了但第一帧connect返回 error或者直接断开。原因通常是auth_token不匹配或者auth_mode和客户端发送的字段名对不上。排查顺序先确认config.toml里的 token 和脚本里的一致再确认环境变量${OPENCLAW_GATEWAY_TOKEN}真的被注入到了进程环境里很多人改了.env但没重启 Gateway。5.2 Session 串号上下文跑到别的会话里现象是群聊的上下文串到私聊或者 CLI 的任务和消息平台的任务互相看不见。根因基本都在route_by。如果你只按peer路由不同 channel 下同名 peer 会撞到一起如果漏了account多账号场景会混。建议先用channel account peer三件套确认稳定后再按需精简。5.3 队列打架同一 session 并发多个 run现象是 Agent 回复错乱或者“继续上一个任务”时接的其实是另一个任务。检查max_concurrent_runs是否设成了大于 1以及queue_mode是否符合你的交互预期。长任务场景建议max_concurrent_runs 1配steer让补充输入进入当前 run 而不是另起一个。5.4 模型调用 401TaoToken 通道没配对现象是 Gateway 和 Session 都正常但 Agent Runtime 一调用模型就报认证错误。检查[agent]段的base_url是否为https://taotoken.net/api不带多余路径api_key是否从环境变量正确读取。如果 Key 是在控制台刚创建的确认没有多余空格。想快速排除是 Key 问题还是配置问题可以先用模型对话页面发一条消息验证 Key 本身可用。5.5 事件流收不到stream_events 没开或订阅缺失现象是最终回复能收到但中间的工具事件、流式文本收不到。检查stream_events true是否生效以及客户端在connect后是否显式订阅了事件类型。部分版本需要客户端发一个订阅请求才会推送assistant.stream和tool.event。6. 把 Gateway 接进你的开发链路Gateway 的配置骨架搭好之后下一步就是把它接进你日常的开发链路。如果你主要在做本地编码和 Agent 任务建议把模型通道固定到 Coding Plan减少凭证切换的摩擦https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite需要管理多个 Key 或查看调用情况时控制台在这里https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite接入过程中遇到协议或字段问题接入文档有更细的说明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite如果你用的是 Claude Code 这类工具链Anthropic 兼容通道的配置参考https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_code_anthropicutm_campaignrewrite最后留一个我踩过的坑改完config.toml一定要完整重启 Gateway 进程热加载在部分版本里对[gateway]段的监听地址和认证字段不生效你会以为配置没写对其实只是没重启。