nanobot源码解析：Gateway多渠道集成如何规避502错误

写 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 调用的统一出口。也就是说，你的消息先到 Gateway，Gateway 再去调 LLM 后端，拿到结果后原路返回。

这个设计在理念上没问题，但落到部署层面就有点重了。为了撑起这个 Gateway，openclaw 在 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是所有渠道共用的一条消息管道。你没看错，所有渠道的消息最终都进同一个 channel（Go 管道），这避免了给每个渠道单独开队列带来的内存和管理复杂度。

从职责边界看，Gateway 就三层：入站、治理、出站。入站管“收”，出站管“发”，中间夹着的 router、限流、鉴权、重试都属于治理层。下面逐个拆。

2.2 入站链路：适配器、规范化、投递

一条消息从外部渠道进来，路径是这样的：

1. 渠道适配器（比如 LarkAdapter）的轮询/长连接/Webhook 收到原始事件；
2. 适配器把平台特有的事件结构体转成统一的InboundMessage；
3. 适配器调用gateway.Submit(msg)把消息投入inbox管道；
4. 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.SendMessage，CLI 渠道则直接把文本打印到终端。

出站链路还有个隐藏细节：回复超时和失败重试。大部分渠道 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 如何扩展一个新渠道

因为接口足够薄，新增一个渠道的过程完全可以照抄已有适配器的骨架。按我的经验，三步就能搞定：

1. 实现Channel接口：Name()返回标识，Start里建立连接并订阅消息，收到消息后转成InboundMessage调用gateway.Submit，Send里把OutboundMessage转成平台消息格式发送。
2. 注册到 Gateway：在main.go或者setup.go的初始化流程里调gateway.Register(MyAdapter{...})。
3. 补配置解析：在配置结构体的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 飞书侧要做的三件事

要在飞书开放平台接入机器人，源码之外有几步平台操作绕不开：

1. 在飞书开放平台创建企业自建应用，拿到App ID和App Secret。
2. 给应用开启“机器人”能力，拿到机器人的名字和头像。
3. 配置事件订阅。选择“长连接”模式则无需暴露公网回调地址；选择“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 到 nanobot

5.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 讨论区里出现频率最高的几类报错，我把根因归成三类：

第二条热搜里还有个值得留意的信息：legacy exec approvals exist at /root/.openclaw/exec-approvals.json. run 'openclaw approvals'。这虽然跟 502 无关，但说明 openclaw 在权限审批和文件落盘上有一堆自有约定，迁移时这些历史文件都可能成为隐患。

5.3 nanobot 怎么从架构上规避 502

Nanobot 从设计上就把这类问题拆解掉了：

• 去掉了本地代理层：没有代理，就不存在代理切换失败、代理端口未监听这类 502 源头。请求直连配置的 LLMbase_url，日志里出错信息直接从上游透传回来，更直观。
• 渠道与 LLM 调用解耦：LLM 一次失败不会影响渠道连接。比如 LLM 服务重启的那几十秒里，飞书渠道的长连接依然健康，恢复后下一条消息就能正常处理，不存在“全链路雪崩”。
• 不注册系统服务：没有 schtasks、没有 service install，Windows 上的权限问题面大幅缩小。

当然，nanobot 不是银弹。如果你把base_url配成了一个根本不存在的地址，它照样会报连接错误，只是错误信息会比 502 可读得多。

5.4 如果 nanobot 也返回 502 怎么办

Nanobot 本身不充当 HTTP 代理，所以它自己几乎不会“产生” 502。但有一种情况你会看到 502：你把 nanobot 暴露在外网，前面挂了一层 Nginx/网关，当 nanobot 进程崩溃或过载时，Nginx 会向上游客户端返回 502。这时候排查顺序就是：

1. 确认 nanobot 进程是否还在，ps看进程，curl http://127.0.0.1:8080/healthz看健康检查；
2. 确认 Nginx 反代配置里的proxy_pass指向的端口是否与 nanobot 监听端口一致；
3. 看 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 发一个轻量请求，失败就立刻落日志并等待重试，不要直接进入事件循环。这个小改动能让渠道故障在启动阶段就暴露，而不是等到用户说话才发现机器人没挂上。我踩过一次之后就把这个探测加到了所有适配器里，效果立竿见影。