# 微信 AI 机器人小白安装教程

## 一、准备条件

- 一台 Ubuntu 20.04、22.04 或 24.04 服务器，建议至少 2 核 4 GB 内存。
- 可以登录网页版微信的微信号。部分新号或受限制账号可能无法扫码登录，这不是代码故障。
- 至少一个可用的文字模型 API。默认启动命令使用 MiniMax。
- 生图、配音、音乐、Hermes 都是可选功能，没有对应配置时可不启用。

## 二、上传并解压

把下载的压缩包上传到服务器，例如 `/opt`，然后执行：

```bash
cd /opt
tar -xzf wechat-ai-bot-source-20260717.tar.gz
cd wechat-ai-bot
```

如果你的面板可以在线解压，也可以解压后进入 `wechat-ai-bot` 目录。

## 三、一键安装环境

Ubuntu/Debian 执行：

```bash
sudo bash install.sh
```

脚本会安装 Node.js、项目依赖、FFmpeg、PDF 工具和中文 OCR。首次安装通常需要几分钟。

## 四、填写配置

执行：

```bash
nano .env.hermes
```

最少需要填写：

```dotenv
BOT_NAME=home
ALIAS_WHITELIST=允许私聊机器人的微信昵称
ROOM_WHITELIST=允许使用机器人的群名
WECHAT_ADMIN_NAMES=管理员微信昵称
MINIMAX_API_KEY=你的文字模型密钥
MINIMAX_MODEL=你的MiniMax模型名
```

多个昵称或群名使用英文逗号分隔。配置文件里不要加多余引号，也不要把密钥发给别人。

可选功能：

- AI 生图：填写 `IMAGE_API_BASE_URL` 和 `IMAGE_API_KEY`。
- AI 配音/音乐：填写 `MINIMAX_AUDIO_KEY`，必要时修改 `MINIMAX_AUDIO_BASE_URL`。
- Hermes：先单独安装 Hermes，再设置 `HERMES_WECHAT_ENABLED=true`、路径和白名单。

保存方式：按 `Ctrl+O`、回车，然后按 `Ctrl+X`。

## 五、第一次扫码登录

执行：

```bash
./bot.sh run
```

终端会显示二维码。使用微信扫码并确认登录。看到登录成功后，可以先在微信里测试一条消息。

要退出前台运行，按 `Ctrl+C`。然后改为后台运行：

```bash
./bot.sh start
```

## 六、常用管理命令

```bash
./bot.sh status    # 查看是否运行
./bot.sh logs      # 实时查看日志，退出日志按 Ctrl+C
./bot.sh restart   # 修改配置或代码后重启
./bot.sh stop      # 停止机器人
./bot.sh run       # 前台运行，适合扫码和排错
```

## 七、微信里的基本用法

```text
菜单
/生图 一只坐在窗边的橘猫
/生图2K 产品摄影，白色背景
/配音 欢迎使用微信机器人
/音乐 温暖流行｜今天阳光正好
/视频解析 <受支持的视频分享链接>
```

群聊必须真正艾特机器人后再输入命令。机器人会原生艾特发起人回复。

管理员可以在群里使用：

```text
@home 功能状态
@home 开启生图
@home 关闭生图
@home 开启配音
@home 关闭音乐
@home 关闭视频解析
@home 关闭全部付费功能
```

## 八、授权音频转码

仅处理你拥有版权或已经获得授权的音频：

1. 私聊机器人发送 MP3、WAV、FLAC、M4A 等真实音频文件。
2. 收到暂存提示后发送 `/授权音频`。
3. 机器人转成微信兼容 MP3 并回传。
4. 原文件和转码文件会在上传满 24 小时后自动清理。

## 九、常见问题

### 没有二维码

执行 `./bot.sh logs` 查看错误。首次扫码建议用 `./bot.sh run`，不要直接后台启动。

### 扫码后无法登录

部分微信账号不允许网页版登录。可以换一个长期正常使用、能登录网页版微信的账号测试。

### 群里不回复

确认群名已写入 `ROOM_WHITELIST`，并且消息中是真正艾特机器人，不是手打 `@home`。

### 私聊不回复

确认对方昵称或通讯录备注在 `ALIAS_WHITELIST` 中，修改后执行 `./bot.sh restart`。

### 生图、配音或音乐失败

检查对应 API 地址、密钥和余额。执行 `./bot.sh logs` 查看接口错误，但不要把完整日志公开发送，因为日志可能包含聊天内容。

### PDF 扫描件识别失败

安装脚本默认安装中文 OCR。可执行 `tesseract --list-langs`，确认包含 `chi_sim` 和 `eng`。

### 视频解析失败

第三方平台会不定期修改页面。机器人会先用主解析接口，失败后自动使用备用接口，但私密、失效或受限内容仍可能无法解析。只下载你有权保存的内容。

## 十、安全提醒

- `.env.hermes` 权限应为 `600`，不要上传到网盘、GitHub 或聊天群。
- 不要公开微信登录状态文件、聊天记录和运行日志。
- 初次部署后立即修改管理员昵称和所有白名单。
- 昵称可以修改，生产环境建议进一步绑定稳定联系人 ID。
- 定期更新系统和 npm 依赖，外网服务器应启用防火墙和 SSH 密钥登录。