吃龙虾🦞咯！万字拆解OpenClaw的架构与设计

这是我的专栏《春哥的Agent通关秘籍》系列文章的第18篇，希望系统性跟着我一起学AI-Agent编码的同学可以关注一下我的这个专栏。

还在跟风养龙虾🦞？直接扒开龙虾的源码外衣，进行一个学习拆解！

为什么说龙虾🦞OpenClaw的通信架构值得深入学习？

OpenClaw最近在全世界范围内的火爆程度不用多言，其在GitHub上的星星数量，已经超越了 和，登榜全球榜首！牛的！

腾子前段时间办了个免费装机龙虾，现场那叫一个火爆异常。

OpenClaw的爆火绝对和它的多终端多IM适配能力，自我进化能力分不开。未来这种模式也一定会是各种助手类Agent的标配！

无论是大家办公常用的 钉钉/飞书/机器人，抑或是国外比较常用的 Microsoft Teams、Mattermost、Twitter/X 等，都能便捷接入。

本文，将通过分析OpenClaw的架构，聚焦其支持的终端接入、分层策略、主流IM连接方式的利弊，以及分层细节和接口适配，探讨当前IM通信技术的设计思路。

OpenClaw的设计理念是”Any OS. Any Platform.”，强调跨设备无缝接入AI助手。

它通过伴侣应用（Companion Apps）和节点（Nodes）机制，实现对多种终端的便捷支持。

这些终端接入方式主要分为设备节点和IM通道集成两种，前者聚焦硬件设备，后者聚焦通信平台。

IM工具接入支持：

• 核心通道（8个）：项目内置了对主流高频 IM 的支持，按照加载顺序包括 Telegram、WhatsApp、Discord、IRC、Google Chat、Slack、Signal 以及 iMessage。
• 扩展通道（50+）：通过其灵活的插件系统，OpenClaw 延伸到了更多垂直细分领域。
• 企业通讯：支持 Microsoft Teams、Mattermost 以及国内常用的飞书（Feishu/Lark）等。
• 社交与去中心化网络：涵盖了 Twitter/X、Twitch，以及 Matrix、Nostr 等去中心化协议。
• 其他协议：甚至支持语音（Voice Call）以及 BlueBubbles 等特定场景通道。

  这些通道的接入强调插件化，用户只需在配置文件中启用，如YAML格式的channels.telegram.enabled: true，即可实现终端便捷交互。

  项目文档强调，接入后支持媒体管道、转录和多代理路由，提升用户体验。

为了抹平几十种 IM 平台的 API 差异，OpenClaw 采用了一种经典的、高内聚低耦合的三层架构设计：

• Gateway（网关层）：作为整个系统的控制大脑。它负责维护 WebSocket 控制平面，进行全局的会话管理（Session），并决定消息如何被路由（Routing）到正确的目的地。
• Channel Core（通道核心层）：起到承上启下的中间件作用。它维护着通道注册表（Registry），管理所有通道的全局配置（Channel Config），并统一处理消息的会话、线程（Threading）以及输入状态（Typing）等通用逻辑。
• Channel Plugins（通道插件层）：这里是”脏活累活”的执行地。无论是前面提到的 8 个核心通道，还是 50 多个扩展通道，都以独立插件的形式存在于这一层，负责与各个 IM 厂商的服务器进行底层网络交互。
  

不同 IM 厂商出于安全、性能或历史包袱的考虑，提供了截然不同的 API 接入方式。

OpenClaw 将这些连接模式主要抽象为三大类：WebSocket 和 Webhook，外加针对特定工具的 CLI/本地直连模式。

这种模式下，你的本地服务器（客户端）主动向 IM 厂商的服务器发起长连接。

代表应用：飞书、钉钉、、 Discord、Slack (Socket Mode)、WhatsApp、Telegram（fallback模式）

• 优势：
  • 无需公网 IP：非常适合个人开发者在本地电脑或内网 NAS 上部署测试。
  • 配置简单：由于是主动连接，通常只需要提供 App ID 和 Secret 即可启动，也更容易通过设置 https_proxy 来穿透网络限制。
• 劣势：客户端需要维持长连接心跳，对本地网络稳定性有一定要求。

这种模式下，当用户在 IM 发送消息时，IM 厂商的服务器会主动发起一个 HTTP POST 请求到你配置的服务器地址。

代表通道：Google Chat、Telegram (Webhook)、飞书 (Webhook)、钉钉机器人（Webhook）、Microsoft Teams。

• 优势：
  • 节省资源：本地服务器不需要维持长连接，只有在有消息时才会被唤醒处理。
  • 官方支持度高：几乎所有现代企业级 IM 都首推这种方式，因为它更容易实现厂商侧的负载均衡。
• 劣势：
  • 强依赖公网 IP：你的服务器必须对外暴露端口，本地开发时必须借助 ngrok 或 frp 等内网穿透工具。
  • 安全要求高：需要额外配置验证 Token (verificationToken)，且系统需要处理速率限制、请求体大小限制以及超时保护，以防止恶意攻击。

代表通道：Signal (依赖 signal-cli)、iMessage (依赖 imsg)、IRC (TCP 直连)。

• 特点：这类通道通常不提供标准的开放 HTTP/WS API，必须通过劫持本地客户端工具或使用极其底层的套接字协议来实现。它们同样不需要公网 IP，但环境配置极为苛刻（例如 iMessage 必须运行在 macOS 上）。

主要接口定义文件：

兼容和适配的核心是抽象。

ChannelPlugin 是 OpenClaw 通道插件的统一契约，定义了所有 IM 通道必须实现的能力。

