入门指南

目标：从零开始 → 第一个可用的聊天（使用默认配置）尽可能快。

最快聊天方式

打开控制台 UI（无需通道设置）。运行 moltbot dashboard 在浏览器中聊天，或在网关主机上打开 http://127.0.0.1:18789/。

推荐路径：使用 CLI 安装向导 (moltbot onboard)。它会设置：

• 模型/认证（推荐 OAuth）
• 网关设置
• 通道（WhatsApp/Telegram/Discord/Mattermost 等）
• 配对默认值（安全私聊）
• 工作区引导 + 技能
• 可选后台服务

前置要求

• Node.js ≥ 22
• pnpm（可选，但从源码构建时推荐）
• 推荐：Brave Search API 密钥用于网页搜索

macOS

如果你计划构建应用，需要安装 Xcode / CLT。仅 CLI + 网关的话，只需要 Node.js。

Windows

使用 WSL2（推荐 Ubuntu）。强烈推荐 WSL2；原生 Windows 未经过更多测试，问题更多，且工具兼容性较差。先安装 WSL2，然后在 WSL 内运行 Linux 步骤。

文档：Windows (WSL2)

1) 安装 CLI（推荐）

# 一键安装脚本
curl -fsSL https://molt.bot/install.sh | bash

Windows (PowerShell):

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

替代方案（全局安装）：

# npm
npm install -g moltbot@latest

# pnpm
pnpm add -g moltbot@latest

2) 运行安装向导（并安装服务）

moltbot onboard --install-daemon

你将选择：

• 本地 vs 远程 网关
• 认证：OpenAI Code (Codex) 订阅 (OAuth) 或 API 密钥。Anthropic 推荐 API key。
• 提供商：WhatsApp 扫码登录、Telegram/Discord Bot Token 等
• 守护进程：后台安装（launchd/systemd；WSL2 使用 systemd）
• 运行时：Node（推荐；WhatsApp/Telegram 需要）
• 网关令牌：向导默认生成一个（即使在本地环回）

向导文档：安装向导

认证：存储位置（重要）

• 推荐 Anthropic 路径：设置 API key（向导可以为服务存储）。也支持 claude setup-token。
• OAuth 凭证：~/.clawdbot/credentials/oauth.json
• 认证配置：~/.clawdbot/agents/<agentId>/agent/auth-profiles.json

无头/服务器提示：先在普通机器上进行 OAuth，然后复制 oauth.json 到网关主机。

3) 启动网关

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

moltbot gateway status

手动运行（前台）：

moltbot gateway --port 18789 --verbose

控制台 UI（本地环回）：http://127.0.0.1:18789/

⚠️ Bun 警告（WhatsApp + Telegram）：Bun 与这些通道有已知问题。如果你使用 WhatsApp 或 Telegram，使用 Node 运行网关。

4) 快速验证（2 分钟）

moltbot status
moltbot health
moltbot security audit --deep

5) 配对并连接你的第一个聊天界面

WhatsApp（扫码登录）

moltbot channels login

通过 WhatsApp → 设置 → 已关联设备扫描。

WhatsApp 文档：WhatsApp

Telegram / Discord / 其他

向导可以为你写入 Token/配置。如果你偏好手动配置，从以下开始：

• Telegram：Telegram
• Discord：Discord
• Mattermost（插件）：Mattermost

Telegram 私聊提示：你的第一条私聊会返回一个配对代码。批准它（见下一步），否则 Bot 不会回复。

6) 私聊安全（配对批准）

默认策略：未知的私聊会收到一个短代码，在批准之前不会处理消息。

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

moltbot pairing list whatsapp
moltbot pairing approve whatsapp <code>

配对文档：配对

7) 端到端验证

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

moltbot message send --target +15555550123 --message "你好，来自 Moltbot！"

如果 moltbot health 显示"未配置认证"，回到向导设置 OAuth/key 认证——没有认证智能体无法回复。

提示：moltbot status --all 是最佳的只读调试报告。

从源码运行（开发）

如果你想修改 Moltbot 本身，从源码运行：

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

如果你还没有全局安装，通过 pnpm moltbot ... 从仓库运行向导步骤。

下一步（可选，但很棒）

• macOS 菜单栏应用 + 语音唤醒：macOS 应用
• iOS/Android 节点：参考各平台文档
• 远程访问（SSH 隧道 / Tailscale Serve）：远程访问 和 Tailscale
• 常驻 / VPN 设置：远程访问