Moltbot 完整安装与部署教程

🦞 Moltbot 完整安装与部署教程 🦞

在 macOS 上安装并部署到 Telegram 的完整指南

📋 目录

Moltbot 是什么？
前置条件
安装步骤
初始配置
Telegram Bot 部署
运行 Gateway
验证安装
常见问题

🦞 Moltbot 是什么？

Moltbot 是一个强大的个人 AI 助手，可以在您自己的设备上运行。它支持多种即时通讯平台，包括 WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、iMessage 等。

🔒 隐私优先

数据保存在您自己的设备上，完全由您控制

🌐 多平台支持

支持主流聊天平台，统一管理

🤖 AI 驱动

集成 Claude、GPT 等顶级 AI 模型

🛠️ 强大工具

浏览器控制、文件操作、代码执行等

系统架构

graph TB subgraph "聊天平台" WA[WhatsApp] TG[Telegram] DC[Discord] SL[Slack] end subgraph "Moltbot Gateway" GW[Gateway 控制平面] AG[Agent 运行时] WS[WebSocket 接口] end subgraph "客户端" CLI[CLI 工具] UI[Web UI] MAC[macOS 应用] end WA --> GW TG --> GW DC --> GW SL --> GW GW --> CLI GW --> UI GW --> MAC AG --- GW

📋 前置条件

1检查系统要求

操作系统： macOS（推荐）或 Linux/WSL2
Node.js：版本 >= 22
包管理器：npm、pnpm 或 bun（推荐 pnpm）
磁盘空间：至少 500MB 可用空间
内存：至少 2GB RAM

2验证 Node.js 版本

打开终端，检查 Node.js 是否已安装：

node --version

如果版本低于 22，需要升级 Node.js：

⚠️ 重要：建议使用 Node.js 22 或更高版本，以获得最佳兼容性和性能。

使用 nvm 安装/管理 Node.js：

# 安装 nvm（如果尚未安装）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 安装并使用 Node.js 22
nvm install 22
nvm use 22

# 验证版本
node --version

3安装 pnpm（推荐）

# 使用 npm 安装 pnpm
npm install -g pnpm

# 验证安装
pnpm --version

🚀 安装步骤

方法一：使用安装脚本（推荐）

# 下载并执行安装脚本
curl -fsSL https://molt.bot/install.sh | bash

方法二：使用 npm 全局安装

npm install -g moltbot@latest

方法三：使用 pnpm 全局安装

pnpm add -g moltbot@latest

💡 安装验证：安装完成后，运行以下命令验证安装：

moltbot --version

⚙️ 初始配置

1运行 onboarding 向导

这是最简单、最推荐的配置方式：

moltbot onboard --install-daemon

向导会引导您完成以下配置：

选择本地或远程 Gateway
配置 AI 模型认证（OAuth 或 API Key）
设置聊天频道（WhatsApp、Telegram、Discord 等）
配置 DM 安全性（配对审批）
设置工作区和技能
安装后台服务（launchd/systemd）

2手动配置（可选）

如果您不想使用向导，可以手动配置。配置文件位于：

~/.clawdbot/moltbot.json

基本配置示例：

{
  "agent": {
    "model": "anthropic/claude-opus-4-5"
  },
  "gateway": {
    "port": 18789,
    "auth": {
      "token": "your-gateway-token-here"
    }
  }
}

📱 Telegram Bot 部署

1创建 Telegram Bot

打开 Telegram，搜索并联系 @BotFather
发送 /newbot 命令
按照提示输入 Bot 名称和用户名
保存好 Bot Token（格式类似：123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11）

💡 提示：您还可以使用 BotFather 的其他命令来自定义 Bot：

/setdescription - 设置 Bot 描述
/setabouttext - 设置关于信息
/setuserpic - 设置头像

2配置 Telegram 频道

编辑配置文件，添加 Telegram 配置：

