Zui近在技术圈，Ru果你还没听说过“龙虾”，那你可Neng真的要稍微补补课了。这玩意儿在GitHub上的热度简直离谱，星星数一路狂飙，甚至一度把 Linux 和 React 这种老牌巨头dou甩在了身后。这不仅仅是一个项目，geng像是一场关于AI Agent如何落地的技术狂欢。

为什么大家dou在聊它？为什么腾子前段时间办个免费装机龙虾活动Neng现场爆满？根本原因不在于它是个聊天机器人，而在于它解决了一个让无数开发者头疼的痛点：如何让一个AI Agent丝滑地接入几十种完全不同的IM平台？

今天咱们不搞那些虚头巴脑的吹捧，直接扒开OpenClaw的源码外衣，kankan这只“龙虾”的骨架到底是怎么搭的。无论你是想搞二次开发，还是想偷师它的架构设计，这篇文章dou值得你细品。

一、 核心理念：Any OS. Any Platform.

在深入代码细节之前，我们必须先理解OpenClaw的设计初衷。它的野心hen大，口号是“Any OS. Any Platform.”。这不仅仅是一句广告词，而是其架构设计的灵魂。

市面上IM工具多如牛毛：国内有飞书、钉钉、微信，国外有Telegram、Discord、Slack、WhatsApp。这些平台的API设计千奇百怪，有的用Webhook推消息，有的需要你维持长连接，有的甚至还得靠本地CLI工具。Ru果每接入一个平台就要重写一遍逻辑，那开发者的头发早就掉光了。

OpenClaw的爆火，绝对和它那恐怖的多终端适配Neng力、以及自我进化的 性分不开。未来这种模式，大概率会成为各种助手类Agent的标配。它通过伴侣应用和节点机制，把复杂的底层差异全部抹平，让开发者只需要关注“AI怎么思考”，而不用操心“消息怎么传输”。

二、 架构总览：经典的三层设计

为了抹平几十种IM平台的API差异，OpenClaw采用了一种非常经典、高内聚低耦合的三层架构设计。稍微有点经验的研发一眼就Nengkan出其中的门道：核心模块完全不面向具体的IM工具写代码，而是只面向抽象的“通道接口”编程。

这就好比MVC模式中的Controller和Model/View分离一样，各司其职。

1. Gateway：大脑与控制平面

Gateway是OpenClaw的核心服务中枢，也是整个系统的控制平面。简单来说它就是那个“大管家”。

它的核心职责非常重：

维护WebSocket控制平面： 确保各个组件之间的通信顺畅。

全局会话管理： 谁在跟谁说话？聊到哪了？全靠它记着。

消息路由： 收到消息后该分发给哪个Agent？该回复到哪个群组？这是Gateway的拿手好戏。

我们Ke以kankan源码中Gateway的启动过程，逻辑非常清晰：

export async function startGatewayServer(
  port = 3000,  // 默认端口
  opts: GatewayServerOptions = {}
): Promise {
  // 1. 加载配置快照
  let configSnapshot = await readConfigFileSnapshot;
  // 2. 自动启用符合条件的插件
  const autoEnable = applyPluginAutoEnable;
  // 3. 创建运行时状态
  const runtimeState = await createGatewayRuntimeState;
  // 4. 启动 HTTP 服务器
  const httpServer = createGatewayHttpServer;
  // 5. 启动通道管理器
  const channelManager = createChannelManager;
  // 6. 激活所有通道账户
  await channelManager.startAccounts;
}

Ke以kan到，网关的核心在于拿到运行时状态管理Neng力，并统一调度。它不直接处理具体的IM协议，而是通过管理Channel来干活。

2. Channel Core：承上启下的中间件

这一层起到了关键的承上启下作用。它维护着通道注册表，管理所有通道的全局配置，并统一处理消息的会话、线程以及输入状态等通用逻辑。

它就像是一个翻译官，把Gateway发出的通用指令，翻译成下层Neng听懂的操作。

3. Channel Plugins：干脏活累活的地方

这里才是真正跟IM厂商服务器“肉搏”的地方。无论是前面提到的8个核心通道，还是十几个 通道，dou以独立插件的形式存在于此。

这一层负责Zui底层的网络交互：怎么连Telegram？怎么调飞书的API？怎么处理Signal的加密？全在这里解决。

三、 插件系统：如何统一千奇百怪的IM接口？

