Moltbot 快速入门指南

Moltbot 是一个 AI 聊天机器人框架，支持多平台（WhatsApp、Telegram、Discord、Mattermost 等）。本文档提供从零到第一个可用聊天的快速入门指南。

目标

从 零 → 第一个可用聊天（使用合理的默认配置），尽可能快速完成。

最快的方式：使用 Control UI

无需配置频道，直接打开浏览器界面聊天：

moltbot dashboard

然后访问 http://127.0.0.1:18789/ 或在网关主机上打开该地址。

推荐路径：CLI 向导

使用 CLI 入门向导 (moltbot onboard)，它会自动设置：

• 模型/认证（推荐 OAuth）
• 网关设置
• 频道配置（WhatsApp/Telegram/Discord/Mattermost 插件等）
• 配对默认值（安全私信）
• 工作空间初始化 + Skills
• 可选的后台服务

沙盒配置说明

默认配置 agents.defaults.sandbox.mode: "non-main" 使用 session.mainKey（默认为 "main"），因此群组/频道会话会被沙盒化。

如果希望主代理始终在主机上运行，需要设置显式的代理覆盖：

{
  "routing": {
    "agents": {
      "main": {
        "workspace": "~/clawd",
        "sandbox": { "mode": "off" }
      }
    }
  }
}

前置条件

系统要求

获取 Brave Search API Key

最简单的方式：

moltbot configure --section web

这会将 API key 存储到 tools.web.search.apiKey。

平台特定要求

macOS:

• 如果计划构建应用，需要安装 Xcode / CLT
• 如果只使用 CLI + 网关，只需 Node.js

Windows:

• 强烈推荐使用 WSL2（Ubuntu 推荐）
• 原生 Windows 未经测试，问题更多，工具兼容性较差

安装步骤

1) 安装 CLI（推荐）

Linux / macOS:

curl -fsSL https://molt.bot/install.sh | bash

Windows (PowerShell):

iwr -useb https://molt.bot/install.ps1 | iex

替代方案（全局安装）:

npm install -g moltbot@latest
# 或
pnpm add -g moltbot@latest

2) 运行入门向导并安装服务

moltbot onboard --install-daemon

向导配置选项

3) 启动网关

如果在入门向导中安装了服务，网关应该已经在运行：

手动运行（前台）:

moltbot gateway --port 18789 --verbose

Dashboard（本地回环）: http://127.0.0.1:18789/

3.5) 快速验证（2 分钟）

moltbot status
moltbot health
moltbot security audit --deep

4) 配对并连接第一个聊天平台

WhatsApp（QR 登录）

通过 WhatsApp → 设置 → 关联设备扫描二维码。

Telegram / Discord / 其他

向导可以自动写入 tokens/config。如果更喜欢手动配置，请参考官方文档。

5) 私信安全（配对审批）

默认策略：未知私信会收到简短代码，消息在批准前不会被处理。

如果你的第一条私信没有回复，批准配对：

moltbot pairing list whatsapp
moltbot pairing approve whatsapp <code>

从源码构建（开发）

如果要开发 Moltbot 本身，从源码运行：

git clone https://github.com/moltbot/moltbot.git
cd moltbot
pnpm install
pnpm ui:build        # 首次运行自动安装 UI 依赖
pnpm build
moltbot onboard --install-daemon

网关（从此仓库）:

node moltbot.mjs gateway --port 18789 --verbose

端到端验证

在新终端中，发送测试消息：

moltbot message send --target +15555550123 --message "Hello from Moltbot"

如果 moltbot health 显示"no auth configured"，返回向导设置 OAuth/key 认证 — 没有认证代理将无法响应。

下一步（可选但推荐）

相关链接

• GitHub: https://github.com/moltbot/moltbot
• 官方文档: https://docs.molt.bot
• 官方网站: https://molt.bot