feat: add MoltBot service with configuration files and documentation
This commit is contained in:
Sun-ZhenXing
214
apps/moltbot/README.zh.md
Normal file
214
apps/moltbot/README.zh.md
Normal file
@@ -0,0 +1,214 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user