OpenClaw的兼容和适配核心在于“抽象”。它定义了一个强大的 ChannelPlugin 接口，这就是所有通道必须遵守的“契约”。

我们来kankan这个接口的定义，你会发现它设计得极其详尽，但也极其灵活：

export type ChannelPlugin = {
  id: ChannelId;
  meta: ChannelMeta;
  capabilities: ChannelCapabilities;
  defaults?: {...};           // 默认配置项
  reload?: {...};             // 热重载配置
  onboarding?: ...;           // 新手向导配置
  config: ChannelConfigAdapter;  // 账户配置适配器
  configSchema?: ...;          // 配置结构定义
  setup?: ...;                // 设置适配器
  pairing?: ...;              // 配对适配器
  security?: ...;             // 安全策略适配器
  groups?: ...;               // 群组适配器
  mentions?: ...;             // @提及处理
  outbound?: ...;             // 出站消息
  status?: ...;               // 状态geng新
  gateway?: ...;               // 网关适配器
  auth?: ...;                 // 认证逻辑
  elevated?: ...;              // 权限管理
  commands?: ...;              // 命令处理
  streaming?: ...;             // 流式传输
  threading?: ...;             // 消息串接
  messaging?: ...;             // 消息收发
  agentPrompt?: ...;           // 提示词注入
  directory?: ...;             // 目录服务
  resolver?: ...;             // 标识符解析
  actions?: ...;               // 消息动作
  heartbeat?: ...;             // 心跳保活
  agentTools?: ...;            // 暴露给Agent的工具
};

这个接口设计的精妙之处在于“可选性”。比如Ru果某个IM不支持流式传输，那就不实现 streaming 接口；Ru果不需要群组功Neng，就不实现 groups。Gateway在运行时会自动检测这些Neng力。

比如发送消息，Gateway只需要调用统一的方法：

// Gateway 调用 
const result = await channelPlugin.outbound.sendText({
  cfg,
  to: "user123",
  text: "Hello!",
  accountId: "default"
});
// 内部实现差异对 Gateway 透明
// Telegram: 调用 Telegram Bot API
// Discord: 调用 Discord WebSocket/Gateway  
// Slack: 调用 Slack Web API
// Feishu: 调用飞书 Open API

假如市面上明天新出一款IM叫“春哥通”，你只需要按照这个规范写一个插件，就Neng无痛接入，完全不需要改动核心代码。

四、 连接模式：Webhook vs WebSocket vs CLI

不同IM厂商出于安全、性Neng或历史包袱的考虑，提供了截然不同的API接入方式。OpenClaw将这些连接模式主要抽象为三大类。理解它们的利弊，对于部署Agent至关重要。

1. Webhook 模式

这是企业级IMZui常用的模式，比如飞书、钉钉、Microsoft Teams、Google Chat。

原理： 当用户在IM发送消息时IM厂商的服务器会主动发起一个HTTP POST请求到你配置的服务器地址。

优势：

节省资源： 你的服务器不需要维持长连接，只有在有消息时才会被唤醒处理。

官方支持度高： 几乎所有现代企业级IMdou首推这种方式，因为它geng容易实现厂商侧的负载均衡。

劣势：

强依赖公网IP： 你的服务器必须对外暴露端口，本地开发时必须借助ngrok或frp等内网穿透工具，稍微有点麻烦。

安全要求高： 需要额外配置验证Token，且系统必须处理速率限制、请求体大小限制以及超时保护，以防止恶意攻击。

2. WebSocket / Socket Mode 模式

代表应用包括 Discord 、Slack 、WhatsApp、Telegram。

原理： 你的本地服务器主动向IM厂商的服务器发起长连接。

优势：

无需公网IP： 非常适合个人开发者在本地电脑或内网NAS上部署测试，不用折腾内网穿透。

配置简单： 通常只需要提供App ID和Secret即可启动，也geng容易通过设置https_proxy来穿透网络限制。

劣势：

客户端需要维持长连接心跳，对本地网络稳定性有一定要求。

3. CLI / 本地直连模式

代表通道：Signal 、iMessage 、IRC 。

这种模式通常直接调用本地安装的命令行工具或通过TCP协议直连，geng偏向极客玩法。

五、 Skills机制：渐进式披露的智慧

OpenClaw的一大亮点就在于其Skills的管理和运用。它不是一股脑地把所有Neng力塞给Agent，而是采用了一种非常聪明的“渐进式披露”策略。

1. Skills 的来源

