5.0 KiB
| summary | read_when | ||
|---|---|---|---|
| 入门指南：从零到第一条消息（向导、认证、渠道、配对） |
|
快速开始
目标：尽快从 零 → 第一个运行的聊天（使用合理的默认值）。
最快的聊天方式：打开控制 UI（无需渠道设置）。运行 moltbot dashboard 并在浏览器中聊天，或在网关主机上打开 http://127.0.0.1:18789/。
文档：Dashboard 和 Control UI。
推荐路径：使用 CLI 引导向导 (moltbot onboard)。它会设置：
- 模型/认证（推荐 OAuth）
- 网关设置
- 渠道（WhatsApp/Telegram/Discord/Mattermost(插件)/...）
- 配对默认值（安全 DM）
- 工作区引导 + 技能
- 可选的后台服务
0) 前置条件
- Node
>=22 pnpm（可选；如果从源码构建则推荐）- 推荐： Brave Search API 密钥用于网络搜索。最简单的方式：
moltbot configure --section web（存储tools.web.search.apiKey）。
macOS： 如果计划构建应用，需安装 Xcode / CLT。仅 CLI + 网关只需要 Node。
Windows： 使用 WSL2（推荐 Ubuntu）。WSL2 是强烈推荐的；原生 Windows 未经测试，问题更多，工具兼容性较差。
1) 安装 CLI（推荐）
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
你将选择：
- 本地 vs 远程 网关
- 认证：OpenAI Code (Codex) 订阅 (OAuth) 或 API 密钥。对于 Anthropic 推荐使用 API 密钥。
- 提供商：WhatsApp 二维码登录、Telegram/Discord 机器人令牌等。
- 守护进程：后台安装（launchd/systemd；WSL2 使用 systemd）
- 网关令牌：向导默认生成一个并存储在
gateway.auth.token中。
认证：存储位置（重要）
- 推荐 Anthropic 路径： 设置 API 密钥（向导可以为服务使用存储它）。
- OAuth 凭证（旧版导入）：
~/.clawdbot/credentials/oauth.json - 认证配置文件（OAuth + API 密钥）：
~/.clawdbot/agents/<agentId>/agent/auth-profiles.json
无头/服务器提示： 先在普通机器上进行 OAuth，然后将 oauth.json 复制到网关主机。
3) 启动网关
如果在引导期间安装了服务，网关应该已经在运行：
moltbot gateway status
手动运行（前台）：
moltbot gateway --port 18789 --verbose
仪表板（本地回环）： http://127.0.0.1:18789/
如果配置了令牌，将其粘贴到控制 UI 设置中。
⚠️ Bun 警告（WhatsApp + Telegram）： Bun 在这些渠道上有已知问题。如果使用 WhatsApp 或 Telegram，请用 Node 运行网关。
3.5) 快速验证（2 分钟）
moltbot status
moltbot health
moltbot security audit --deep
4) 配对 + 连接你的第一个聊天界面
WhatsApp（二维码登录）
moltbot channels login
通过 WhatsApp → 设置 → 链接设备 扫描。
Telegram / Discord / 其他
向导可以为你写入令牌/配置。如果偏好手动配置：
- Telegram：设置
TELEGRAM_BOT_TOKEN环境变量或配置文件 - Discord：设置
DISCORD_BOT_TOKEN环境变量
Telegram DM 提示： 你的第一个 DM 会返回一个配对码。需要批准它（见下一步），否则机器人不会响应。
5) DM 安全（配对批准）
默认行为：未知 DM 会收到一个短代码，消息在批准前不会被处理。 如果你的第一个 DM 没有收到回复，批准配对：
moltbot pairing list whatsapp
moltbot pairing approve whatsapp <code>
注意： Telegram 不使用配对，而是使用 allowFrom 配置：
{
channels: {
telegram: {
allowFrom: ["YOUR_USER_ID"]
}
}
}
6) 从源码安装（开发）
git clone https://github.com/moltbot/moltbot.git
cd moltbot
pnpm install
pnpm ui:build # 首次运行会自动安装 UI 依赖
pnpm build
pnpm moltbot onboard --install-daemon
网关（从此仓库）：
node moltbot.mjs gateway --port 18789 --verbose
7) 端到端验证
在新终端中，发送测试消息：
moltbot message send --target +15555550123 --message "来自 Moltbot 的问候"
如果 moltbot health 显示 "no auth configured"，返回向导设置 OAuth/密钥认证——没有它助手无法响应。
提示： moltbot status --all 是最好的可粘贴、只读调试报告。