Moltbot 架构文档

深度解析 Moltbot 项目架构的核心设计与实现机制

项目概览

Moltbot 是一个个人 AI 助手，支持多渠道消息、本地优先部署、插件化扩展和沙箱隔离。

核心特性：

• 🌐 多渠道支持：WhatsApp、Telegram、Discord、Slack、Signal、iMessage 等
• 🔒 本地优先：Gateway 作为控制平面，数据保留在本地
• 🔌 插件系统：支持 Channel、Provider、Tool、Hook 等插件扩展
• 🛡️ 沙箱隔离：非主会话可在 Docker 沙箱中运行
• 🤖️ Agent 运行时：基于 pi-coding-agent 的高性能 AI Agent
• 🔌 WebSocket 协议：统一的网关通信协议

文档导航

核心架构

• Gateway 架构 - WebSocket 网关、服务器启动、协议设计
• Channel 系统 - 渠道插件、消息路由、会话管理
• Pi Agent 运行时 - Agent 运行流程、工具调用、沙箱集成
• 消息路由 - 路由解析、会话键构建、Agent 路由

配置与扩展

• 配置系统 - 配置层次、加载流程、热重载、迁移
• 插件系统 - 插件架构、类型定义、加载流程
• Hooks 系统 - 事件驱动、生命周期、Hook 注册

运行时机制

• 工具系统 - 工具注册、过滤策略、沙箱适配
• 会话管理 - Session 模型、上下文管理、压缩
• Sandbox 系统 - Docker 隔离、容器管理、工具策略

安全与认证

• 安全模型 - DM 策略、允许列表、权限控制

架构层次

核心设计原则

1. 本地优先

• Gateway 作为本地控制平面，绑定到 127.0.0.1
• 数据存储在本地文件系统（~/.clawdbot/）
• 支持远程访问通过 Tailscale/SSH 隧道

2. 插件化架构

• 核心功能最小化，通过插件扩展
• 统一的 Plugin API 和注册机制
• 支持动态加载和热重载

3. 安全第一

• DM 默认需要配对（dmPolicy="pairing"）
• 非主会话默认在沙箱中运行
• 工具执行需要批准（可配置）

4. 消息驱动

• WebSocket 协议统一通信
• 事件广播系统
• 异步队列处理

5. 可观测性

• 详细的日志系统
• Health check 端点
• 使用量追踪和成本统计

技术栈

目录结构概览

moltbot/
├── src/
│   ├── agents/           # Pi Agent 运行时
│   ├── channels/         # 渠道系统和插件
│   ├── cli/             # CLI 命令
│   ├── commands/         # CLI 实现
│   ├── config/           # 配置系统
│   ├── daemon/           # 系统服务（launchd/systemd）
│   ├── gateway/          # Gateway 服务器
│   ├── hooks/            # Hooks 系统
│   ├── plugins/          # 插件系统
│   ├── sessions/         # 会话管理
│   └── utils/            # 工具函数
├── extensions/           # 外部插件（workspace）
├── apps/
│   ├── macos/           # macOS app
│   ├── ios/             # iOS node
│   └── android/         # Android node
└── docs/                # 用户文档

快速链接

• 源码仓库: https://github.com/moltbot/moltbot
• 官方文档: https://docs.molt.bot
• 技术博客: https://steipete.me

文档版本: 2026.1.27 最后更新: 2026-01-28