其各接口组作用如下：

稍微有点经验的研发都能很快理解它的意义，因为其核心模块可以不面向任何具体的IM工具撰写代码，而是只面向通道接口撰写代码。

这样，无论上层使用哪种IM通道，对于核心层而言都是兼容的。

假如市面上新出了一款IM工具叫”春哥通”,那么只要实现插件规范，形成插件，就可以无痛接入。

示例：发送消息的调用流程

在实现接口层，未实现的能力即被视为不支持，但有部分能力必须实现：

插件注册过程中提供了哪些能力？

重点关注其注册逻辑，文件地址：:

OpenClaw虽好，但着实太重，而且用的是Javascript，而且我们学习过程中最重要的就是把它转换成我们自己的实践。

如果我们尝试用python来实现一个名叫 ，我们就可以参考OpenClaw简单地做如下架构：

那么，首当其冲的就是 Gateway 网关的设计。

Gateway 是 OpenClaw 的核心服务中枢，是整个系统的控制平面。

啥是”控制平面”？

简单来说：Gateway = 大管家。

它帮你管理所有IM渠道（飞书、钉钉、Slack、Telegram…），你只需要跟AI聊天，它负责把消息转来转去。

类似 MVC 模式中的 Controller（控制）和 Model/View（数据）。

查看源码文件如下： 可以看到 的启动过程如下：

可以看到，网关的核心在于：

• 拿到插件
• 拿到通道管理权限
• 拿到运行时状态管理能力
• 拿捏HttpServer服务

  并最终完成居中协调。

消息路由 是将收到的 IM 消息 分配到正确的会话 (Session) 的过程。

核心问题：

核心职责：

• 确定Agent: 消息应该交给哪个Agent处理
• 确定Session: 消息属于那个会话
• 上下文隔离：不同用户/不同群组的上下文是否应该隔离

我们研究OpenClaw的代码，会发现它的一个会话的键是这样构成的：

在文件 里可以看到如下代码：

这里其实是定义了OpenClaw支持的几种路由策略：

• main
  • 含义：共享，所有用户的会话混到一起
  • 特点：所有用户的对话历史混在一起
  • 适用场景：一个简单的客服机器人，不需要区分用户
• per-peer
  • 含义： 每个用户独立会话
  • 
  • 特点：每个用户有独立的对话历史
  • 适用场景：需要记住用户上下文，如个人助手
• per-channel-peer
  • 含义：每个用户的不同通道互相独立
  • 特点：同一用户在不同通道，会话分开
  • 适用场景：多租户/多账户场景
• per-account-channel-peer
  • 含义：使用 账户+通道+用户 隔离
  • 特点：完全隔离，每个账户独立
  • 适用场景：多租户/多账户场景

Agent是龙虾的核心中的核心，当我们研读其源码后会发现，龙虾实际存在三种内置的核心运行模式， 分别是：

• 模式 1：Embedded PI (内嵌代理)
• 模式 2：CLI Agent (本地 Claude CLI)
• 模式 3：ACP (Agent Control Plane) — 远程代理

原理：OpenClaw 直接调用 LLM API（如 OpenAI、Anthropic）

特点：

• 不需要额外依赖
• 完全受 OpenClaw 控制
• 支持流式输出
• 需要配置 API Key

原理：调用本地安装的 Claude CLI 工具

特点：

• 使用本地 Claude CLI
• 复用本地登录状态
• 不消耗 API 配额(而是用套餐余量)
• 需要本地安装 CLI

原理：通过 ACP 控制平面调用远程 Agent 服务

特点：

• 远程部署的 Agent
• 适合大规模并发
• 需要 ACP 服务端点

查看源码文件：

而 ACP 模式是独立触发的（在 Gateway 层面），用于特定场景。

OpenClaw的一大亮点就在于其Skills的管理和运用，那么这部分它是如何设计的呢？

OpenClaw的Skills 来自三个地方：

openclaw 龙虾

每个 Skill 需要一个 SKILL.md 文件：

上面是该Skill的元数据，会长期暴露给会话，以便在需要的时候调用。下面是按需加载的实际能力介绍。

不是一次加载所有 skill，而是通过 Eligibility 检查 决定是否加载：

还可以通过配置手动指定只加载哪些 skill：

或者排除某些：

Skills 快照会缓存到 Session 中，避免每次都重新加载:

SkillsSnapshot 的结构如下：

本质上，它是一个合并后的字符串，包含了所有符合条件的 SKILL.md 内容。

不过，SkillSnapshot 针对数量和长度做了一些限制，如下：

首先，skills的Description 会被注入到 Agent 的 System Prompt 中：

并配合提示词，把所有需要备选的skills构成一个大的Prompt：

当Agent通过 或者 ，在上面这段提示词的协助下，发现自己需要调用某个Skill时，它会使用 的能力调用 工具：

1. 先给 Agent 看所有 skill 的索引（name + description）
2. Agent 根据用户请求自主决策需要哪个 skill
3. Agent 主动调用 read 工具读取完整的 SKILL.md
4. 执行 skill 中的命令，或暴露skill中完成的执行顺序

不是系统主动加载，而是 Agent 主动读取！

为什么要专门花时间解析OpenClaw的结构设计？

因为它已经事实上成为了助手类Agent接入的最新标准和要求，通过学习构建和搭建，对于未来的实践Agent能提升较大的体验。

接下来，我会按照龙虾的思路，用python做一些小demo，分别实现它的核心模块，从而达到掌握吸收称为个人技能的效果！

敬请期待！