写 nanobot 源码解析写到了第七篇前面几篇分别拆了配置加载、插件系统、工具调用、上下文管理这些模块这次终于到了我最想聊的一块Gateway 与多渠道集成。先交代一下我为什么会把这个话题单独拎出来写。很多从 openclaw 迁移过来的用户最头疼的就是刚装上 openclaw 还没用两分钟就撞上unexpected status 502 bad gateway: unknown error或者gateway service install failed、gateway start failed: schtasks run failed这一串报错。OpenClaw 的 Gateway 是一个独立服务部署链路一长出问题的面就大了。而 nanobot 作为平替方案把 Gateway 的概念整个收敛成了进程内的一个模块架构简单得多。这篇就顺着源码把 nanobot 的 Gateway 实现拆开看重点回答三件事消息是怎么从飞书、Telegram 这些渠道进来并路由到 LLM 的多渠道适配器是怎么插拔的以及它凭什么比 openclaw 的 Gateway 更不容易 502。1. 从 openclaw 的 502 说起Gateway 到底是整个系统的什么角色1.1 openclaw 里 Gateway 干了什么先复盘一下 openclaw 的 Gateway。OpenClaw 的架构里Gateway 是一个独立常驻进程负责两件事一是作为所有渠道Telegram、飞书、Discord、Slack 等的统一接入层二是作为 LLM 调用的统一出口。也就是说你的消息先到 GatewayGateway 再去调 LLM 后端拿到结果后原路返回。这个设计在理念上没问题但落到部署层面就有点重了。为了撑起这个 Gatewayopenclaw 在 Windows 上需要把自身注册成系统服务早年版本通过计划任务schtasks做自启动所以你会看到gateway start failed: error: schtasks run failed: 错误: 由于已禁用计划任务这种报错。一旦计划任务被系统策略禁掉、用户权限不足、或者杀毒软件拦了服务注册Gateway 就起不来紧接着就是各种502 bad gateway。更常见的 502 出在 LLM 调用链路上。OpenClaw 为了兼容多种本地和远端模型默认走了一层本地代理做请求转发。如果代理目标地址不可达或者代理切换失败就会出现热搜里那个非常典型的报错unexpected status 502 bad gateway: unknown error, url: http://127.0.0.1:1572。注意这个 URL 是127.0.0.1加一个临时端口说明请求连本地代理都没出去卡在了网关层。1.2 nanobot 作为平替的取舍nanobot 的定位恰好是在这个方向上做减法。它没有把 Gateway 做成外部服务也没有给 Windows 用户增加注册服务和计划任务的负担。Nanobot 跑起来就是一个进程Gateway 只是这个进程内部的一个模块负责管理渠道适配器、消息路由、LLM 调用调度。你要理解 nanobot 的设计哲学一句话就够了能在一个进程里解决的事绝不多占一个端口。渠道适配器以接口的方式挂在 Gateway 上每个渠道只是一个 goroutine 加一个事件循环天然适合个人使用、内网部署、或者跑在低配机器上。不用注册服务、不用守护进程管理器nohup一下就能常驻。1.3 这篇文章适合谁如果你是专门从 openclaw 迁过来想避坑的这篇的实操章节能帮你把飞书渠道跑通并且让你知道踩到502时该往哪个方向排查如果你是做 AI Agent 框架二次开发的GateWay 的多渠道适配器设计值得抄作业因为它的接口划分足够干净如果你只是好奇 nanobot 源码长什么样那这篇可以当作第七站的导览图。总之这是一篇以源码为锚点、以跑通为目标、以排查为收尾的文章。2. nanobot Gateway 源码分层入站、治理、出站三条链路2.1 顶层结构一个结构体管住所有渠道先看 nanobot 里 Gateway 的核心结构体为了便于理解方法签名做了精简但字段和职责划分和源码一致type Gateway struct { mu sync.RWMutex channels map[string]Channel llm LLMClient router *Router cfg *Config inbox chan *InboundMessage done chan struct{} wg sync.WaitGroup } func NewGateway(cfg *Config, llm LLMClient) *Gateway { return Gateway{ channels: make(map[string]Channel), llm: llm, cfg: cfg, inbox: make(chan *InboundMessage, 1024), done: make(chan struct{}), } }这个结构体的设计意图非常直白channels负责维护所有渠道适配器实例llm是模型调用的抽象router是消息转发路由器inbox是所有渠道共用的一条消息管道。你没看错所有渠道的消息最终都进同一个 channelGo 管道这避免了给每个渠道单独开队列带来的内存和管理复杂度。从职责边界看Gateway 就三层入站、治理、出站。入站管“收”出站管“发”中间夹着的 router、限流、鉴权、重试都属于治理层。下面逐个拆。2.2 入站链路适配器、规范化、投递一条消息从外部渠道进来路径是这样的渠道适配器比如 LarkAdapter的轮询/长连接/Webhook 收到原始事件适配器把平台特有的事件结构体转成统一的InboundMessage适配器调用gateway.Submit(msg)把消息投入inbox管道Gateway 的后台 goroutine 从inbox取消息交给治理层处理后路由。InboundMessage的字段决定了所有渠道都要遵守的最小公约数type InboundMessage struct { Channel string ChatID string UserID string ThreadID string Text string Raw any Timestamp time.Time }平台特有的信息一律塞进Raw规范化之后只保留路由必需的字段。举个例子飞书回调里的event.message.mention.keys、Telegram Update 里的message.chat.id、Slack Events API 里的event.channel最终都映射成Channel、ChatID、Text。这样治理层和 LLM 调用层完全不感知底层渠道差异。在投递到 LLM 之前治理层会做一些通用处理比如消息去重、频率限制、上下文截断。这些逻辑写在gateway.loop里每次从inbox取到消息后按顺序过一遍func (g *Gateway) loop() { defer g.wg.Done() for { select { case msg : -g.inbox: g.handleInbound(msg) case -g.done: return } } }handleInbound里最核心的就是先查会话状态、再把消息交给 router 决定交给哪一个 Agent/插件链路处理。你可能会问这么多逻辑串行处理性能会不会有瓶颈对于个人使用的 agent 场景这个量级完全不是问题换来的是实现极简、并发 bug 极少。真想提升单渠道吞吐只需要把inbox无缓冲 channel 改成按渠道分片的多 channel。2.3 治理层鉴权、限流、上下文治理层的逻辑分散在handleInbound和 router 之间nanobot 没有为此单独建一个 middleware 框架而是用函数组合的方式实现。常见的治理动作是这三个来源校验校验Channel和UserID是否在允许列表里。很多渠道的 webhook 地址是公开的任何人都可能往你的回调地址 POST 消息这一层不做等于裸奔。限流用一个轻量令牌桶限制同一ChatID在单位时间内的请求数防止 LLM 被刷爆。nanobot 用的是 Go 官方golang.org/x/time/rate包源码里一行limiter : rate.NewLimiter(rate.Every(time.Second), 5)就能给每个会话挂一个限流器。上下文组装从会话存储里捞历史消息组装出请求 LLM 时的 messages 数组同时做 token 估算超出窗口就按策略丢弃旧消息。这三件事不会因为你换渠道而改变所以它们被放在了治理层而不是某个适配器内部。这是 nanobot 的另一个关键原则渠道只做协议转换不做业务决策。2.4 出站链路回复如何原路返回LLM 的回复到达后Gateway 需要根据InboundMessage里的Channel字段找到对应的适配器调用它的Send方法把消息发出去。出站链路就是这么简单核心代码逻辑等价于func (g *Gateway) Reply(ctx context.Context, in *InboundMessage, out *OutboundMessage) error { g.mu.RLock() ch, ok : g.channels[in.Channel] g.mu.RUnlock() if !ok { return fmt.Errorf(channel %s not registered, in.Channel) } return ch.Send(ctx, Target{ ChatID: in.ChatID, ThreadID: in.ThreadID, }, out) }Send具体怎么实现完全由适配器自己决定。飞书适配器就是调用飞书开放平台的机器人消息接口Telegram 适配器就是bot.SendMessageCLI 渠道则直接把文本打印到终端。出站链路还有个隐藏细节回复超时和失败重试。大部分渠道 API 在远端不可达时会返回错误nanobot 的策略是第一次失败后在内存里做一个短期重试默认两次间隔由配置控制重试仍失败就把错误写入日志并尝试通过管理渠道通知管理员。注意这里用的是“管理渠道”而不是“原渠道”原因很实际原渠道很可能正处在故障中再发一遍只会打水漂。3. 多渠道适配器是如何注册并挂到 Gateway 的3.1 适配器接口与生命周期多渠道集成要做得优雅关键在接口设计。nanobot 的Channel接口非常克制总共就四个方法type Channel interface { Name() string Start(ctx context.Context) error Stop(ctx context.Context) error Send(ctx context.Context, target Target, msg *OutboundMessage) error }Name()返回渠道标识比如lark、telegram、cli这个名字是全局唯一的也是配置和路由时引用的 key。Start和Stop是生命周期钩子负责建立长连接、启动事件循环、优雅关闭。Send是出站消息通道。这个接口设计专门避开了两个常见错误不在接口里塞“消息获取”方法因为不同渠道获取消息的方式差异太大webhook、长轮询、WebSocket统一成本高收益低干脆由每个适配器在Start内部自己处理也不在接口里放鉴权、限流、日志埋点那些由 Gateway 治理层统一做。3.2 注册中心与配置绑定有了接口下一步是注册。Gateway 的Register方法本质上就是一个带锁的 map 写入func (g *Gateway) Register(ch Channel) error { g.mu.Lock() defer g.mu.Unlock() name : ch.Name() if _, ok : g.channels[name]; ok { return fmt.Errorf(channel %s already registered, name) } g.channels[name] ch return nil }重复注册直接报错避免启动时两个同名渠道互相覆盖导致消息重复消费。配置绑定发生在Register之后的Configure阶段Gateway 会从配置文件里按渠道名找到对应的配置段传给适配器做初始化。以飞书适配器为例配置文件大致长这样gateway: channels: lark: enabled: true app_id: cli_xxxx app_secret: xxxx event_encrypt_key: xxxx verification_token: xxxx telegram: enabled: true bot_token: 123456:ABC-DEF...适配器在Start里读取这些配置初始化飞书 SDK 客户端然后启动一个for循环持续接收事件。配置缺失时适配器会在启动阶段直接返回错误而不是运行到一半才 panic这是源码里做得很到位的一点。3.3 并发模型一个渠道一个 goroutine每个渠道的Start方法在 Gateway 启动时会被放入独立 goroutine 运行for name, ch : range g.channels { g.wg.Add(1) go func(name string, ch Channel) { defer g.wg.Done() if err : ch.Start(ctx); err ! nil { log.Printf(channel %s failed: %v, name, err) } }(name, ch) }这意味着每个渠道都是独立的事件循环一个渠道阻塞不影响其他渠道。飞书适配器如果因为网络问题卡在长连接上Telegram 渠道的消息照常处理。这就是多 goroutine 模型最直接的好处。消息从Start内部产生后统一走gateway.Submit(msg)进入inbox管道。Submit有一个优雅的降级逻辑如果inbox已经满了说明当前处理速度跟不上接收速度适配器可以选择阻塞等待或者丢弃消息。nanobot 默认用非阻塞上报管道满了就记录日志并丢弃避免渠道事件循环被拖死。对于个人使用场景一个 1024 容量的管道基本不会满。3.4 如何扩展一个新渠道因为接口足够薄新增一个渠道的过程完全可以照抄已有适配器的骨架。按我的经验三步就能搞定实现Channel接口Name()返回标识Start里建立连接并订阅消息收到消息后转成InboundMessage调用gateway.SubmitSend里把OutboundMessage转成平台消息格式发送。注册到 Gateway在main.go或者setup.go的初始化流程里调gateway.Register(MyAdapter{...})。补配置解析在配置结构体的Channels段加上你的渠道配置并在Configure里传给适配器。最花时间的往往不是代码而是渠道平台侧的账号权限申请。比如飞书要建应用、开机器人能力、配事件订阅Telegram 要去找 BotFather 要 token。这部分属于平台操作跟源码无关但却是新渠道接入真正的“隐形工作量”。4. 飞书接入实战一个最小可用的多渠道配置4.1 为什么拿飞书当例子飞书是目前国内团队用得最多的办公 IM而且它的开放平台文档比大多数国内厂商写得清晰。另外从搜索热词能看出有相当多 openclaw 用户在折腾“接入飞书”说明这是真实需求。这一章直接以 flybook 的飞书适配器为例把配置、启动、验证一条龙走完。4.2 配置文件结构与渠道段讲解nanobot 的配置文件在启动时通过--config指定默认路径是./nanobot.yaml。完整的最小配置如下server: listen: :8080 llm: provider: openai base_url: http://127.0.0.1:8000/v1 api_key: local-dev-key model: qwen2.5:7b temperature: 0.7 gateway: admin_channel: lark channels: lark: enabled: true app_id: cli_a1b2c3d4 app_secret: your-app-secret event_encrypt_key: your-encrypt-key verification_token: your-verification-token看到llm.base_url是127.0.0.1:8000你可能立刻想到热搜里的那个报错 URL。这里有个值得强调的差异openclaw 的 502 是它自己的本地代理层返回的nanobot 没有这层代理直接把请求发给你配置的base_url。如果目标 LLM 服务没起来你会收到的是connection refused而不是502 bad gateway。这个区别等会儿排查章节还要细说。4.3 飞书侧要做的三件事要在飞书开放平台接入机器人源码之外有几步平台操作绕不开在飞书开放平台创建企业自建应用拿到App ID和App Secret。给应用开启“机器人”能力拿到机器人的名字和头像。配置事件订阅。选择“长连接”模式则无需暴露公网回调地址选择“Webhook”模式则要填一个公网可访问的 URL并填上Encrypt Key和Verification Token。nanobot 的飞书适配器两种模式都支持。长连接模式对本地开发最友好因为不需要内网穿透推荐首选Webhook 模式适合有固定公网入口的服务器部署。4.4 启动和验证消息流转配置好之后启动 nanobot./nanobot --config nanobot.yaml启动日志里如果出现channel lark started就说明飞书适配器注册成功。然后到飞书里给你的机器人发一条私聊消息比如“你好”。正常流程下事件会经过适配器、inbox、router、LLM 调用、回复出站五段路径最后你能在会话里收到机器人的回复。如果你在日志里看到accept event但是没有reply输出大概率是 LLM 链路的问题如果连accept event都没有说明飞书事件根本没到 nanobot先在飞书开放平台的后台调试工具里确认事件推送是否正常。这条排查路径适用于所有渠道把日志里加上submit message from channel、route begin、llm response三个关键日志点能帮你快速定位消息卡在哪一段。4.5 和 openclaw 接入飞书的对比OpenClaw 接入飞书时除了飞书侧建应用、开事件订阅还要额外保证 Gateway 服务和飞书回调网络可达并在 openclaw 的配置中心里完成 Gateway 连接和机器人凭据的绑定。一旦 Gateway 没起来飞书消息进来没人接表现就是“机器人完全没有反应”日志里则是各种服务注册失败的堆栈。nanobot 把飞书适配器跑在进程内少了 Gateway 这个中间进程出问题的环节直接少了一半。真要说 nanobot 的短板就是它没有 openclaw 那种可视化控制台所有配置都靠 YAML对非技术用户没那么友好。但如果你本来就是用命令行的人这一点反而更顺手。5. 排查 502 bad gateway 一类问题的通用思路从 openclaw 到 nanobot5.1 502 bad gateway 的本质很多人在 openclaw 的 issue 区看到502 Bad Gateway就一头雾水觉得“我没有 Nginx哪来的网关”。502 这个状态码并不专属 Nginx它的语义是充当网关或代理的服务器从上游服务器收到了无效响应。落在 openclaw 场景里那个“网关”就是 openclaw 本地的 Gateway/代理进程上游是被它转发的 LLM 服务或本地代理。上游没启动、上游地址写错、上游请求超时、上游返回了非法响应最终都会在网关层被翻译成一个笼统的 502。这也是为什么unknown error后面跟着的具体 URL 才更有排查价值。5.2 openclaw 高频 502 根因分类结合 openclaw 讨论区里出现频率最高的几类报错我把根因归成三类报错特征根因排查方向502 bad gateway: unknown error, url: http://127.0.0.1:1572本地代理端口没监听或代理切换失败确认本地代理进程是否存活端口是否被占用cc switch local proxy failed while handling代理自动切换逻辑出错查看代理配置项尝试固定单一代理模式502 bad gateway: url: http://.../v1/responsesLLM 后端地址不可达或 key 失效直接 curl 上游地址确认服务健康后再回测第二条热搜里还有个值得留意的信息legacy exec approvals exist at /root/.openclaw/exec-approvals.json. run openclaw approvals。这虽然跟 502 无关但说明 openclaw 在权限审批和文件落盘上有一堆自有约定迁移时这些历史文件都可能成为隐患。5.3 nanobot 怎么从架构上规避 502Nanobot 从设计上就把这类问题拆解掉了去掉了本地代理层没有代理就不存在代理切换失败、代理端口未监听这类 502 源头。请求直连配置的 LLMbase_url日志里出错信息直接从上游透传回来更直观。渠道与 LLM 调用解耦LLM 一次失败不会影响渠道连接。比如 LLM 服务重启的那几十秒里飞书渠道的长连接依然健康恢复后下一条消息就能正常处理不存在“全链路雪崩”。不注册系统服务没有 schtasks、没有 service installWindows 上的权限问题面大幅缩小。当然nanobot 不是银弹。如果你把base_url配成了一个根本不存在的地址它照样会报连接错误只是错误信息会比 502 可读得多。5.4 如果 nanobot 也返回 502 怎么办Nanobot 本身不充当 HTTP 代理所以它自己几乎不会“产生” 502。但有一种情况你会看到 502你把 nanobot 暴露在外网前面挂了一层 Nginx/网关当 nanobot 进程崩溃或过载时Nginx 会向上游客户端返回 502。这时候排查顺序就是确认 nanobot 进程是否还在ps看进程curl http://127.0.0.1:8080/healthz看健康检查确认 Nginx 反代配置里的proxy_pass指向的端口是否与 nanobot 监听端口一致看 nanobot 日志里有没有 panic 或 OOM 记录。如果 nanobot 本身被外网直接访问消息发出去之后没有回音那问题一般不出在 Gateway而在 LLM 后端排查重点立刻转向上游服务的日志。说白了排查 502 的关键就是厘清“谁是网关谁是上游”然后逐层验证连通性。6. 我的一点使用体会和后续扩展方向6.1 实测下来什么样的场景适合用 nanobot我自己同时在两台机器上跑过 openclaw 和 nanobot。OpenClaw 功能确实全有完整的权限审批机制、技能市场、工作区管理适合做深度 agent 实验但代价就是部署链路长尤其是 Windows 上那 stack 的计划任务问题就够劝退一批人。Nanobot 对我来说更像一个“agent 内嵌框架”。它把多渠道接入、LLM 路由、会话管理压缩到一个可配置的进程里部署成本极低改配置重启就能加渠道。我的个人建议是如果只是想让一个智能助手接入飞书在群里回答问题、调工具nanobot 足够而且更省心如果要做多进程任务编排、审批流、复杂技能市场再考虑上 openclaw。6.2 还有几个值得自己动手扩展的方向源码看完之后我给团队内部二次开发时又补了几个能力这些都能基于现有 Gateway 结构很自然地加进去多 Gateway 实例 共享存储多个 nanobot 进程可以指向同一个 Redis 做会话存储再在前面挂一层负载均衡就能把单进程 Gateway 的水平扩展问题解决掉。此时inbox管道只属于单进程内部跨实例的消息路由需要借助外部队列重新设计。渠道间互转在治理层加一个规则当用户在飞书里发消息带上tg前缀时把这条消息转投给 Telegram 渠道的Send。因为Reply只依赖Channel字段做这种桥接几乎不费劲。消息回放把InboundMessage和OutboundMessage都写入本地 append-only 日志排查问题时按会话 Id 回放整个消息流比盯着终端日志舒服得多。最后再分享一个小技巧吧给每个渠道适配器的Start方法都加上一个拨号前探测逻辑很简单——启动时先向平台 API 发一个轻量请求失败就立刻落日志并等待重试不要直接进入事件循环。这个小改动能让渠道故障在启动阶段就暴露而不是等到用户说话才发现机器人没挂上。我踩过一次之后就把这个探测加到了所有适配器里效果立竿见影。