最近在尝试为QQ群增加一些趣味互动功能时发现很多开发者对“猫娘”这类角色扮演聊天机器人很感兴趣但往往卡在部署环节。网上的教程要么过于零散要么依赖复杂的服务器环境对新手不够友好。本文将分享一套在手机上快速部署猫娘QQ机器人的完整方案从零开始手把手带你完成环境搭建、代码编写和上线运行。无论你是想学习机器人开发还是单纯想给自己的小群增添一个可爱的AI伙伴这篇教程都能让你在半小时内拥有一个可对话的“猫娘”。1. 项目背景与核心概念1.1 什么是QQ机器人QQ机器人是一种能够自动响应QQ消息、执行特定任务如群管理、信息查询、娱乐互动的程序。它通过模拟QQ客户端登录接收和发送消息实现自动化交互。传统的QQ机器人开发需要处理复杂的QQ协议、反爬机制和服务器维护门槛较高。1.2 什么是“猫娘”机器人“猫娘”并非特指某个技术框架而是一种流行的机器人角色设定。它通常指代一个具有猫耳娘属性、能够进行拟人化、可爱风格对话的AI聊天机器人。其核心功能是智能对话可以根据用户的输入生成符合“猫娘”人设的回复。实现方式多样可以基于规则模板、本地AI模型或调用云端大语言模型如豆包、文心一言等的API。1.3 为什么选择在手机部署对于个人开发者或学生而言租用云服务器是一笔持续的开销且配置管理较为繁琐。而现代智能手机的性能已足够强大完全可以作为7x24小时运行的微型服务器。在手机上部署的优势在于零成本利用闲置手机无需额外服务器费用。便捷性随时随地通过手机管理无需电脑常开。低功耗相比电脑手机待机功耗更低。学习门槛低通过一些移动端开发工具可以简化环境配置过程。技术栈选择为了实现快速部署我们将采用一个成熟的Python QQ机器人框架——NoneBot2搭配官方适配的go-cqhttp协议端。对话能力则通过调用国内可访问的AI平台API如豆包来实现。2. 环境准备与工具说明在开始之前请确保你拥有一部安卓手机iOS系统限制较多不推荐并准备好以下工具。本文所有操作均可在手机端完成。2.1 核心工具清单Termux一个强大的安卓终端模拟器和Linux环境应用。它可以在不root手机的情况下提供一个完整的Linux命令行环境是我们部署Python项目的基础。AidLux或UserLAnd备选这类应用能提供更完整的图形化Linux桌面环境适合不熟悉命令行的用户。但Termux更轻量是本教程的首选。MT管理器或ES文件浏览器用于在手机本地管理文件方便查看和编辑代码。一个可用的QQ号用于机器人登录建议使用小号避免主号风险。2.2 安装与配置Termux从F-Droid官网或GitHub Releases页面下载Termux的APK文件并安装。请勿从Google Play安装旧版本。打开Termux首先更新软件包列表并升级现有包pkg update pkg upgrade -y安装必要的软件包Python、Git、Vim编辑器等。pkg install python git vim -y验证安装python --version git --version如果显示Python 3.x和Git版本号则环境准备就绪。2.3 获取API密钥以豆包为例为了让机器人能“聪明地”对话我们需要一个AI大脑。这里以字节跳动的豆包平台为例它提供了免费且易用的API。在手机浏览器中访问豆包官网注册并登录。进入控制台创建一个新应用。在应用详情中找到API Key或访问令牌并妥善保存。这个密钥将用于让我们的机器人调用豆包的对话能力。3. 核心组件原理与搭建我们的机器人架构主要分为两层协议层和应用层。协议层 (go-cqhttp)负责处理与QQ服务器的底层通信包括登录、接收消息、发送消息。它将以HTTP或WebSocket协议将消息事件转发给我们的应用层。应用层 (NoneBot2)一个基于Python的机器人框架负责处理业务逻辑。它接收协议层转发的事件根据我们编写的插件逻辑例如调用AI接口生成回复再通过协议层发送出去。3.1 部署协议端go-cqhttpgo-cqhttp是兼容OneBot协议的标准实现使用Go语言编写性能好且跨平台。下载可执行文件在Termux中我们下载适用于Linux ARM64架构的版本。# 进入一个工作目录 cd ~ mkdir qqbot cd qqbot # 从GitHub Release下载请替换为最新版本链接 # 可以使用Termux的curl或wget pkg install wget -y wget https://github.com/Mrs4s/go-cqhttp/releases/download/v1.0.0-rc4/go-cqhttp_linux_arm64.tar.gz # 解压 tar -zxvf go-cqhttp_linux_arm64.tar.gz # 给予执行权限 chmod x go-cqhttp首次运行并生成配置./go-cqhttp首次运行会因缺少配置文件而退出并在当前目录生成config.yml。配置config.yml使用vim或MT管理器编辑这个文件。vim config.yml找到并修改以下几处关键配置account: # 账号相关 uin: 1233456 # QQ账号填写机器人的QQ号 password: # 密码为空推荐使用扫码登录 encrypt: false # 是否开启密码加密默认false # 连接服务列表主要配置HTTP或WebSocket反向代理 servers: - http: host: 127.0.0.1 # 监听地址本地环回地址 port: 5700 # 监听端口 timeout: 5 # 请求超时 middlewares: : *default # 引用默认中间件 post: # 上报地址列表指向NoneBot2 - url: http://127.0.0.1:8080/onebot/v11/http # 重点NoneBot2默认上报地址 - ws-reverse: universal: ws://127.0.0.1:8080/onebot/v11/ws/ # 反向WebSocket地址连接更稳定 reconnect-interval: 3000 middlewares: : *default说明我们配置了HTTP和WebSocket两种方式上报事件给NoneBot2确保连接稳定。保存并退出编辑器。启动并扫码登录./go-cqhttp程序运行后会在终端显示一个二维码。使用手机QQ注意需要用机器人账号同属一个设备的QQ客户端扫描登录。成功后终端会提示登录成功信息。此时可按CtrlC暂时停止我们将先配置NoneBot2。3.2 部署应用框架NoneBot2NoneBot2是一个现代化、跨平台的Python机器人框架插件生态丰富。创建虚拟环境并安装在qqbot目录下操作。cd ~/qqbot python -m venv venv # 创建虚拟环境 source venv/bin/activate # 激活虚拟环境 (Termux中可能是 source venv/bin/activate) pip install nb-cli # 安装NoneBot脚手架使用脚手架创建项目nb create交互式命令行中按提示选择Project Name: 输入cat-girl-botRuntime Environment: 选择Simple(简单环境)其他选项可按回车使用默认值。 完成后会生成一个cat-girl-bot的目录。安装核心适配器和依赖cd cat-girl-bot pip install nonebot-adapter-onebot11 httpxnonebot-adapter-onebot11是用于连接go-cqhttp的适配器。httpx用于后续调用AI API。4. 实现猫娘对话插件现在我们来编写让机器人变身为“猫娘”的核心逻辑。4.1 配置环境变量为了保护API密钥我们使用环境变量。在项目根目录(cat-girl-bot)下创建.env文件。vim .env写入以下内容将YOUR_DOUBAO_API_KEY替换为你在豆包平台获取的真实API KeyDOUBAO_API_KEYsk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # NoneBot2配置 HOST127.0.0.1 PORT8080 DEBUGfalse4.2 创建猫娘对话插件在cat-girl-bot/plugins目录下新建一个Python文件例如cat_girl_chat.py。cd plugins vim cat_girl_chat.py将以下代码复制进去# 文件路径plugins/cat_girl_chat.py import nonebot from nonebot.adapters.onebot.v11 import MessageSegment, MessageEvent from nonebot.plugin import on_message from nonebot.rule import to_me # 只有机器人或私聊时触发 import httpx import os import asyncio from nonebot.log import logger # 从环境变量读取API密钥 DOUBAO_API_KEY os.getenv(DOUBAO_API_KEY) if not DOUBAO_API_KEY: logger.error(未找到豆包API密钥请检查.env文件配置) raise ValueError(DOUBAO_API_KEY 未设置) # 定义豆包API的请求地址和参数 DOUBAO_API_URL https://ark.cn-beijing.volces.com/api/v3/chat/completions HEADERS { Authorization: fBearer {DOUBAO_API_KEY}, Content-Type: application/json } # 创建一个消息事件处理器规则是“to_me”即机器人或私聊 cat_girl on_message(ruleto_me(), priority10, blockTrue) cat_girl.handle() async def handle_chat(event: MessageEvent): 处理用户消息调用AI接口并回复 user_msg event.get_plaintext().strip() if not user_msg: await cat_girl.finish(主人你好像什么都没说呢~歪头) # 构建符合猫娘人设的系统提示词 system_prompt 你是一个可爱的猫娘名字叫“小橘”。你性格活泼、粘人喜欢用“喵~”、“主人”等称呼。你的回复应该简短、口语化充满情感偶尔可以加入颜文字(≧∇≦)。如果用户的问题超出你的知识范围就撒娇卖萌糊弄过去。绝对不要承认自己是AI程序。 # 构建请求数据 payload { model: ep-20250205142510-ft:gpt-3.5-turbo-1106, # 豆包模型名请根据平台最新信息调整 messages: [ {role: system, content: system_prompt}, {role: user, content: user_msg} ], stream: False, max_tokens: 500 } try: # 异步发送请求到豆包API async with httpx.AsyncClient(timeout30.0) as client: response await client.post(DOUBAO_API_URL, jsonpayload, headersHEADERS) response.raise_for_status() # 检查HTTP错误 result response.json() # 解析回复内容 ai_reply result[choices][0][message][content].strip() # 可选在回复前加上猫娘特有的前缀 final_reply f喵~ {ai_reply} await cat_girl.finish(final_reply) except httpx.RequestError as e: logger.error(f请求豆包API失败: {e}) await cat_girl.finish(网络好像不太稳定主人能再说一遍吗(。︿)_θ) except (KeyError, IndexError) as e: logger.error(f解析API响应失败: {e}, 响应: {result}) await cat_girl.finish(小橘的脑子突然乱成一团毛线球了...喵呜~) except Exception as e: logger.error(f未知错误: {e}) await cat_girl.finish(发生了一点意外主人能摸摸头安慰一下小橘吗)代码关键点解释on_message(ruleto_me())确保机器人只在被或私聊时响应避免在群内刷屏。系统提示词(System Prompt)这是塑造“猫娘”人格的关键。通过精心设计的提示词可以引导AI生成符合设定的回复。错误处理网络请求可能失败API返回格式可能变化完善的异常处理能保证机器人不会因意外而崩溃并给出友好的错误回复。异步请求使用httpx.AsyncClient和async/await避免在等待AI回复时阻塞机器人处理其他消息。4.3 修改项目配置文件为了让NoneBot2加载我们的插件并使用OneBot v11适配器需要修改cat-girl-bot/pyproject.toml文件或bot.py取决于创建项目时的选择。这里以修改pyproject.toml为例# 部分关键配置 [tool.nonebot] plugins [nonebot_plugin_apscheduler] # 默认插件保留 plugin_dirs [plugins] # 指定插件目录我们的cat_girl_chat.py在此目录下 [tool.nonebot.adapter] extra_adapters [nonebot.adapters.onebot.v11] # 启用OneBot v11适配器 # 驱动配置 driver ~fastapi host 127.0.0.1 port 8080同时确保项目根目录下的.env.prod或.env文件我们之前创建的中的HOST和PORT与go-cqhttp配置中的上报地址(http://127.0.0.1:8080)一致。5. 启动与验证全流程5.1 启动NoneBot2应用在Termux中确保位于项目目录并激活了虚拟环境。cd ~/qqbot/cat-girl-bot source venv/bin/activate运行NoneBot2。使用nb run命令可以快速启动。nb run如果看到类似[INFO] NoneBot is initializing...和[INFO] Running on http://127.0.0.1:8080的日志说明应用层启动成功正在监听8080端口。5.2 启动go-cqhttp协议端打开另一个Termux会话可以通过滑动屏幕从左侧拉出菜单点击“新建会话”。在新会话中进入go-cqhttp所在目录并启动。cd ~/qqbot ./go-cqhttp程序会自动读取config.yml并尝试连接NoneBot2。在日志中你应该看到连接WebSocket或HTTP上报成功的消息例如[INFO]: 正在尝试连接到反向WebSocket服务器 ws://127.0.0.1:8080...和[INFO]: 反向WebSocket连接成功。5.3 功能测试在手机QQ上找到你登录了机器人账号的客户端。用自己的主QQ号向机器人账号发起私聊或者将机器人拉入一个QQ群。在私聊窗口或群聊中**机器人**并发送一句话例如“你好呀”。观察Termux中NoneBot2的日志应该能看到接收和发送消息的记录。如果一切正常你将收到一条带有“喵~”前缀、风格可爱的回复例如“喵~ 主人你好呀今天找小橘有什么事嘛(≧∇≦)”。6. 常见问题与排查思路在部署过程中你可能会遇到以下问题。请根据现象按顺序排查。问题现象可能原因排查步骤与解决方案Termux 无法安装包软件源问题或网络问题。1. 运行termux-change-repo选择镜像源如清华源。2. 执行pkg update --fix-missing。3. 检查手机网络连接。go-cqhttp 扫码登录失败1. 账号被风控。2. 扫码的QQ客户端与机器人账号不在同一设备。1. 确保用于扫码的QQ登录的正是机器人账号且在同一台手机上。2. 尝试在config.yml中配置account.password使用密码登录有安全风险。3. 更换一个QQ号尝试。NoneBot 启动报错ModuleNotFoundError依赖未安装或虚拟环境未激活。1. 确认在项目目录下执行了source venv/bin/activate。2. 运行pip list检查nonebot2,nonebot-adapter-onebot11,httpx是否存在。3. 缺失则用pip install安装。go-cqhttp 日志显示连接失败1. NoneBot2 未启动。2. 端口被占用或配置错误。3. IP地址错误。1. 确认NoneBot2已成功启动并监听在8080端口。2. 在Termux运行netstat -tunlp | grep 8080查看端口占用。3. 核对config.yml中的url和universal地址与NoneBot2的HOST、PORT完全一致均为127.0.0.1:8080。机器人能收到消息但不回复1. 插件未加载。2. 事件匹配规则问题。3. AI API调用失败。1. 检查NoneBot2启动日志看是否加载了cat_girl_chat插件。2. 确认私聊或了机器人to_me规则。3. 查看NoneBot2日志中的错误信息重点检查豆包API密钥是否正确、网络是否通畅。AI回复内容不符合猫娘人设系统提示词System Prompt不够精确。修改cat_girl_chat.py中的system_prompt变量。更详细地描述猫娘的背景、性格、说话习惯和禁忌。可以多参考网上的“角色扮演提示词”进行优化。手机锁屏后机器人掉线手机系统为省电杀死了后台进程。1. 进入手机系统设置为Termux和QQ应用开启“自启动”、“后台常驻”、“省电策略无限制”。2. 可以考虑使用tmux或screen在Termux内部会话运行但锁屏问题主要靠系统设置解决。7. 进阶优化与最佳实践一个基础的猫娘机器人上线后还可以从以下几个方面进行优化使其更稳定、更智能、更好玩。7.1 使用进程守护保持在线Termux会话关闭后进程会终止。可以使用nohup或tmux来守护进程。# 方法一使用nohup (在项目目录下) cd ~/qqbot/cat-girl-bot nohup nb run nb.log 21 cd ~/qqbot nohup ./go-cqhttp cqhttp.log 21 # 查看日志 tail -f nb.log tail -f cqhttp.log # 关闭进程可用 pkill -f “nb run” 和 pkill -f “go-cqhttp”7.2 丰富插件功能一个完整的机器人不应只有聊天功能。可以在plugins目录下创建更多插件群管插件自动欢迎新人、定时提醒、关键词过滤。娱乐插件抽签、占卜、讲笑话、成语接龙。实用插件天气查询、翻译、简易计算。 NoneBot2有丰富的插件市场可以通过nb plugin install命令安装社区插件。7.3 对话记忆与上下文目前的代码是“单轮对话”AI不记得之前的聊天内容。要实现多轮对话上下文记忆需要修改请求数据payload将历史对话记录也放入messages列表中。注意这会消耗更多的API Token。# 简化的上下文实现思路需要持久化存储用户对话历史 user_session_history {} # 用字典在内存中临时存储生产环境应用数据库 cat_girl.handle() async def handle_chat(event: MessageEvent): user_id event.user_id user_msg event.get_plaintext().strip() # 获取该用户的历史对话列表 history user_session_history.get(user_id, []) history.append({role: user, content: user_msg}) # 保持历史记录长度避免过长 if len(history) 10: # 只保留最近10轮对话 history history[-10:] payload { model: ..., messages: [system_msg] history, # 系统提示词 历史对话 stream: False, } # ... 发送请求并获取回复 ai_reply ... # 将AI回复也加入历史 history.append({role: assistant, content: ai_reply}) user_session_history[user_id] history # ... 回复用户7.4 安全与风控注意事项账号安全务必使用QQ小号并避免在机器人上登录重要账号。密码登录存在泄露风险扫码登录更安全。内容审核AI生成的内容不可控建议在回复前加入敏感词过滤逻辑或选择提供内容安全审核的AI服务商。API费用管理豆包等平台通常有免费额度但超出后会收费。在代码中加入使用量监控和限流逻辑避免意外消耗。遵守平台规则了解并遵守QQ群规及AI服务平台的使用条款避免滥用导致账号或服务被封禁。通过以上步骤你已经成功在手机上部署了一个具备基本智能对话能力的猫娘QQ机器人。这个项目不仅是一个有趣的玩具更是你学习Python异步编程、网络API调用、进程管理和服务部署的绝佳实践。你可以在此基础上不断迭代为她添加更多表情包回复、语音功能需协议支持、甚至简单的记忆模块让她变得更加独一无二。