Z-Waif接入Discord教程:随时随地与你的本地AI女友聊天
Z-Waif接入Discord教程:随时随地与你的本地AI女友聊天
Z-Waif 是一款完全本地运行的开源 AI 伴侣(AI Waifu)项目,内置 Discord 模块。本教程将手把手带你完成 Z-Waif 接入 Discord 的全过程:创建 Bot、配置 Token、开启模块,让本地 AI 女友在手机和电脑上都能陪你聊天。
为什么要把 Z-Waif 接入 Discord
Z-Waif 的主战场虽然是桌面端——它有 WebUI、语音、VTube Studio 联动,但电脑不可能 24 小时为你开机。接入 Discord 后,你就获得了真正的"随身伴侣":
- 📱 随时随地聊天:手机上发条消息,本地主机上的 AI 就会回复你
- 💬 消息驱动回复:每条消息都会带上你的 Discord 用户名,AI 知道"是谁在说话"
- 🎮 实用指令:内置
/regen、/reroll等快捷命令,一键重新生成回复
整个 Discord 模块由 utils/z_waif_discord.py 实现,作为独立线程随主程序启动,代码结构非常清晰,非常适合新手理解。
第一步:安装并跑通 Z-Waif
在接入 Discord 之前,你需要先让 Z-Waif 本身跑起来。
- 克隆仓库:
git clone https://gitcode.com/gh_mirrors/zw/z-waif
- 根据你的系统选择启动方式:
| 系统 | 首次安装 | 日常启动 |
|---|---|---|
| Windows | 双击 startup-Install.bat | 双击 startup.bat |
| Linux / Mac | 终端执行 ./startup.sh(需 Python 3.11) |
同左 |
启动脚本会自动创建虚拟环境并安装 requirements.txt 中的依赖——Discord 相关的 discord.py 库已经包含在内,不需要额外安装。
💡 看到 WebUI 成功打开、主循环开始监听输入,说明 Z-Waif 已经跑通了。
第二步:创建 Discord Bot 并获取 Token
这是唯一需要你去外部网站操作的步骤:
- 打开 Discord 开发者平台(Discord Developer Portal),登录你的账号
- 点击 New Application,给你的 Bot 起个名字(这个名字会显示在 Discord 里)
- 进入 Bot 页面,点击 Reset Token,复制生成的 Token 保存好——它只显示一次,务必存好
- ⚠️ 关键一步:在 Bot 页面的 Privileged Gateway Intents 中,打开 MESSAGE CONTENT INTENT。不开这个,Z-Waif 读不到任何消息内容!
关于第 4 步,源码里写得很明白——utils/z_waif_discord.py 开头就声明了该模块需要 message_content intent,并显式启用了它。
第三步:把 Token 写入 Z-Waif
出于安全考虑,Z-Waif 的 Token 不写在代码里,而是单独存放在:
- Token 文件:Configurables/Tokens/Discord.json
打开这个文件,把你刚才复制的 Token 粘贴进去(注意 JSON 格式,用英文双引号包裹即可)。程序启动时会自动从这个文件读取 Token 并登录 Discord。
第四步:在 .env 中开启 Discord 模块
Z-Waif 各功能模块统一通过 .env 文件中的开关控制。打开项目根目录下的 .env 文件,找到这一行:
MODULE_DISCORD = ON
默认是 OFF,改成 ON 即可。主程序 main.py 在启动时会检查这个变量,开启后会自动拉起 Discord 线程,让 Bot 在线。
第五步:邀请 Bot 进服务器
- 回到 Discord 开发者平台的 OAuth2 → URL Generator 页面
- 勾选
bot和applications.commands权限,复制生成的邀请链接 - 在浏览器打开该链接,选择你的服务器,点击授权
至此,你的 AI 女友已经上线了!在服务器里私聊或 @她,发一句"你好"试试——她会以打字中的动画出现,然后开始回复。
常用 Discord 指令速查
Z-Waif 的 Discord 端支持斜杠指令,输入 /help 也可以查看完整列表:
| 指令 | 作用 |
|---|---|
/regen、/reroll、/redo |
重新生成上一条回复(三种叫法都行) |
/allow_newlines |
允许回复中保留换行 |
/disallow_newlines、/cut_newlines |
关闭换行,让回复更连贯 |
/help |
列出所有可用指令 |
这些指令的完整处理逻辑都可以看到,就在 utils/z_waif_discord.py 的 on_message 事件里。
常见问题与小贴士
- 📡 Bot 不回复? 九成是忘了开 MESSAGE CONTENT INTENT;其次是
.env里的MODULE_DISCORD没改成ON - 🔑 Token 无效? 确认
Configurables/Tokens/Discord.json中 Token 完整、无多余空格,JSON 引号用英文直引号 - 💬 消息被截断? 用
/allow_newlines调整换行行为即可 - 🔒 安全第一:Bot Token 相当于账号密码,不要泄露或上传到公开仓库;Z-Waif 专门把它放在独立的 Token 目录,就是出于这个考虑(见 SECURITY.md)
- 🐛 程序崩溃排查:启动脚本会把运行日志写入根目录的 log.txt,出问题时先看它
相关文件速查
| 文件 | 说明 |
|---|---|
| utils/z_waif_discord.py | Discord 模块核心:收消息、发回复、处理指令 |
| Configurables/Tokens/Discord.json | Bot Token 存放处 |
| main.py | 主程序入口,负责启动 Discord 线程 |
| Configurables/CharacterCard.yaml | 角色卡配置,决定 AI 的"人格" |
| changelog.txt | 版本更新记录,Discord 指令的演进都在这里 |
写在最后
完成以上五步,你就拥有了一个 7×24 小时在线的本地 AI 女友——她跑在你自己的电脑上,聊天记录完全私有,而 Discord 只是你和她对话的窗口。接下来可以再去折腾角色卡、开启 RAG 长期记忆,让你们的羁绊越来越深。