KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #typescript #ai-agent #developer-tools #claude-code #codex #deepseek-harness #ai-agents #react #mcp #rust

xbot

★ 97 Open GitHub ↗

ws版本xbot

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 🤖 xbot 机器人项目 🤖

> ## ⚠️ 免责声明
>
> **本项目仅供学习交流使用，严禁用于商业用途！**
> 使用本项目所产生的一切法律责任和风险，由使用者自行承担，与项目作者无关。
> 请遵守相关法律法规，合法合规使用本项目。

## 📝 项目概述

xbot 是一个智能机器人系统，提供了丰富的交互体验。
本项目只用于学习交流，不在提供 wechat 协议。可自行拓展接入微信企业官方机器人，钉钉，飞书等机器人。

## 📚 项目文档

- [**系统架构文档**](docs/系统架构文档.md) - 系统组件和架构详解
- [**插件开发指南**](docs/插件开发指南.md) - 如何开发自定义插件
- [**配置指南**](docs/配置指南.md) - 系统配置详细说明
- [**用户手册**](docs/用户手册.md) - 用户使用指南
- [**API 文档**](docs/API文档.md) - 系统 API 接口文档

### 🔄 双协议支持与框架模式

本系统现已支持多种微信协议：

#### 协议版本支持

- **pad 协议**
- **ipad 协议**
- **mac 协议**

#### 框架模式支持

- **wechat**：

