215 lines
6.1 KiB
Markdown
215 lines
6.1 KiB
Markdown
# MoltBot
|
||
|
||
MoltBot 是一个运行在你自己设备上的个人 AI 助手。它集成了多个消息平台（WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、iMessage、Microsoft Teams、WebChat），并在所有频道上提供 AI 驱动的帮助。
|
||
|
||
## 功能特性
|
||
|
||
- **多频道支持**：WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、iMessage、BlueBubbles、Microsoft Teams、Matrix、Zalo、WebChat
|
||
- **本地优先网关**：会话、频道、工具和事件的统一控制平面
|
||
- **多代理路由**：将入站频道路由到具有独立会话的隔离代理
|
||
- **语音唤醒 + 对话模式**：macOS/iOS/Android 上的永久在线语音支持（使用 ElevenLabs）
|
||
- **实时画布**：由代理驱动的可视化工作空间，支持 A2UI
|
||
- **一流工具**：浏览器、画布、节点、定时任务、会话和特定频道的操作
|
||
- **配套应用**：macOS 菜单栏应用 + iOS/Android 节点
|
||
- **技能平台**：内置、托管和工作区技能，支持安装门控
|
||
|
||
## 快速开始
|
||
|
||
1. 复制示例环境文件：
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
2. 生成安全的网关令牌：
|
||
|
||
```bash
|
||
# 使用 OpenSSL
|
||
openssl rand -hex 32
|
||
|
||
# 或使用 Python
|
||
python3 -c "import secrets; print(secrets.token_hex(32))"
|
||
```
|
||
|
||
3. 编辑 `.env` 文件，至少设置：
|
||
- `MOLTBOT_GATEWAY_TOKEN` - 你生成的令牌
|
||
- `ANTHROPIC_API_KEY` 或 `OPENAI_API_KEY` - 如果使用 API 密钥认证
|
||
|
||
4. 启动网关：
|
||
|
||
```bash
|
||
docker compose up -d
|
||
```
|
||
|
||
5. 访问控制界面：
|
||
- 在浏览器中打开 <http://localhost:18789>
|
||
- 在提示时输入你的网关令牌
|
||
|
||
## 配置
|
||
|
||
### 网关访问
|
||
|
||
网关可以通过两种方式访问：
|
||
|
||
- **回环地址**（`MOLTBOT_GATEWAY_BIND=loopback`）：仅从主机访问（127.0.0.1）
|
||
- **局域网**（`MOLTBOT_GATEWAY_BIND=lan`）：从本地网络访问（0.0.0.0）
|
||
|
||
对于生产部署，建议：
|
||
|
||
- 使用 Tailscale Serve/Funnel 进行安全的远程访问
|
||
- 设置 SSH 隧道
|
||
- 实现带认证的反向代理
|
||
|
||
### 模型配置
|
||
|
||
MoltBot 支持多个 AI 模型提供商：
|
||
|
||
- **Anthropic Claude**（推荐）：Claude Pro/Max，支持 OAuth 或 API 密钥
|
||
- **OpenAI**：ChatGPT/Codex，支持 OAuth 或 API 密钥
|
||
- **自定义提供商**：通过控制界面或配置文件进行配置
|
||
|
||
在 `.env` 文件中设置 API 密钥，或通过入门向导使用 OAuth 认证。
|
||
|
||
### 频道集成
|
||
|
||
连接消息平台：
|
||
|
||
1. **WhatsApp**：使用 CLI 链接设备
|
||
|
||
```bash
|
||
docker compose run --rm moltbot-cli channels login
|
||
```
|
||
|
||
2. **Telegram**：在配置中设置 `TELEGRAM_BOT_TOKEN`
|
||
|
||
3. **Discord**：在配置中设置 `DISCORD_BOT_TOKEN`
|
||
|
||
4. **Slack**：在配置中设置 `SLACK_BOT_TOKEN` 和 `SLACK_APP_TOKEN`
|
||
|
||
详细设置说明请参阅[官方文档](https://docs.molt.bot/channels)。
|
||
|
||
## 使用命令行界面
|
||
|
||
CLI 服务可通过 `cli` 配置文件使用：
|
||
|
||
```bash
|
||
# 运行入门向导
|
||
docker compose run --rm --service-ports moltbot-cli onboard
|
||
|
||
# 列出提供商
|
||
docker compose run --rm moltbot-cli providers list
|
||
|
||
# 发送消息
|
||
docker compose run --rm moltbot-cli message send --to +1234567890 --message "你好"
|
||
|
||
# 检查健康状态
|
||
docker compose run --rm moltbot-cli health --port 18789
|
||
```
|
||
|
||
## 安全注意事项
|
||
|
||
1. **网关令牌**：保护好你的网关令牌。这是控制界面和 WebSocket 连接的认证方式。
|
||
|
||
2. **私信访问**：默认情况下，MoltBot 对来自未知发送者的私信使用配对模式。他们会收到一个配对码，你必须批准。
|
||
|
||
3. **网络暴露**：如果在 localhost 之外暴露网关，请使用适当的认证和加密：
|
||
- 设置 Tailscale 进行安全的远程访问
|
||
- 使用 SSH 隧道
|
||
- 实现带 HTTPS 和认证的反向代理
|
||
|
||
4. **API 密钥**：永远不要将 API 密钥提交到版本控制。使用 `.env` 文件或密钥管理。
|
||
|
||
5. **沙箱模式**：为了群组/频道安全，启用沙箱模式以在 Docker 容器中运行非主会话。
|
||
|
||
## 高级配置
|
||
|
||
### 资源限制
|
||
|
||
在 `.env` 文件中调整 CPU 和内存限制：
|
||
|
||
```env
|
||
MOLTBOT_CPU_LIMIT=2.0
|
||
MOLTBOT_MEMORY_LIMIT=2G
|
||
MOLTBOT_CPU_RESERVATION=1.0
|
||
MOLTBOT_MEMORY_RESERVATION=1G
|
||
```
|
||
|
||
### 持久化数据
|
||
|
||
数据存储在两个 Docker 卷中：
|
||
|
||
- `moltbot_config`：配置文件和凭据（~/.clawdbot）
|
||
- `moltbot_workspace`：代理工作区和技能（~/clawd）
|
||
|
||
备份数据：
|
||
|
||
```bash
|
||
docker run --rm -v moltbot_config:/data -v $(pwd):/backup alpine tar czf /backup/moltbot-config-backup.tar.gz /data
|
||
docker run --rm -v moltbot_workspace:/data -v $(pwd):/backup alpine tar czf /backup/moltbot-workspace-backup.tar.gz /data
|
||
```
|
||
|
||
### 自定义配置文件
|
||
|
||
在 `~/.clawdbot/moltbot.json`（容器内）创建自定义配置文件：
|
||
|
||
```json
|
||
{
|
||
"agents": {
|
||
"defaults": {
|
||
"model": {
|
||
"primary": "anthropic/claude-opus-4-5",
|
||
"fallbacks": ["anthropic/claude-sonnet-4-5", "openai/gpt-4o"]
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 故障排除
|
||
|
||
### 网关无法启动
|
||
|
||
1. 检查日志：`docker compose logs moltbot-gateway`
|
||
2. 验证网关令牌是否在 `.env` 中设置
|
||
3. 确保端口 18789 未被占用
|
||
|
||
### 无法访问控制界面
|
||
|
||
1. 验证网关绑定设置是否与你的访问方式匹配
|
||
2. 如果从另一台机器访问，检查防火墙规则
|
||
3. 确保容器健康：`docker compose ps`
|
||
|
||
### 模型 API 错误
|
||
|
||
1. 验证 API 密钥是否在 `.env` 中正确设置
|
||
2. 检查 API 密钥有效性和配额
|
||
3. 查看日志中的具体错误消息
|
||
|
||
### 运行诊断命令
|
||
|
||
诊断命令可帮助诊断常见问题：
|
||
|
||
```bash
|
||
docker compose run --rm moltbot-cli doctor
|
||
```
|
||
|
||
## 文档
|
||
|
||
- [官方网站](https://molt.bot)
|
||
- [完整文档](https://docs.molt.bot)
|
||
- [入门指南](https://docs.molt.bot/start/getting-started)
|
||
- [配置参考](https://docs.molt.bot/gateway/configuration)
|
||
- [安全指南](https://docs.molt.bot/gateway/security)
|
||
- [Docker 安装](https://docs.molt.bot/install/docker)
|
||
- [GitHub 仓库](https://github.com/moltbot/moltbot)
|
||
|
||
## 许可证
|
||
|
||
MoltBot 使用 MIT 许可证发布。详情请参阅 [LICENSE](https://github.com/moltbot/moltbot/blob/main/LICENSE) 文件。
|
||
|
||
## 社区
|
||
|
||
- [Discord](https://discord.gg/clawd)
|
||
- [GitHub 讨论](https://github.com/moltbot/moltbot/discussions)
|
||
- [问题跟踪](https://github.com/moltbot/moltbot/issues)
|