Moltbot(Clawdbot)架构与技术全解析:AI助手开发必学指南(建议收藏)
Moltbot是一个个人AI助手系统,采用模块化架构,通过本地优先的Gateway控制平面管理多渠道通信和智能体会话。系统支持13+消息平台,具备语音唤醒、实时画布、工具系统等高级功能。基于TypeScript和Node.js构建,使用Pi Agent作为智能体运行时,通过插件系统实现功能扩展。跨平台支持macOS、iOS和Android,采用WebSocket协议通信,会话以JSONL格式持久化
Moltbot是一个个人AI助手系统,采用模块化架构,通过本地优先的Gateway控制平面管理多渠道通信和智能体会话。系统支持13+消息平台,具备语音唤醒、实时画布、工具系统等高级功能。基于TypeScript和Node.js构建,使用Pi Agent作为智能体运行时,通过插件系统实现功能扩展。跨平台支持macOS、iOS和Android,采用WebSocket协议通信,会话以JSONL格式持久化存储,整体设计注重隐私保护和可扩展性。
这两天被Moltbot刷屏了,各大云厂商都已经开始在云上部署Moltbot,玩法确实很多,具体怎么玩大家也可以在网上搜索一下。本文主要是从技术层面详细分析 Moltbot 项目的架构设计、技术栈、核心模块和实现细节。