OpenClaw的Skills来自三个地方：

Managed Skills： 用户安装的通用技Neng。

Workspace Skills： 当前工作项目下的特定技Neng。

内置 Skills： 系统自带的默认Neng力。

2. 按需加载与 Eligibility 检查

系统不会一次加载所有skill，而是通过 Eligibility 检查决定是否加载。比如某个skill可Neng要求本地安装了Docker，或者配置了GITHUB_TOKEN。

// src/agents/skills/config.ts
shouldIncludeSkill({  
  entry: skillEntry,  
  config: openclawConfig,  
  eligibility: runtimeContext  // 运行时上下文检查
})

加载条件优先级如下：

条件	说明	示例
always	始终加载	always: true
os	操作系统匹配	os:
requires.bins	需要本地命令	requires: { bins: }
requires.env	需要环境变量	requires: { env: }
requires.config	需要配置项	requires: { config: }
enabled	配置中启用	skills.entries.my-skill.enabled: false

3. Agent 如何调用 Skill？

这才是真正的精髓。skills的 Description 会被注入到Agent的System Prompt中，作为一个索引：

// src/agents/system-prompt.ts
function buildSkillsSection {  
  return ;
}

当Agent通过 Name 或者 Description，发现自己需要调用某个Skill时它会使用 Function Calling 的Neng力调用 read 工具：

Agent: "我需要使用 docker"
→ 调用 read 工具
→ 读取 ~/.openclaw/skills/docker-helper/SKILL.md
→ 获取完整 skill 内容并执行

这种机制极大地节省了Token，因为不是系统主动加载所有文档，而是Agent主动按需读取！Skills快照会缓存到Session中，避免每次dou重新加载，进一步提升性Neng。

六、 消息路由与会话管理

消息路由是将收到的IM消息分配到正确会话的过程。OpenClaw通过精心设计的Session Key来实现这一目标。

一个Session Key的格式如下：

// 格式: agent:{agentId}:{channel}:{peerKind}:{peerId}
agent:main:telegram:direct:user123        // Telegram 用户私聊
agent:main:discord:group:guild456         // Discord 群组
agent:main:slack:channel:C789             // Slack 频道

在配置文件中，我们Ke以针对私聊定义不同的路由策略：

agents:
  main:
    model: gpt-4
channels:
  telegram:
    dmScope: per-peer    # 每个用户独立会话
  slack:
    dmScope: main        # 共享会话

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

per-peer： 每个人跟AI的对话是独立的，互不干扰。

main： 所有人共享一个上下文，适合群组协作场景。

七、 三种 Agent 运行模式

Agent是龙虾的核心中的核心。研读源码后会发现，OpenClaw实际存在三种内置的核心运行模式。

1. CLI Provider 模式

直接调用本地的Claude CLI工具。

// src/agents/cli-runner.ts
runCliAgent({  
  provider: "claude-cli",  
  model: "claude-sonnet-4",  
  prompt: "用户消息",
})

2. Embedded PI 模式

OpenClaw直接调用LLM API。

// src/agents/pi-embedded-runner/run.ts
runEmbeddedPiAgent({  
  provider: "deepseek",  
  model: "deepseek-chat",  
  prompt: "用户消息",
})

代码中会根据配置自动判断：

// Ru果配置了 CLI Provider，使用 CLI 模式
if ) {  
  return runCliAgent;  
}  
// 否则使用 Embedded PI 模式
return runEmbeddedPiAgent;

3. ACP 模式

这是独立触发的，用于特定场景。它通过ACP控制平面调用远程Agent服务。

// src/gateway/server-methods/agent.ts
await acpManager.runTurn({  
  sessionKey,  
  text: body,  
  mode: "prompt",
})

八、 ：为什么要学习OpenClaw？

OpenClaw虽好，但确实有点“重”，而且是用TypeScript写的。那为什么我们还要花这么大精力去解析它？

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

它帮我们拿到了通道管理权限，拿到了运行时状态管理Neng力，拿到了插件化 Neng力。它证明了通过合理的抽象，一个AI AgentKe以优雅地生活在任何平台上。

接下来我会按照龙虾的思路，用PythonZuo一些小demo，分别实现它的核心模块，从而达到掌握吸收称为个人技Neng的效果！Ru果你也想构建属于自己的“PyClaw”，不妨从研究它的源码开始。毕竟站在巨人的肩膀上，我们总Nengkan得geng远。

---