# 使用 CLI 配置（推荐）
moltbot configure --section telegram --key botToken "你的Bot Token"

# 或者手动编辑配置文件
moltbot configure

配置文件内容：

{
  "channels": {
    "telegram": {
      "botToken": "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",
      "groups": {
        "*": {
          "requireMention": false
        }
      },
      "allowFrom": ["*"]
    }
  }
}

⚠️ 安全注意：

不要将 Bot Token 分享给他人
建议使用环境变量：TELEGRAM_BOT_TOKEN
配置文件权限应设置为仅当前用户可读

3设置 DM 安全策略

Moltbot 默认启用 DM 配对保护，需要批准后才能接收消息：

{
  "channels": {
    "telegram": {
      "dmPolicy": "pairing",
      "allowFrom": ["*"]
    }
  }
}

DM 策略说明：

pairing - 需要配对码批准（推荐）
open - 开放接收所有消息
closed - 拒绝所有 DM

4登录 Telegram 频道

# 登录 Telegram
moltbot channels login telegram

首次登录会提示配置验证信息。

▶️ 运行 Gateway

方式一：使用后台服务（推荐）

# 检查服务状态
moltbot gateway status

# 启动服务
moltbot gateway start

# 停止服务
moltbot gateway stop

# 重启服务
moltbot gateway restart

方式二：手动运行（前台模式）

# 前台运行 Gateway
moltbot gateway --port 18789 --verbose

⚠️ Bun 警告：如果您使用 WhatsApp 或 Telegram，强烈建议使用 Node.js 运行 Gateway，而不是 Bun，因为 Bun 存在兼容性问题。

方式三：从源码运行（开发模式）

# 克隆源码
git clone https://github.com/moltbot/moltbot.git
cd moltbot

# 安装依赖
pnpm install

# 构建项目
pnpm build

# 运行 Gateway
node moltbot.mjs gateway --port 18789 --verbose

✅ 验证安装

1检查系统状态

# 检查整体状态
moltbot status

# 健康检查
moltbot health

# 深度安全审计
moltbot security audit --deep

2测试 Telegram Bot

在 Telegram 中找到您的 Bot
发送 /start 命令
Bot 应该返回配对码
批准配对请求：

# 列出待批准的配对
moltbot pairing list telegram

# 批准配对
moltbot pairing approve telegram 配对码

3发送测试消息

# 通过 CLI 发送测试消息
moltbot message send --target +15555550123 --message "Hello from Moltbot!"

# 与 Agent 对话
moltbot agent --message "你好，Moltbot！" --thinking high

4访问 Web UI

打开浏览器访问：

# 控制面板
http://127.0.0.1:18789/

# WebChat
http://127.0.0.1:18789/webchat

💡 提示：如果配置了 Gateway token，需要在设置中输入 token 才能连接。

🛠️ 常用命令

命令	描述
`moltbot status`	查看系统状态
`moltbot health`	健康检查
`moltbot gateway status`	检查 Gateway 状态
`moltbot gateway start`	启动 Gateway 服务
`moltbot gateway stop`	停止 Gateway 服务
`moltbot channels list`	列出已配置的频道
`moltbot channels login telegram`	登录 Telegram 频道
`moltbot pairing list telegram`	查看 Telegram 配对请求
`moltbot pairing approve telegram <code>`	批准 Telegram 配对
`moltbot message send --target <target> --message "<message>"`	发送消息
`moltbot agent --message "<message>"`	与 AI Agent 对话
`moltbot doctor`	系统诊断
`moltbot update`	更新 Moltbot

🔧 常见问题

Q1: Gateway 无法启动？

解决方案：

检查端口 18789 是否被占用：lsof -i :18789
查看详细错误日志：moltbot gateway --verbose
确保 Node.js 版本 >= 22

Q2: Telegram Bot 无响应？

目录导航

Moltbot 完整安装与部署教程

预览结果：