通过在 `main_config.toml` 文件中设置 `Protocol.version` 和 `Framework.type` 参数，系统会自动选择相应的服务和 API 路径。详细配置方法请参见[协议配置](#协议配置)部分。

选择不同的协议版本和框架模式，可以满足不同用户的需求，提供更灵活的交互体验。

#### 🔧 协议配置

在 `main_config.toml` 文件中，配置 `Protocol.version` 和 `Framework.type` 参数来选择协议版本和框架模式：

```toml
[Protocol]
version = "ipad"  # 可选值：pad, ipad, Mac
```

## 🚀 快速开始

### OpenClaw 过渡接入

当前仓库已加入 OpenClaw/ilink 过渡通道，可在现有 WechatAPI 不可用时先切换使用。

1. 在 `main_config.toml` 中设置：

```toml
[Framework]
type = "wechat"
channel = "openclaw"

[OpenClaw]
base-url = "https://ilinkai.weixin.qq.com"
bot-type = "3"
credentials-file = "resource/openclaw_account.json"
message-mode = "http"
```

2. 首次启动后，后台状态会进入“等待微信扫码登录”，二维码链接会写入 `admin/bot_status.json`。
3. 用微信完成扫码确认后，凭据会保存到 `resource/openclaw_account.json`。
4. 后续重启会优先复用该凭据，并通过 `ilink/bot/getupdates` 长轮询收消息。

> 当前过渡版优先保证文本消息主链路可用；图片发送、更多联系人详情等高级能力仍按旧 WechatAPI 能力为准。

<table>
  <tr>
    <td width="50%">
      <h3>💬 加入 xbot 交流群</h3>
      <p>扫描右侧的二维码加入官方交流群，获取：</p>
      <ul>
        <li>💡 <strong>最新功能更新</strong>和使用技巧</li>
        <li>👨‍💻 <strong>技术支持</strong>和问题解答</li>
        <li>👥 与其他用户<strong>交流经验</strong></li>
        <li>📝 <strong>插件开发</strong>和定制化帮助</li>
      </ul>
    </td>
    <td width="25%" align="center">
      <img src="https://github.com/user-attachments/assets/39f6eff3-bcaa-4bdf-87f2-fd887c26a4e7" alt="关注公众号进群" width="220">
      <p><strong>xbot 交流群</strong></p>
    </td>
  </tr>
</table>

## ✨ 主要特性

### 1. 💻 管理后台

- 📊 **控制面板**：系统概览、机器人状态监控
- 🔌 **插件管理**：安装、配置、启用/禁用各类功能插件
- 📁 **文件管理**：上传、查看和管理机器人使用的文件
- 📵 **联系人管理**：微信好友和群组联系人管理
- 📈 **系统状态**：查看系统资源占用和运行状态

### 2. 💬 聊天功能

- 📲 **私聊互动**：与单个用户的一对一对话
- 👥 **群聊响应**：在群组中通过@或特定命令触发
- 📞 **聊天室模式**：支持多人持续对话，带有用户状态管理
- 💰 **积分系统**：对话消耗积分，支持不同模型不同积分定价
- 📸 **朋友圈功能**：支持查看、点赞和评论朋友圈

### 3. 🤖 智能对话

- 🔍 **多模型支持**：可配置多种 AI 模型，支持通过关键词切换
- 📷 **图文结合**：支持图片理解和多媒体输出
- 🖼️ **[引用图片识别](引用图片识别功能说明.md)**：通过引用图片消息让 AI 分析图片内容
- 🎤 **语音交互**：支持语音输入识别和语音回复
- 😍 **语音撒娇**：支持甜美语音撒娇功能

### 4. 🔗 插件系统

- 🔌 **插件管理**：支持加载、卸载和重载插件
- 🔧 **自定义插件**：可开发和加载自定义功能插件
- 🤖 **Dify 插件**：集成 Dify API，提供高级 AI 对话能力
- ⏰ **定时提醒**：支持设置定时提醒和日程管理
- 👋 **群欢迎**：自动欢迎新成员加入群聊
- 🌅 **早安问候**：每日早安问候功能

## 📍 安装指南

### 📦 系统要求

- 🐍 Python 3.11+
- 📱 WX 客户端
- 🔋 Redis（用于数据缓存）
- 🎥 FFmpeg（用于语音处理）
- 🐳 Docker（可选，用于容器化部署）

### 📝 安装步骤

#### 🔹 方法一：直接安装

1. **克隆代码库**

```bash
   git clone https://github.com/NanSsye/xbot.git
   cd xbot
   ```

2. **安装依赖**

```bash
   pip install -r requirements.txt
   ```

3. **安装 Redis**

- Windows: 下载 Redis for Windows
   - Linux: `sudo apt-get install redis-server`
   - macOS: `brew install redis`

4. **安装 FFmpeg**

- Windows: 下载安装包并添加到系统 PATH
   - Linux: `sudo apt-get install ffmpeg`
   - macOS: `brew install ffmpeg`

5. **配置**

- 复制 `main_config.toml.example` 为 `main_config.toml` 并填写配置
   - 设置管理员 ID 和其他基本参数

**设置管理员：**

在 `main_config.toml` 文件中的 `[XYBot]` 部分设置管理员：

```toml
   [XYBot]
   # 管理员微信ID，可以设置多个，用英文逗号分隔
   admins = ["wxid_l2221111", "wxid_l111111"]  # 管理员的wxid列表，可从消息日志中获取
   ```

**设置 GitHub 加速代理：**

在 `main_config.toml` 文件中的 `[XYBot]` 部分设置 GitHub 加速代理：

```toml
   [XYBot]
   # GitHub加速服务设置
   # 可选值: "", "https://ghfast.top/", "https://gh-proxy.com/", "https://mirror.ghproxy.com/"
   # 空字符串表示直连不使用加速
   # 注意: 如果使用加速服务，请确保以"/"结尾
   github-proxy = "https://ghfast.top/"
   ```

**设置系统通知功能：**

在 `main_config.toml` 文件中配置系统通知功能（微信离线、重连、重启等通知）：

```toml
   # 系统通知设置
   [Notification]
   enabled = true                      # 是否启用通知功能
   token = "your_pushplus_token"       # PushPlus Token，必须在这里设置！
   channel = "wechat"                  # 通知渠道：wechat(微信公众号)、sms(短信)、mail(邮件)、webhook、cp(企业微信)
   template = "html"                   # 通知模板
   topic = ""                          # 群组编码，不填仅发送给自己

# 通知触发条件
   [Notification.triggers]
   offline = true                      # 微信离线时通知
   reconnect = true                    # 微信重新连接时通知
   restart = true                      # 系统重启时通知
   error = true                        # 系统错误时通知

# 通知模板设置
   [Notification.templates]
   offlineTitle = "警告：微信离线通知 - {time}"  # 离线通知标题
   offlineContent = "您的微信账号 <b>{wxid}</b> 已于 <span style=\"color:#ff4757;font-weight:bold;\">{time}</span> 离线，请尽快检查您的设备连接状态或重新登录。"  # 离线通知内容
   reconnectTitle = "微信重新连接通知 - {time}"  # 重连通知标题
   reconnectContent = "您的微信账号 <b>{wxid}</b> 已于 <span style=\"color:#2ed573;font-weight:bold;\">{time}</span> 重新连接。"  # 重连通知内容
   restartTitle = "系统重启通知 - {time}"  # 系统重启通知标题
   restartContent = "系统已于 <span style=\"color:#1e90ff;font-weight:bold;\">{time}</span> 重新启动。"  # 系统重启通知内容
   ```

❗ **重要提示：**

- PushPlus Token 必须在 `main_config.toml` 文件中直接设置，而不是通过网页界面设置
   - 如果通过网页界面设置，可能会导致容器无法正常启动
   - 请先在 [PushPlus 官网](http://www.pushplus.plus/) 注册并获取 Token

在 `main_config.toml` 文件中添加以下配置来选择微信协议版本：

```toml
   [Protocol]
   version = "ipad"  # 可选值：pad, ipad, Mac
   ```

- **pad 协议**
- **ipad 协议**
- **mac**

系统会根据配置的协议版本自动选择正确的服务路径和 API 路径前缀。

在 `main_config.toml` 文件中添加以下配置来选择框架模式：

```toml
[Framework]
type = "wechat"
```

6. **启动必要的服务**

**需要先启动 Redis 和 PAD 服务**（注意启动顺序！）：

### 🏠 Windows 用户

- ❗ **第一步**：启动 Redis 服务 🔋

- 进入 `redis` 目录，双击 `redis-server.exe` 文件
     - 等待窗口显示 Redis 启动成功

- ❗ **第二步**：启动 PAD 服务 📱

- 根据你的协议版本选择相应的服务：
       - 直接启动 docker 容器：xbot-wechat
       - 映射 9011 和 9088 两个端口

- ⚠️ 请确保这两个服务窗口始终保持打开状态，不要关闭它们！

**然后启动主服务**：

```bash
   python main.py
   ```

### 💻 Linux 用户

- ❗ **第一步**：启动 Redis 服务 🔋

```bash
     # 进入Redis目录
     cd redis

# 使用Linux配置文件启动Redis
     redis-server redis.linux.conf
     ```

- 如果 Redis 未安装，需要先安装：

```bash
     # Ubuntu/Debian
     sudo apt-get update
     sudo apt-get install redis-server

# CentOS/RHEL
     sudo yum install redis
     ```

- ❗ **第二步**：启动 PAD 服务 📱

根据你的协议版本选择相应的服务：

- 直接启动 docker 容器：xbot-wechat
     - 映射 9011 和 9088 两个端口

- ⚠️ 请确保这两个服务进程保持运行状态，可以使用如下命令检查：

```bash
     # 检查Redis服务
     ps aux | grep redis

```

**然后启动主服务**：

```bash
   python main.py
   ```

#### 🔺 方法二：Docker 安装 🐳

1. **使用 Docker Compose 启动 xbot（默认按 `main_config.toml` 选择通道）**

```bash
   # 克隆代码库
   git clone https://github.com/NanSsye/xbot.git
   cd xbot

# 首次构建并启动
   docker compose up -d --build
   ```

2. **如果使用 OpenClaw 过渡通道**

请确保 `main_config.toml` 中为：

```toml
   [Framework]
   type = "wechat"
   channel = "openclaw"

[OpenClaw]
   base-url = "https://ilinkai.weixin.qq.com"
   credentials-file = "resource/openclaw_account.json"
   ```

容器启动后会自动：

- 安装 `openclaw`
   - 安装本仓库内置的 `weixin-cli-source/package`
   - 后台执行 `weixin-installer install`
   - 将 OpenClaw 状态持久化到 Docker 卷 `xbot-openclaw-state`

查看安装日志：

```bash
   docker exec -it xbot tail -f /app/logs/openclaw-bootstrap.log
   ```

首次登录如果需要扫码，按日志提示完成即可。登录凭据会保存在挂载的 `resource/` 和 OpenClaw 状态卷中，后续重启会复用。

3. **如果继续使用旧 WechatAPI 通道**

修改配置为：

```toml
   [Framework]
   type = "wechat"
   channel = "wechatapi"
   ```

然后额外启动旧协议容器：

```bash
   docker compose --profile wechatapi up -d
   ```

这会额外启动 `xbot-wechat` 服务并暴露 `9011/9088/9010` 端口。

4. **常用命令**

```bash
   docker logs -f xbot
   docker exec -it xbot tail -f /app/logs/openclaw-bootstrap.log
   docker exec -it xbot /bin/bash
   ```

### 🔍 访问后台

- 🌐 打开浏览器访问 `http://localhost:9090` 进入管理界面
- 👤 默认用户名：`admin`
- 🔑 默认密码：`admin1234`

### 🤖 Dify 插件配置

```toml
[Dify]
enable = true
default-model = "model1"
command-tip = true
commands = ["ai", "机器人", "gpt"]
admin_ignore = true
whitelist_ignore = true
http-proxy = ""
voice_reply_all = false
robot-names = ["机器人", "小助手"]
remember_user_model = true
chatroom_enable = true

[Dify.models.model1]
api-key = "your_api_key"
base-url = "https://api.dify.ai/v1"
trigger-words = ["dify", "小d"]
price = 10
wakeup-words = ["你好小d", "嘿小d"]
```

## 📖 使用指南

详细使用指南请参考[用户手册](docs/用户手册.md)。

## 🔌 插件开发

想要开发自己的插件？请参考[插件开发指南](docs/插件开发指南.md)了解详细信息。

## 🔴 常见问题

1. **安装依赖失败** 💻

- 尝试使用 `pip install --upgrade pip` 更新 pip
   - 可能需要安装开发工具: `apt-get install python3-dev`

2. **语音识别失败** 🎤

- 确认 FFmpeg 已正确安装并添加到 PATH
   - 检查 SpeechRecognition 依赖是否正确安装

3. **无法连接微信** 📱

- 确认微信客户端和接口版本是否匹配
   - 检查网络连接和端口设置
   - 如果使用 PAD 协议，确认 PAD 服务是否正常运行
   - ⚠️ Windows 用户请确认是否按正确顺序启动服务：先启动 Redis，再启动 PAD
   - 检查 `main_config.toml` 中的协议版本设置是否正确（849 用于 iPad，855 用于安卓 PAD）

4. **Redis 连接错误** 🔋

- 确认 Redis 服务器是否正常运行
   - 🔴 Windows 用户请确认是否已启动 `849/redis` 目录中的 `redis-server.exe`
   - 检查 Redis 端口和访问权限设置
   - 确认配置文件中的 Redis 端口是否为 6378
   - 💡 提示：Redis 窗口应显示"已就绪接受指令"或类似信息

5. **Dify API 错误** 🤖

- 验证 API 密钥是否正确
   - 确认 API URL 格式和访问权限

6. **Docker 部署问题** 🐳

- 确认 Docker 容器是否正常运行：`docker ps`
   - 查看容器日志：`docker logs xbot`
   - 重启容器：`docker-compose restart`
   - 查看卷数据：`docker volume ls`
   - 💡 注意：Docker 容器内会自动启动 PAD 和 Redis 服务，无需手动启动
   - 如果需要切换协议版本，只需修改 `main_config.toml` 中的 `Protocol.version` 设置并重启容器
   - ⚠️ Windows 用户注意：Docker 容器使用的是 Linux 环境，不能直接使用 Windows 版的可执行文件

7. **无法访问管理后台** 🛑

- 确认服务器正常运行在 9090 端口
   - 尝试使用默认账号密码: admin/admin1234
   - 检查防火墙设置是否阻止了端口访问

## 🏗️ 技术架构

详细架构信息请参考[系统架构文档](docs/系统架构文档.md)。

## 📜 协议和许可

### ⚠️ 重要免责声明

- **本项目仅供学习和研究使用，严禁用于任何商业用途**
- **使用前请确保符合微信和相关服务的使用条款**
- **使用本项目所产生的一切法律责任和风险，由使用者自行承担，与项目作者无关**
- **请遵守相关法律法规，合法合规使用本项目**
- **如果您使用了本项目，即表示您已阅读并同意上述免责声明**

## 🙏 鸣谢

本项目的开发离不开以下作者和项目的支持与贡献：

<table style="border-collapse: collapse; border: none;">
  <tr style="border: none;">
    <td width="180" align="center" style="border: none; padding: 10px;">
      <div style="border-radius: 50%; overflow: hidden; width: 120px; height: 120px; margin: 0 auto;">
        <img src="https://avatars.githubusercontent.com/u/83214045" width="120" height="120">
      </div>
      <br>
      <strong style="font-size: 16px;">HenryXiaoYang</strong>
      <br>
      <a href="https://github.com/HenryXiaoYang" style="text-decoration: none; color: #0366d6;">个人主页</a>
    </td>
    <td style="border: none; padding: 10px;">
      <p style="margin-bottom: 8px; font-size: 15px;">项目：<a href="https://github.com/HenryXiaoYang/XYBotV2" style="text-decoration: none; color: #0366d6;">XYBotV2</a> - 本项目的重要参考源</p>
      <p style="margin-top: 0; font-size: 15px;">提供了微信机器人的基础架构和核心功能，为本项目的开发提供了宝贵的参考。</p>
    </td>
  </tr>
  <tr style="border: none;">
    <td width="180" align="center" style="border: none; padding: 10px;">
      <div style="border-radius: 50%; overflow: hidden; width: 120px; height: 120px; margin: 0 auto;">
        <img src="https://avatars.githubusercontent.com/u/178422005" width="120" height="120">
      </div>
      <br>
      <strong style="font-size: 16px;">heaven2028</strong>
      <br>
      <a href="https://github.com/heaven2028" style="text-decoration: none; color: #0366d6;">个人主页</a>
    </td>
    <td style="border: none; padding: 10px;">
      <p style="margin-bottom: 8px; font-size: 15px;">与本项目作者共同完成的开发工作</p>
      <p style="margin-top: 0; font-size: 15px;">在功能扩展、界面设计和系统优化方面做出了重要贡献。</p>
    </td>
  </tr>
</table>

同时感谢所有其他贡献者和使用的开源项目。

## 📞 联系方式

- **GitHub**: [https://github.com/NanSsye](https://github.com/NanSsye)
- **官方交流群**：请查看上方[快速开始](#快速开始)部分的二维码

## 💻 管理后台界面展示

# 已还原为同步消息处理方式，无需 Celery 和 Redis 队列，消息由主循环直接分发处理。

xbot

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README