手机零成本部署猫娘QQ机器人：基于NoneBot2与AI API的完整实践指南-育师

最近在尝试为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-cqhttp

go-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客户端）扫描登录。成功后，终端会提示登录成功信息。此时可按Ctrl+C暂时停止，我们将先配置NoneBot2。

3.2 部署应用框架：NoneBot2

NoneBot2是一个现代化、跨平台的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-bot
- Runtime Environment: 选择Simple(简单环境)
- 其他选项可按回车使用默认值。完成后，会生成一个cat-girl-bot的目录。
安装核心适配器和依赖：
```
cd cat-girl-bot pip install nonebot-adapter-onebot11 httpx
```
nonebot-adapter-onebot11是用于连接go-cqhttp的适配器。httpx用于后续调用AI API。

4. 实现猫娘对话插件

现在，我们来编写让机器人变身为“猫娘”的核心逻辑。

4.1 配置环境变量

为了保护API密钥，我们使用环境变量。在项目根目录(cat-girl-bot)下创建.env文件。

vim .env

写入以下内容（将YOUR_DOUBAO_API_KEY替换为你在豆包平台获取的真实API Key）：

DOUBAO_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # NoneBot2配置 HOST=127.0.0.1 PORT=8080 DEBUG=false

4.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": f"Bearer {DOUBAO_API_KEY}", "Content-Type": "application/json" } # 创建一个消息事件处理器，规则是“to_me”（即@机器人或私聊） cat_girl = on_message(rule=to_me(), priority=10, block=True) @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(timeout=30.0) as client: response = await client.post(DOUBAO_API_URL, json=payload, headers=HEADERS) 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(rule=to_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 2>&1 & cd ~/qqbot nohup ./go-cqhttp > cqhttp.log 2>&1 & # 查看日志 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调用、进程管理和服务部署的绝佳实践。你可以在此基础上不断迭代，为她添加更多表情包回复、语音功能（需协议支持）、甚至简单的记忆模块，让她变得更加独一无二。