d53dffca83
feat(openclaw): introduce OpenClaw personal AI assistant with multi-channel support and CLI fix(mineru): update MinerU version to 2.7.6 in Dockerfile and documentation
270 lines
6.6 KiB
Markdown
270 lines
6.6 KiB
Markdown
# Nanobot
|
||
|
||
[中文说明](README.zh.md) | [English](README.md)
|
||
|
||
Nanobot 是一个轻量级、生产就绪的个人 AI 助手，支持多渠道（Telegram、Discord、WhatsApp、飞书），本地模型集成，以及强大的工具能力。
|
||
|
||
## 特性
|
||
|
||
- 🤖 **多 LLM 提供商支持**：OpenRouter、Anthropic、OpenAI、DeepSeek、Groq、Gemini 等
|
||
- 🖥️ **本地模型**：使用 vLLM 或任何 OpenAI 兼容服务器运行您自己的模型
|
||
- 💬 **多渠道**：集成 Telegram、Discord、WhatsApp 和飞书
|
||
- 🛠️ **强大工具**：文件操作、Shell 执行、网络搜索和自定义技能
|
||
- 📅 **定时任务**：支持自然语言的类 Cron 任务调度
|
||
- 🎯 **记忆与技能**：持久化记忆和可扩展技能系统
|
||
- 🔒 **安全性**：沙盒模式、访问控制和安全命令执行
|
||
|
||
## 快速开始
|
||
|
||
### 前置要求
|
||
|
||
- 已安装 Docker 和 Docker Compose
|
||
- 至少一个 LLM 提供商 API 密钥（推荐：[OpenRouter](https://openrouter.ai/keys)）
|
||
|
||
### 配置步骤
|
||
|
||
1. **复制环境变量示例文件：**
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
2. **编辑 `.env` 并至少配置一个 LLM 提供商：**
|
||
|
||
```bash
|
||
# 使用 OpenRouter（推荐，可访问所有模型）
|
||
OPENROUTER_API_KEY=sk-or-v1-xxxxx
|
||
|
||
# 或使用其他提供商
|
||
ANTHROPIC_API_KEY=sk-ant-xxxxx
|
||
OPENAI_API_KEY=sk-xxxxx
|
||
```
|
||
|
||
3. **启动服务：**
|
||
|
||
```bash
|
||
docker compose up -d
|
||
```
|
||
|
||
4. **初始化配置（仅首次需要）：**
|
||
|
||
```bash
|
||
docker compose exec nanobot nanobot onboard
|
||
```
|
||
|
||
5. **检查状态：**
|
||
|
||
```bash
|
||
docker compose exec nanobot nanobot status
|
||
```
|
||
|
||
## 使用方法
|
||
|
||
### CLI 模式
|
||
|
||
直接与 nanobot 对话：
|
||
|
||
```bash
|
||
docker compose exec nanobot nanobot agent -m "2+2 等于多少？"
|
||
```
|
||
|
||
交互模式：
|
||
|
||
```bash
|
||
docker compose exec nanobot nanobot agent
|
||
```
|
||
|
||
### 网关模式（默认）
|
||
|
||
默认的 `docker compose up` 会启动网关服务器，支持：
|
||
|
||
- Telegram 机器人集成
|
||
- Discord 机器人集成
|
||
- WhatsApp 消息（需要额外配置）
|
||
- 飞书 / Lark 集成
|
||
- HTTP API 访问（端口 18790）
|
||
|
||
### 渠道配置
|
||
|
||
#### Telegram
|
||
|
||
1. 通过 Telegram 上的 [@BotFather](https://t.me/BotFather) 创建机器人
|
||
2. 从 [@userinfobot](https://t.me/userinfobot) 获取您的用户 ID
|
||
3. 在 `.env` 中配置：
|
||
|
||
```bash
|
||
TELEGRAM_ENABLED=true
|
||
TELEGRAM_TOKEN=你的机器人令牌
|
||
```
|
||
|
||
4. 重启服务
|
||
|
||
#### Discord
|
||
|
||
1. 在 [Discord 开发者门户](https://discord.com/developers/applications) 创建机器人
|
||
2. 在机器人设置中启用 **MESSAGE CONTENT INTENT**
|
||
3. 在 `.env` 中配置：
|
||
|
||
```bash
|
||
DISCORD_ENABLED=true
|
||
DISCORD_TOKEN=你的机器人令牌
|
||
```
|
||
|
||
4. 重启服务
|
||
|
||
#### WhatsApp
|
||
|
||
需要 Node.js 和额外配置。详见 [官方文档](https://github.com/HKUDS/nanobot#-chat-apps)。
|
||
|
||
#### 飞书
|
||
|
||
1. 在 [飞书开放平台](https://open.feishu.cn/app) 创建应用
|
||
2. 启用机器人能力并添加 `im:message` 权限
|
||
3. 在 `.env` 中配置：
|
||
|
||
```bash
|
||
FEISHU_ENABLED=true
|
||
FEISHU_APP_ID=你的应用ID
|
||
FEISHU_APP_SECRET=你的应用密钥
|
||
```
|
||
|
||
4. 重启服务
|
||
|
||
## 配置
|
||
|
||
### 环境变量
|
||
|
||
所有可用配置选项请参见 [.env.example](.env.example)。
|
||
|
||
关键设置：
|
||
|
||
| 变量 | 描述 | 默认值 |
|
||
| ----------------------- | -------------------------------------- | --------------------------- |
|
||
| `NANOBOT_MODEL` | 要使用的 LLM 模型 | `anthropic/claude-opus-4-5` |
|
||
| `NANOBOT_COMMAND` | 要运行的命令（gateway、agent、status） | `gateway` |
|
||
| `RESTRICT_TO_WORKSPACE` | 沙盒模式 - 限制工具访问工作空间 | `false` |
|
||
| `BRAVE_API_KEY` | 网络搜索工具的 API 密钥 | （空） |
|
||
| `TELEGRAM_ENABLED` | 启用 Telegram 渠道 | `false` |
|
||
| `DISCORD_ENABLED` | 启用 Discord 渠道 | `false` |
|
||
|
||
### LLM 提供商优先级
|
||
|
||
当配置了多个提供商时，nanobot 将：
|
||
|
||
1. 根据模型名称匹配提供商（例如 `gpt-4` → OpenAI）
|
||
2. 回退到第一个可用的 API 密钥
|
||
|
||
### 安全性
|
||
|
||
对于生产部署：
|
||
|
||
- 设置 `RESTRICT_TO_WORKSPACE=true` 以沙盒化所有文件和 Shell 操作
|
||
- 在配置文件中为渠道访问控制配置 `allowFrom` 列表
|
||
- 为渠道集成使用专用用户账户
|
||
- 监控 API 使用并设置支出限制
|
||
- 将凭证保存在环境变量中，绝不在代码中
|
||
|
||
## 定时任务
|
||
|
||
按计划运行任务：
|
||
|
||
```bash
|
||
# 添加每日提醒
|
||
docker compose exec nanobot nanobot cron add \
|
||
--name "morning" \
|
||
--message "早上好！今天有什么安排？" \
|
||
--cron "0 9 * * *"
|
||
|
||
# 列出计划任务
|
||
docker compose exec nanobot nanobot cron list
|
||
|
||
# 删除任务
|
||
docker compose exec nanobot nanobot cron remove <job_id>
|
||
```
|
||
|
||
## 本地模型（vLLM）
|
||
|
||
使用您自己的本地模型运行 nanobot：
|
||
|
||
1. **启动 vLLM 服务器：**
|
||
|
||
```bash
|
||
vllm serve meta-llama/Llama-3.1-8B-Instruct --port 8000
|
||
```
|
||
|
||
2. **在 `.env` 中配置：**
|
||
|
||
```bash
|
||
VLLM_API_KEY=dummy
|
||
VLLM_API_BASE=http://host.docker.internal:8000/v1
|
||
NANOBOT_MODEL=meta-llama/Llama-3.1-8B-Instruct
|
||
```
|
||
|
||
3. **重启服务**
|
||
|
||
## 数据卷
|
||
|
||
- `nanobot_config`：配置文件和凭证
|
||
- `nanobot_workspace`：代理工作空间和文件
|
||
|
||
## 端口
|
||
|
||
- `18790`：网关 HTTP API（可通过 `NANOBOT_PORT_OVERRIDE` 配置）
|
||
|
||
## 资源限制
|
||
|
||
默认资源限制：
|
||
|
||
- CPU：1.0 核心（限制），0.5 核心（预留）
|
||
- 内存：1GB（限制），512MB（预留）
|
||
|
||
通过环境变量调整：`NANOBOT_CPU_LIMIT`、`NANOBOT_MEMORY_LIMIT` 等。
|
||
|
||
## 故障排除
|
||
|
||
### 查看日志
|
||
|
||
```bash
|
||
docker compose logs -f nanobot
|
||
```
|
||
|
||
### 验证配置
|
||
|
||
```bash
|
||
docker compose exec nanobot nanobot status
|
||
```
|
||
|
||
### 测试 LLM 连接
|
||
|
||
```bash
|
||
docker compose exec nanobot nanobot agent -m "你好！"
|
||
```
|
||
|
||
### 常见问题
|
||
|
||
**未配置 API 密钥：**
|
||
|
||
- 确保在 `.env` 中至少设置了一个提供商 API 密钥
|
||
- 更新环境变量后重启服务
|
||
|
||
**渠道无响应：**
|
||
|
||
- 检查渠道是否在 `.env` 中启用
|
||
- 验证机器人令牌是否正确
|
||
- 检查日志中的连接错误
|
||
|
||
**文件权限错误：**
|
||
|
||
- 确保数据卷具有适当的权限
|
||
- 调试时尝试使用 `RESTRICT_TO_WORKSPACE=false` 运行
|
||
|
||
## 许可证
|
||
|
||
Nanobot 是一个开源项目。许可证详情请参见 [官方仓库](https://github.com/HKUDS/nanobot)。
|
||
|
||
## 链接
|
||
|
||
- 官方仓库：<https://github.com/HKUDS/nanobot>
|
||
- 文档：<https://github.com/HKUDS/nanobot#readme>
|
||
- 问题反馈：<https://github.com/HKUDS/nanobot/issues>
|