目录
- 项目概述
- 技术栈
- 核心架构
- 模块详解
- 数据流与协议
- 扩展机制
- 平台支持
- 开发与构建
项目概述
Moltbot 是一个个人 AI 助手系统,可以在用户自己的设备上运行。它通过用户已使用的通信渠道(WhatsApp、Telegram、Slack、Discord、Signal、iMessage 等)与用户交互,并支持语音唤醒、画布渲染、浏览器控制等高级功能。
核心特性
- 本地优先的 Gateway:单一控制平面,管理会话、渠道、工具和事件
- 多渠道收件箱:支持 13+ 个消息平台
- 多智能体路由:支持多个隔离的智能体工作空间
- 语音唤醒与对话模式:macOS/iOS/Android 上的始终在线语音交互
- 实时画布:智能体驱动的可视化工作空间
- 工具系统:浏览器、画布、节点、定时任务、会话管理等工具
- 配套应用:macOS 菜单栏应用 + iOS/Android 节点应用
技术栈
运行时环境
- Node.js: ≥22.12.0(主要运行时)
- TypeScript: 5.9.3(主要开发语言)
- 包管理: pnpm 10.23.0(支持 Bun 作为替代)
核心依赖
AI 与智能体
@mariozechner/pi-agent-core: 0.49.3 - Pi 智能体核心运行时@mariozechner/pi-ai: 0.49.3 - Pi AI 集成@mariozechner/pi-coding-agent: 0.49.3 - 编码智能体@agentclientprotocol/sdk: 0.13.1 - ACP 协议 SDK
消息渠道
@whiskeysockets/baileys: 7.0.0-rc.9 - WhatsApp Web 协议grammy: 1.39.3 - Telegram Bot APIdiscord.js(通过扩展) - Discord Bot API@slack/bolt: 4.6.0 - Slack SDKsignal-cli(外部依赖) - Signal 协议
WebSocket 与网络
ws: 8.19.0 - WebSocket 服务器express: 5.2.1 - HTTP 服务器(控制 UI)hono: 4.11.4 - 轻量级 Web 框架@homebridge/ciao: 1.3.4 - Bonjour/mDNS 服务发现
工具与自动化
playwright-core: 1.58.0 - 浏览器控制(CDP)chromium-bidi: 13.0.1 - 浏览器双向协议croner: 9.1.0 - 定时任务sharp: 0.34.5 - 图像处理
数据与存储
sqlite-vec: 0.1.7-alpha.2 - 向量数据库(SQLite)proper-lockfile: 4.1.2 - 文件锁
类型与验证
@sinclair/typebox: 0.34.47 - JSON Schema 与类型验证zod: 4.3.6 - 运行时类型验证ajv: 8.17.1 - JSON Schema 验证器
其他关键依赖
tslog: 4.10.2 - 结构化日志commander: 14.0.2 - CLI 框架@clack/prompts: 0.11.0 - 终端 UI 组件markdown-it: 14.1.0 - Markdown 解析pdfjs-dist: 5.4.530 - PDF 处理
开发工具
- Linter: oxlint 1.41.0
- Formatter: oxfmt 0.26.0
- 测试框架: Vitest 4.0.18
- 构建工具: TypeScript Compiler (tsc)
- UI 构建: Rolldown 1.0.0-rc.1
平台特定
macOS/iOS
- 语言: Swift
- 框架: SwiftUI(使用 Observation 框架)
- 工具: Xcode, xcodegen
Android
- 语言: Kotlin
- 构建: Gradle (Kotlin DSL)
- 框架: Jetpack Compose
核心架构
整体架构图
┌─────────────────────────────────────────────────────────┐
│ 消息渠道层 │
│ WhatsApp / Telegram / Slack / Discord / Signal / ... │
└──────────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ Gateway (控制平面) │
│ • WebSocket 服务器 (ws://127.0.0.1:18789) │
│ • 渠道连接管理 │
│ • 会话管理 │
│ • 事件分发 │
│ • 工具执行 │
└──────────────┬────────────────────────────────────────────┘
│
├─ Pi Agent (RPC 模式)
├─ CLI (moltbot 命令)
├─ WebChat UI
├─ macOS 应用
└─ iOS/Android 节点
Gateway 架构
Gateway 是系统的核心控制平面,负责:
- 渠道连接管理
- 维护所有消息渠道的连接(WhatsApp、Telegram、Slack 等)
- 处理渠道认证和会话保持
- 监控渠道健康状态
- WebSocket 服务器
- 默认绑定到
127.0.0.1:18789 - 支持本地和远程访问(Tailscale、SSH 隧道)
- 类型化的请求/响应协议
- JSON Schema 验证
- 会话管理
- 维护智能体会话状态
- 支持多智能体隔离
- 会话持久化(JSONL 格式)
- 事件系统
- 服务器推送事件(
agent,chat,presence,health等) - 客户端订阅机制
- 状态版本控制
Gateway 协议
连接握手:
// 客户端必须首先发送 connect 请求
{
type: "req",
id: "unique-request-id",
method: "connect",
params: {
deviceId: "device-identity",
role: "operator" | "node",
auth: { token?: string }
}
}
// 服务器响应
{
type: "res",
id: "unique-request-id",
ok: true,
payload: {
hello: "ok",
snapshot: {
presence: {...},
health: {...}
}
}
}
请求/响应模式:
// 请求
{ type: "req", id: string, method: string, params: any }
// 响应
{ type: "res", id: string, ok: boolean, payload?: any, error?: any }
事件推送:
{ type: "event", event: string, payload: any, seq?: number, stateVersion?: number }
智能体运行时
Moltbot 使用 Pi Agent 作为智能体运行时,通过 RPC 模式集成:
智能体循环(Agent Loop)
- 入口点
- Gateway RPC:
agent和agent.wait - CLI:
moltbot agent命令
-
执行流程
消息接收 → 会话解析 → 上下文组装 → 模型推理 → 工具执行 → 流式回复 → 持久化 -
关键组件
runEmbeddedPiAgent: 执行智能体运行createAgentSession: 创建智能体会话subscribeEmbeddedPiSession: 订阅 Pi 事件并桥接到 Gateway 事件流
- 队列与并发
- 按会话键(session key)序列化运行
- 可选的全局队列防止工具/会话竞争
- 保持会话历史一致性
工具系统
智能体可以调用多种工具:
- bash: 执行 shell 命令(支持沙箱模式)
- browser: 浏览器控制(CDP)
- canvas: 画布操作(A2UI)
- nodes: 设备节点操作(相机、屏幕录制、位置等)
- cron: 定时任务
- sessions_*: 会话间通信
- discord/slack: 渠道特定操作
- gateway: Gateway 配置和管理
渠道系统
渠道插件架构
每个渠道实现为一个插件,包含以下适配器:
type ChannelPlugin = {
id: ChannelId;
meta: ChannelMeta;
capabilities: ChannelCapabilities;
config: ChannelConfigAdapter; // 配置解析
onboarding?: ChannelOnboardingAdapter; // 引导流程
pairing?: ChannelPairingAdapter; // 配对逻辑
outbound?: ChannelOutboundAdapter; // 消息发送
status?: ChannelStatusAdapter; // 状态检查
gateway?: ChannelGatewayAdapter; // Gateway 方法
// ... 更多适配器
}
核心渠道
内置渠道:
whatsapp: Baileys Web 协议telegram: grammY Bot APIslack: Bolt SDKdiscord: discord.js(通过扩展)signal: signal-cliimessage: macOS 原生集成webchat: WebSocket 聊天界面
扩展渠道(通过插件):
msteams: Microsoft Teamsmatrix: Matrix 协议zalo: Zalo Bot APIzalouser: Zalo 个人账户bluebubbles: BlueBubbles iMessage 服务器line: LINE Messaging APImattermost: Mattermostnextcloud-talk: Nextcloud Talknostr: Nostr 协议tlon: Urbit Tlontwitch: Twitch IRC
路由机制
消息路由规则(优先级顺序):
- 精确对等匹配:
bindings中的peer.kind+peer.id - Guild 匹配: Discord 的
guildId - Team 匹配: Slack 的
teamId - 账户匹配: 渠道的
accountId - 渠道匹配: 该渠道的任何账户
- 默认智能体:
agents.list[].default或第一个列表项
会话键(Session Key)格式
- 直接消息:
agent:<agentId>:main - 群组:
agent:<agentId>:<channel>:group:<id> - 频道:
agent:<agentId>:<channel>:channel:<id> - 线程: 追加
:thread:<threadId> - 话题: 嵌入
:topic:<topicId>(Telegram)
示例:
agent:main:telegram:group:-1001234567890:topic:42agent:main:discord:channel:123456:thread:987654
模块详解
1. Gateway 模块 (src/gateway/)
职责: WebSocket 服务器、协议处理、客户端管理
关键文件:
server.impl.ts: Gateway 服务器实现server-runtime-state.ts: 运行时状态管理server-methods/: Gateway RPC 方法实现server-channels.ts: 渠道管理器
核心功能:
- WebSocket 连接管理
- 请求路由和验证
- 事件分发
- 客户端配对和设备管理
2. 智能体模块 (src/agents/)
职责: Pi Agent 集成、会话管理、工具执行
关键文件:
pi-embedded-runner/: Pi Agent 嵌入式运行器pi-tools.ts: Moltbot 工具定义cli-runner.ts: CLI 模式运行器model-selection.ts: 模型选择逻辑model-fallback.ts: 模型故障转移
核心功能:
- 智能体循环执行
- 工具调用处理
- 会话上下文管理
- 流式响应处理
3. 渠道模块 (src/channels/)
职责: 渠道抽象、路由、消息处理
关键文件:
registry.ts: 渠道注册表dock.ts: 渠道轻量级元数据plugins/: 渠道插件实现targets.ts: 消息目标解析session.ts: 渠道会话管理
核心功能:
- 渠道发现和加载
- 消息路由
- 群组和线程处理
- 配对和认证
4. 自动回复模块 (src/auto-reply/)
职责: 消息接收、智能体调用、回复发送
关键文件:
reply/agent-runner-execution.ts: 智能体执行queue.ts: 消息队列reply-payloads.ts: 回复载荷处理typing-mode.ts: 输入指示器
核心功能:
- 消息接收和解析
- 智能体调用编排
- 回复生成和发送
- 队列管理
5. 配置模块 (src/config/)
职责: 配置管理、验证、持久化
关键文件:
config.ts: 配置加载和解析types.*.ts: 配置类型定义sessions.ts: 会话配置channels.ts: 渠道配置
核心功能:
- JSON5 配置解析
- 配置验证(TypeBox/Zod)
- 配置合并和默认值
- 配置热重载
6. CLI 模块 (src/cli/)
职责: 命令行界面、命令注册、用户交互
关键文件:
program/: 命令注册和路由gateway-cli/: Gateway 命令nodes-cli/: 节点命令config-cli.ts: 配置命令
核心功能:
- 命令解析和路由
- 终端 UI(@clack/prompts)
- 进度显示(osc-progress)
- 帮助系统
7. 工具模块
浏览器工具 (src/browser/)
- Chrome/Chromium 管理
- CDP 控制
- 快照和操作
- 配置文件管理
画布工具 (src/canvas-host/)
- A2UI 主机
- 画布操作(push/reset/eval)
- HTML 渲染
节点工具 (src/node-host/)
- 设备节点通信
- 相机、屏幕录制、位置等操作
- 权限管理
8. 媒体处理 (src/media/)
职责: 媒体文件处理、转码、存储
核心功能:
- 图像处理(sharp)
- 音频处理
- 视频处理
- MIME 类型检测
- 文件大小限制
9. 安全模块 (src/security/)
职责: 沙箱、权限控制、安全策略
核心功能:
- Docker 沙箱(非主会话)
- 工具权限控制
- 配对和设备认证
- 配置安全检查
10. 插件系统 (src/plugins/)
职责: 插件加载、运行时、工具注入
关键文件:
loader.ts: 插件加载器runtime.ts: 插件运行时registry.ts: 插件注册表tools.ts: 工具注入
核心功能:
- 插件发现和加载
- 插件生命周期管理
- 工具和钩子注册
- 配置模式验证
数据流与协议
消息处理流程
1. 渠道接收消息
↓
2. 渠道插件解析消息
↓
3. 路由解析(确定智能体和会话)
↓
4. 消息入队(按会话序列化)
↓
5. 智能体循环执行
├─ 上下文组装
├─ 模型推理
├─ 工具调用(如需要)
└─ 流式回复生成
↓
6. 回复处理
├─ Markdown 渲染
├─ 媒体附件
└─ 格式化
↓
7. 发送到原渠道
Gateway 事件流
客户端订阅:
// 订阅事件
{ type: "req", method: "subscribe", params: { events: ["agent", "presence"] } }
// 接收事件
{ type: "event", event: "agent", payload: { runId, phase: "start" } }
{ type: "event", event: "agent", payload: { runId, stream: "assistant", delta: "..." } }
{ type: "event", event: "agent", payload: { runId, phase: "end", summary: {...} } }
会话持久化
存储位置: ~/.clawdbot/agents/<agentId>/sessions/<sessionKey>.jsonl
格式: JSONL(每行一个 JSON 对象)
{"role": "user", "content": "Hello", "timestamp": "2026-01-28T10:00:00Z"}
{"role": "assistant", "content": "Hi!", "timestamp": "2026-01-28T10:00:01Z"}
扩展机制
插件系统
插件类型
- 渠道插件 (
extensions/*/)
- 实现
ChannelPlugin接口 - 提供渠道特定功能
- 工具插件
- 注册自定义工具
- 扩展智能体能力
- 钩子插件
- 生命周期钩子
- 消息处理钩子
插件结构
extensions/my-plugin/
├── clawdbot.plugin.json # 插件清单
├── package.json
├── index.ts # 入口点
└── src/
├── channel.ts # 渠道实现
├── runtime.ts # 运行时逻辑
└── config-schema.ts # 配置模式
插件清单
{
"id": "my-plugin",
"name": "My Plugin",
"version": "1.0.0",
"entry": "./index.ts",
"capabilities": {
"channel": true,
"tools": ["my-tool"]
}
}
Skills 系统
Skills 是智能体的能力扩展,存储在 ~/clawd/skills/<skill>/SKILL.md。
类型:
- Bundled: 内置技能
- Managed: 通过 ClawdHub 管理
- Workspace: 用户自定义
注入点:
AGENTS.md: 智能体指令TOOLS.md: 工具文档SOUL.md: 个性定义
平台支持
macOS 应用
技术栈:
- Swift + SwiftUI
- Observation 框架(状态管理)
- Bonjour 服务发现
- XPC 进程间通信
功能:
- 菜单栏控制
- Voice Wake(语音唤醒)
- Talk Mode(对话模式)
- WebChat 界面
- 远程 Gateway 控制
架构:
Moltbot.app
├── GatewayConnection (WebSocket)
├── ChannelsStore (状态管理)
├── VoiceWakeManager (语音唤醒)
└── NodeMode (节点模式)
iOS 应用
技术栈:
- Swift + SwiftUI
- Bonjour 配对
- AVFoundation(音频)
功能:
- Canvas 渲染
- Voice Wake
- Talk Mode
- 相机和屏幕录制
Android 应用
技术栈:
- Kotlin + Jetpack Compose
- WebSocket 客户端
- CameraX
功能:
- Canvas 渲染
- Talk Mode
- 相机和屏幕录制
- 可选 SMS 支持
开发与构建
项目结构
moltbot/
├── src/ # TypeScript 源代码
│ ├── gateway/ # Gateway 核心
│ ├── agents/ # 智能体运行时
│ ├── channels/ # 渠道系统
│ ├── cli/ # CLI 命令
│ ├── commands/ # 命令实现
│ └── ...
├── apps/ # 平台应用
│ ├── macos/ # macOS 应用
│ ├── ios/ # iOS 应用
│ └── android/ # Android 应用
├── extensions/ # 插件扩展
├── ui/ # Web UI
├── docs/ # 文档
├── scripts/ # 构建脚本
└── test/ # 测试
构建流程
- 依赖安装:
pnpm install - UI 构建:
pnpm ui:build - TypeScript 编译:
pnpm build - 测试:
pnpm test
开发命令
# 开发模式(自动重载)
pnpm gateway:watch
# 运行 CLI
pnpm moltbot <command>
# 测试
pnpm test
pnpm test:coverage
# 代码质量
pnpm lint
pnpm format
测试策略
- 单元测试: Vitest,覆盖率阈值 70%
- E2E 测试: Docker 环境
- 实时测试:
pnpm test:live(需要真实 API 密钥)
代码规范
- 语言: TypeScript (ESM)
- 格式化: oxfmt
- Linting: oxlint
- 文件大小: 建议 < 500 LOC
- 类型: 严格类型,避免
any
总结
Moltbot 是一个设计精良的个人 AI 助手系统,具有以下特点:
- 模块化架构: 清晰的模块划分,易于扩展
- 类型安全: 全面的 TypeScript 类型系统
- 可扩展性: 插件系统和 Skills 机制
- 跨平台: 支持 macOS、iOS、Android
- 本地优先: 数据存储在本地,隐私可控
- 多渠道支持: 统一的渠道抽象,易于添加新渠道
该架构支持快速迭代和功能扩展,同时保持代码质量和可维护性。
如何系统的学习大模型 AI ?
由于新岗位的生产效率,要优于被取代岗位的生产效率,所以实际上整个社会的生产效率是提升的。
但是具体到个人,只能说是:
“最先掌握AI的人,将会比较晚掌握AI的人有竞争优势”。
这句话,放在计算机、互联网、移动互联网的开局时期,都是一样的道理。
我在一线互联网企业工作十余年里,指导过不少同行后辈。帮助很多人得到了学习和成长。
我意识到有很多经验和知识值得分享给大家,也可以通过我们的能力和经验解答大家在人工智能学习中的很多困惑,所以在工作繁忙的情况下还是坚持各种整理和分享。但苦于知识传播途径有限,很多互联网行业朋友无法获得正确的资料得到学习提升,故此将并将重要的AI大模型资料包括AI大模型入门学习思维导图、精品AI大模型学习书籍手册、视频教程、实战学习等录播视频免费分享出来。
一直在更新,更多的大模型学习和面试资料已经上传带到CSDN的官方了,有需要的朋友可以扫描下方二维码免费领取【保证100%免费】👇👇

01.大模型风口已至:月薪30K+的AI岗正在批量诞生

2025年大模型应用呈现爆发式增长,根据工信部最新数据:
国内大模型相关岗位缺口达47万
初级工程师平均薪资28K(数据来源:BOSS直聘报告)
70%企业存在"能用模型不会调优"的痛点
真实案例:某二本机械专业学员,通过4个月系统学习,成功拿到某AI医疗公司大模型优化岗offer,薪资直接翻3倍!
02.大模型 AI 学习和面试资料
1️⃣ 提示词工程:把ChatGPT从玩具变成生产工具
2️⃣ RAG系统:让大模型精准输出行业知识
3️⃣ 智能体开发:用AutoGPT打造24小时数字员工
📦熬了三个大夜整理的《AI进化工具包》送你:
✔️ 大厂内部LLM落地手册(含58个真实案例)
✔️ 提示词设计模板库(覆盖12大应用场景)
✔️ 私藏学习路径图(0基础到项目实战仅需90天)






第一阶段(10天):初阶应用
该阶段让大家对大模型 AI有一个最前沿的认识,对大模型 AI 的理解超过 95% 的人,可以在相关讨论时发表高级、不跟风、又接地气的见解,别人只会和 AI 聊天,而你能调教 AI,并能用代码将大模型和业务衔接。
- 大模型 AI 能干什么?
- 大模型是怎样获得「智能」的?
- 用好 AI 的核心心法
- 大模型应用业务架构
- 大模型应用技术架构
- 代码示例:向 GPT-3.5 灌入新知识
- 提示工程的意义和核心思想
- Prompt 典型构成
- 指令调优方法论
- 思维链和思维树
- Prompt 攻击和防范
- …
第二阶段(30天):高阶应用
该阶段我们正式进入大模型 AI 进阶实战学习,学会构造私有知识库,扩展 AI 的能力。快速开发一个完整的基于 agent 对话机器人。掌握功能最强的大模型开发框架,抓住最新的技术进展,适合 Python 和 JavaScript 程序员。
- 为什么要做 RAG
- 搭建一个简单的 ChatPDF
- 检索的基础概念
- 什么是向量表示(Embeddings)
- 向量数据库与向量检索
- 基于向量检索的 RAG
- 搭建 RAG 系统的扩展知识
- 混合检索与 RAG-Fusion 简介
- 向量模型本地部署
- …
第三阶段(30天):模型训练
恭喜你,如果学到这里,你基本可以找到一份大模型 AI相关的工作,自己也能训练 GPT 了!通过微调,训练自己的垂直大模型,能独立训练开源多模态大模型,掌握更多技术方案。
到此为止,大概2个月的时间。你已经成为了一名“AI小子”。那么你还想往下探索吗?
- 为什么要做 RAG
- 什么是模型
- 什么是模型训练
- 求解器 & 损失函数简介
- 小实验2:手写一个简单的神经网络并训练它
- 什么是训练/预训练/微调/轻量化微调
- Transformer结构简介
- 轻量化微调
- 实验数据集的构建
- …
第四阶段(20天):商业闭环
对全球大模型从性能、吞吐量、成本等方面有一定的认知,可以在云端和本地等多种环境下部署大模型,找到适合自己的项目/创业方向,做一名被 AI 武装的产品经理。
- 硬件选型
- 带你了解全球大模型
- 使用国产大模型服务
- 搭建 OpenAI 代理
- 热身:基于阿里云 PAI 部署 Stable Diffusion
- 在本地计算机运行大模型
- 大模型的私有化部署
- 基于 vLLM 部署大模型
- 案例:如何优雅地在阿里云私有部署开源大模型
- 部署一套开源 LLM 项目
- 内容安全
- 互联网信息服务算法备案
- …
学习是一个过程,只要学习就会有挑战。天道酬勤,你越努力,就会成为越优秀的自己。
如果你能在15天内完成所有的任务,那你堪称天才。然而,如果你能完成 60-70% 的内容,你就已经开始具备成为一名大模型 AI 的正确特征了。
这份完整版的大模型 AI 学习资料已经上传CSDN,朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】

更多推荐



所有评论(0)