193 lines
5.0 KiB
Markdown
193 lines
5.0 KiB
Markdown
---
|
||
summary: "入门指南：从零到第一条消息（向导、认证、渠道、配对）"
|
||
read_when:
|
||
- 首次从零开始设置
|
||
- 你想要从安装→引导→第一条消息的最快路径
|
||
---
|
||
|
||
# 快速开始
|
||
|
||
目标：尽快从 **零** → **第一个运行的聊天**（使用合理的默认值）。
|
||
|
||
最快的聊天方式：打开控制 UI（无需渠道设置）。运行 `moltbot dashboard` 并在浏览器中聊天，或在网关主机上打开 `http://127.0.0.1:18789/`。
|
||
文档：[Dashboard](/web/dashboard) 和 [Control UI](/web/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（推荐）
|
||
|
||
```bash
|
||
curl -fsSL https://molt.bot/install.sh | bash
|
||
```
|
||
|
||
**Windows (PowerShell)：**
|
||
```powershell
|
||
iwr -useb https://molt.bot/install.ps1 | iex
|
||
```
|
||
|
||
**替代方案（全局安装）：**
|
||
```bash
|
||
npm install -g moltbot@latest
|
||
# 或
|
||
pnpm add -g moltbot@latest
|
||
```
|
||
|
||
---
|
||
|
||
## 2) 运行引导向导（并安装服务）
|
||
|
||
```bash
|
||
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) 启动网关
|
||
|
||
如果在引导期间安装了服务，网关应该已经在运行：
|
||
|
||
```bash
|
||
moltbot gateway status
|
||
```
|
||
|
||
**手动运行（前台）：**
|
||
```bash
|
||
moltbot gateway --port 18789 --verbose
|
||
```
|
||
|
||
**仪表板（本地回环）：** `http://127.0.0.1:18789/`
|
||
|
||
如果配置了令牌，将其粘贴到控制 UI 设置中。
|
||
|
||
⚠️ **Bun 警告（WhatsApp + Telegram）：** Bun 在这些渠道上有已知问题。如果使用 WhatsApp 或 Telegram，请用 **Node** 运行网关。
|
||
|
||
---
|
||
|
||
## 3.5) 快速验证（2 分钟）
|
||
|
||
```bash
|
||
moltbot status
|
||
moltbot health
|
||
moltbot security audit --deep
|
||
```
|
||
|
||
---
|
||
|
||
## 4) 配对 + 连接你的第一个聊天界面
|
||
|
||
### WhatsApp（二维码登录）
|
||
|
||
```bash
|
||
moltbot channels login
|
||
```
|
||
|
||
通过 WhatsApp → 设置 → 链接设备 扫描。
|
||
|
||
### Telegram / Discord / 其他
|
||
|
||
向导可以为你写入令牌/配置。如果偏好手动配置：
|
||
- Telegram：设置 `TELEGRAM_BOT_TOKEN` 环境变量或配置文件
|
||
- Discord：设置 `DISCORD_BOT_TOKEN` 环境变量
|
||
|
||
**Telegram DM 提示：** 你的第一个 DM 会返回一个配对码。需要批准它（见下一步），否则机器人不会响应。
|
||
|
||
---
|
||
|
||
## 5) DM 安全（配对批准）
|
||
|
||
默认行为：未知 DM 会收到一个短代码，消息在批准前不会被处理。
|
||
如果你的第一个 DM 没有收到回复，批准配对：
|
||
|
||
```bash
|
||
moltbot pairing list whatsapp
|
||
moltbot pairing approve whatsapp <code>
|
||
```
|
||
|
||
**注意：** Telegram 不使用配对，而是使用 `allowFrom` 配置：
|
||
|
||
```json5
|
||
{
|
||
channels: {
|
||
telegram: {
|
||
allowFrom: ["YOUR_USER_ID"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6) 从源码安装（开发）
|
||
|
||
```bash
|
||
git clone https://github.com/moltbot/moltbot.git
|
||
cd moltbot
|
||
pnpm install
|
||
pnpm ui:build # 首次运行会自动安装 UI 依赖
|
||
pnpm build
|
||
pnpm moltbot onboard --install-daemon
|
||
```
|
||
|
||
**网关（从此仓库）：**
|
||
```bash
|
||
node moltbot.mjs gateway --port 18789 --verbose
|
||
```
|
||
|
||
---
|
||
|
||
## 7) 端到端验证
|
||
|
||
在新终端中，发送测试消息：
|
||
|
||
```bash
|
||
moltbot message send --target +15555550123 --message "来自 Moltbot 的问候"
|
||
```
|
||
|
||
如果 `moltbot health` 显示 "no auth configured"，返回向导设置 OAuth/密钥认证——没有它助手无法响应。
|
||
|
||
**提示：** `moltbot status --all` 是最好的可粘贴、只读调试报告。
|
||
|
||
---
|
||
|
||
## 下一步（可选，但很棒）
|
||
|
||
- macOS 菜单栏应用 + 语音唤醒：[macOS 应用](/platforms/macos)
|
||
- iOS/Android 节点（Canvas/相机/语音）：[节点](/nodes)
|
||
- 远程访问（SSH 隧道 / Tailscale Serve）：[远程访问](/gateway/remote)
|