目标:一个能用自己小号跟你私聊、会发语音、记得上文、偶尔主动找你的角色。跑在云服务器上,7×24 在线,面板走 SSH 隧道不暴露公网。
没图形界面不是问题,关键是端口怎么访问、Docker 装没装、目录权限别搞错。
cat /etc/os-release | head -2
nproc && free -h && df -h /
fallocate -l 2G /swapfile && chmod 600 /swapfile && mkswap /swapfile && swapon /swapfile),但会卡。Ubuntu / Debian:
curl -fsSL https://get.docker.com | sh
systemctl enable --now docker
docker compose version
CentOS / Rocky / Alma:
dnf -y install dnf-plugins-core
dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
dnf -y install docker-ce docker-ce-cli containerd.io docker-compose-plugin
systemctl enable --now docker
/etc/docker/daemon.json:{"registry-mirrors":["https://docker.1ms.run","https://docker.xuanyuan.me"]}systemctl restart docker。加速站会失效,拉不动就换一个。① 默认用户是 ubuntu,不是 root。所有要写系统目录的命令前面加 sudo。
② 你的本机密钥不一定在服务器上。装密钥时如果选的是「创建新密钥对」,那把 RSA 私钥只在下载那一刻存在过。想让本机免密登录,得把本机公钥追加进服务器的 ~/.ssh/authorized_keys:
mkdir -p ~/.ssh && chmod 700 ~/.ssh
echo '你的公钥内容' >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys
本机公钥用 cat ~/.ssh/id_ed25519.pub 看。追加用 >>,别覆盖。
③ 给 ubuntu 加 docker 权限,否则每条 docker 命令都要 sudo:
sudo usermod -aG docker $USER
newgrp docker
在你本地 Windows 上执行(把 IP 换成你的):
scp -r C:/Users/LENOVO/WorkBuddy/2026-10-21-09-42-34/qq-companion ubuntu@192.144.189.143:/home/ubuntu/
然后登服务器:
ssh ubuntu@192.144.189.143
cd /home/ubuntu/qq-companion
chmod +x server-init.sh
nano docker-compose.yml # 把 WEBUI_TOKEN 改成你自己的密码
mkdir -p /home/ubuntu/qq-companion && nano /home/ubuntu/qq-companion/docker-compose.yml,把内容粘进去。我把 compose 里的端口绑成了 127.0.0.1,公网压根连不到,安全。你要在自己电脑上开条隧道进去:
ssh -N -L 6185:127.0.0.1:6185 -L 6099:127.0.0.1:6099 ubuntu@192.144.189.143
Windows 自带 OpenSSH,直接在 PowerShell 里跑这条,窗口别关。然后浏览器打开:
这三样没有,后面一步都做不下去。先备齐再开工。
注册一个专门给机器人用的号。别用你的主号,理由在最下面的风险一节。
注册完先正常登录一次手机 QQ,挂一天左右,让号「活」一点,新注册就上协议端容易被风控。
推荐 DeepSeek(便宜、中文好、OpenAI 兼容)。去 platform.deepseek.com 注册,充值 10 块,在「API keys」里创建一个,复制出来存好——只显示一次。
想省钱也可以先不充值,用你已有的其它 OpenAI 兼容服务(豆包、通义、硅基流动都行),后面填 Base URL 就行。
跑在服务器上就没「电脑关机」的问题了,但要确认:云厂商到期别忘续费、别手贱关机、安全组不用开任何入站端口(隧道走的是 SSH 22)。
AstrBot 是「大脑 + 面板」,NapCat 是「QQ 协议端」。两个都跑在 Docker 里,彼此用容器网络互通,不用配 IP。
在服务器上编辑 /home/ubuntu/qq-companion/docker-compose.yml,把 change-me-to-your-own-token 换成一串你自己的密码(16 位以上,字母数字混合)。这就是 NapCat 面板的登录密码,记下来。
顺手确认端口那两行是 127.0.0.1:6185:6185 和 127.0.0.1:6099:6099——前面带 127.0.0.1 才是只本地可访问。
cd /home/ubuntu/qq-companion
chmod +x server-init.sh
./server-init.sh
脚本会建目录、修权限、拉镜像、启动,最后把登录密码和下一步提示打出来。第一次拉镜像几百 MB,慢的话等几分钟。
不想用脚本,等价于这四条:
mkdir -p data napcat/config ntqq
chown -R 1000:1000 data napcat ntqq
docker compose pull
docker compose up -d
docker save/load 过去。cd /home/ubuntu/qq-companion
docker compose logs astrbot | grep -iE "password|密码" | tail -5
新版首次启动会随机生成密码打在日志里。找不到就试默认的 astrbot / astrbot。
这一步等于「用一个特殊客户端登录 QQ」,之后所有消息都由它转发。
登录成功后首页会显示你的 QQ 头像和昵称,状态是「在线」。
QQ 协议端会出现「被踢下线」「登录失效」的情况,尤其头几天。重启 NapCat 会重新出码:
cd /home/ubuntu/qq-companion
docker compose restart napcat
docker compose logs -f napcat
日志里会打出二维码链接,点开扫码。刷不出来就还是用 6099 的 WebUI 页面,更直观。
判断是否在线的最快方式:docker compose ps 显示 napcat 是 Up,不代表 QQ 在线——必须看 WebUI 首页的状态。
关键一步:AstrBot 开一个「反向 WebSocket」口子,NapCat 把消息推过去。协议叫 OneBot v11。
6185 → 左侧「消息平台 / 机器人」→ 右上「+ 创建机器人」。qq1,勾选「启用」。0.0.0.0,端口 6199。ws://astrbot:6199/ws
astrbot 是容器名,Docker 内部 DNS 自动解析,不要写 127.0.0.1(那是容器自己)。Array,心跳间隔 5000,重连间隔 5000。docker compose logs -f astrbot
出现类似 aiocqhttp(OneBot v11) 适配器已连接 就通了。这时用大号给小号发一句话,应该在几秒内收到回复。
没配模型时它不会说话。这一步填 API Key。
deepseek-chat。现在用大号发「你好」,应该能收到正常回复了。先跑通再美化人设,不要一开始就折腾提示词。
这一步没有技术含量,但决定成败。默认的 AI 腔是「客服味」,必须用规则压掉。
模板里已经写了,但你要理解为什么:
如果想要「话多、粘人、连发消息」的类型,光改人格不够,还得开分段回复。否则它想连发三条也只能挤成一条长消息发出来。
1.5,3.5 秒。太密像机器刷屏,太疏像掉线。开了之后,超过 40 字的回复会按标点拆成两三条依次发出,中间停一两秒——这就是「连着打字」的观感。
连续发 20 条,把这几种情况记下来,回去改提示词:
这是实拍踩到的坑:机器人一会儿叫「小渔」、一会儿写成别的,怎么都不稳定。翻数据库才发现——人格里根本没有任何地方写过名字。
成因很隐蔽:本地 人格模板.txt 的第一行是「你是「小渔」,一个 20 岁的普通女生」,但当初往面板里粘贴时,这一行漏掉了,数据库里只剩从【说话方式】开始的部分。模型不知道叫什么,只能从聊天记录里捡一个词当名字,于是写法飘忽。
正确做法是单独开一段,把身份写清楚,并且禁止它跟着别人的错字走:
【你是谁】
- 你叫小鱼,20 岁,普通女孩,不是助手也不是机器人。
- 问你是谁,就答「小鱼」,不要解释来源。
- 有人写成「小渔」,那是他打错字了,你自己永远写「小鱼」。
怀疑名字没生效,直接翻库看实际存了什么(AstrBot 的人格在 SQLite 里,不在配置文件里):
sudo python3 -c "import sqlite3;c=sqlite3.connect('/home/ubuntu/qq-companion/data/data_v4.db');print(c.execute('SELECT system_prompt FROM personas').fetchone()[0][:400])"
声音是「像不像人」的一半。这一章先选对供应商,再谈音色克隆。走错路会白烧一周。
| 路线 | 代表音色 | 钱 | 结论 |
|---|---|---|---|
| 豆包语音合成 2.0(火山引擎) | 甜美桃子、Vivi、甜美小源等官方音色 | 免费 20000 字符 / 半年,超出 3 元/万字符 | 线上就用这个:不用买槽位、音色自带、直接能听 |
| Edge TTS | zh-CN-XiaoxiaoNeural | 完全免费,不用 Key | 兜底用。能听,但一股播报味,撑不起陪伴感 |
| 硅基流动 CosyVoice2 | alex、以及上传素材自己复刻 | 有免费额度 | 别选,实测发闷,见下面的复盘 |
longhua_v2 只有 2.5%、longanran 只有 0.1%——原生比复刻还差,说明是模型层面的问题,调 pitch_rate 一点用没有。/api/v1/mega_tts/status 返回 load grant not found,就下了「Key 有效」的结论。后来拿一个全 0 的假 Key 再打一遍,返回一模一样——这个接口根本区分不了有效和无效。真正能验证的是新接口:返回 45000030 [resource_id=...] requested resource not granted 才说明「鉴权过了,只是没开通这个资源」。别拿一个不区分对错的接口做验证。用的是火山引擎的「语音合成 2.0」,走 v3 接口。这套接口只要一个 X-Api-Key,不需要 APP ID——旧版 /api/v1/mega_tts/* 才需要 Access Token,两者不通用,别混。
zh_female_tianmeitaozi_uranus_bigtts(甜美桃子,实测基频 320Hz,最亮)、zh_female_vv_uranus_bigtts(Vivi,302Hz)、zh_female_tianmeixiaoyuan_uranus_bigtts(甜美小源)。数字越大不代表越好,实听为准。smart_tts 插件配置(见 6.6 节),或者直接调接口试。手动试一条(把 sk-xxx 换成你的 Key,返回值是一串按行分隔的 JSON,每行 data 字段 base64 解出来就是 mp3 片段):
curl -X POST 'https://openspeech.bytedance.com/api/v3/tts/unidirectional' \
-H 'X-Api-Key: sk-xxx' \
-H 'X-Api-Resource-Id: seed-tts-2.0' \
-H 'X-Api-Request-Id: 00000000-0000-0000-0000-000000000000' \
-H 'Content-Type: application/json' \
-d '{
"user": {"uid": "test"},
"req_params": {
"text": "今天好累啊,不想动了",
"speaker": "zh_female_tianmeitaozi_uranus_bigtts",
"audio_params": {"format": "mp3", "sample_rate": 24000}
}
}'
| 返回码 / 报错 | 含义 | 怎么办 |
|---|---|---|
401 load grant not found | 鉴权没过 | Key 错了或没开通。注意:假 Key 返回一模一样,别拿来当验证 |
45000030 ... not granted | 鉴权过了,但没开这个资源 | 去控制台开对应服务,开通后大约 20 分钟才生效 |
55000000 resource ID mismatched | resource_id 和服务类型对不上 | 合成用 seed-tts-2.0,复刻用 seed-icl-2.0,两套授权分开 |
{"code":20000000,"message":"OK","data":null} | 正常,流结束标记 | 这是结尾,不是错误,别当异常抛 |
不花一分钱,不用申请 Key。如果只是想先把「能出声」这条链路跑通,或者豆包额度用完了不想续费,就用它。
本项目用的是自建镜像(Dockerfile 里装了 edge-tts),smart_tts 插件里保底逻辑也挂在它上面:豆包失败自动回退 Edge TTS,保证消息不会因为语音挂了而发不出去。
语音引擎 edge
Voice zh-CN-XiaoxiaoNeural # 晓晓,标准女声
zh-CN-XiaoyiNeural # 晓伊,更年轻
zh-CN-liaoning-XiaobeiNeural # 东北话
注意 NapCat 官方镜像里没有 edge-tts,直接用会报模块找不到,得自己 Dockerfile 装一层。
trigger_probability 先填 0.3~0.5,随便聊两句,确认链路通:data/temp/ 下会出现 mp3,QQ 里能收到语音条。0。后面 6.6 节的插件要接管判断,内置这条必须闭嘴,否则一条消息会被转两次语音。docker compose restart astrbot(只有这一次值得重启)。ErrType: 1 ErrCode: 3),伴随 ApiNotAvailable,看着像代码坏了,其实是被风控。之后改插件配置走「插件重载」,改框架配置走 POST /api/config/astrbot/update,都别重启容器。想让她的声音像某个特定的人,就得用「声音复刻」(火山那边叫 seed-icl-2.0,和合成是两套独立授权)。价格:音色槽位 110.40 元(原价 138),一个槽位一个音色,除非你确认听感真的过得了关,否则这笔钱先按住。
seed-icl-2.0 管复刻,seed-tts-2.0 管合成,开通一个不等于开通另一个。如果真要做,素材这四条比参数重要得多:
| 原则 | 为什么 | 反例(都实测踩过) |
|---|---|---|
| 短而纯 优于 长而杂 | 模型从素材里取「平均音色」,杂的东西会被当成音色的一部分学进去 | 55 秒素材里含扮 GPT、扮饲养员、扮鱼的腔调,复刻出来基频只有 246Hz,而参考真人 348Hz;音域从 249Hz 缩到 119Hz |
保持 44.1kHz,别 -ar 16000 | 样本率不是越高越好的问题,是先降再升补不回来 | 直接转 16k 再送进去,高频细节永久丢失 |
绝不做 silenceremove | 它会切出几十个断点,听起来就是「杂声」 | 一段素材过滤波后 SNR 从 48.3dB 掉到 35.8dB,底噪涨 4 倍,制造 10 处波形突变 |
| 录音环境 > 一切后处理 | 11 万块的算法救不了 20 块的麦克风 | 用 47kbps 视频音轨当素材,编码噪声被一起学进去 |
结论:录 30 秒安静环境的真人原声,比拿一段视频音轨去算法降噪强十倍。没有干净素材就别花这个钱。
AstrBot 内置的触发逻辑是纯掷骰子:每条回复 random() <= 概率,跟内容一点关系没有。所以「我困了」会变成语音,讲正事也会变成语音;反过来该有情绪的时候又恰好没触发。
解决办法是 astrbot_plugin_smart_tts(项目里自带)。思路:把内置概率设成 0 让它闭嘴,插件接管判断。
| 回复类型 | 触发概率 | 判断依据 |
|---|---|---|
| 情绪化 | 85% | 连串感叹号、哈哈/呜呜/啊啊、想你/讨厌/笑死、句尾语气词,累加分 ≥ 2 |
| 普通 | 15% | 剩下的,纯随机,保留一点惊喜 |
| 跳过 | — | 不到 6 字、超过 120 字、带链接/代码、带图片 |
插件里另有一组「引擎」参数,决定用谁发声。线上这套:
| 配置项 | 线上值 | 说明 |
|---|---|---|
tts_engine | doubao | 可选 doubao / edge,doubao 失败会自动回落 edge |
doubao_api_key | sk-... | 火山 X-Api-Key |
doubao_resource_id | seed-tts-2.0 | 合成资源。写成复刻的 seed-icl-2.0 会 403 |
doubao_speaker | zh_female_tianmeitaozi_uranus_bigtts | 甜美桃子 |
doubao_sample_rate | 24000 | 输出 mp3 采样率 |
部署(目录 data/plugins/astrbot_plugin_smart_tts/,三个文件:main.py / metadata.yaml / _conf_schema.json):
sudo chown -R 1000:1000 /home/ubuntu/qq-companion/data/plugins
cd /home/ubuntu/qq-companion
docker restart astrbot
启动日志出现 [smart_tts] 已加载,配置:... 就成功了。之后在面板「插件管理」里能调参数,不用改代码。
urllib,必须用 asyncio.to_thread 包一层,否则阻塞整个事件循环,QQ 那边会感觉「卡住」;for line in resp 逐行 json.loads,每行 data 字段 base64 解码后追加写文件;code=20000000 是正常结束,判定要写 code not in (0, 20000000, None),只判 == 0 会每句话刷一条报错。on_decorating_result 钩子抢在内置 TTS 之前执行。所以必须把内置的 trigger_probability 设成 0,否则两边都触发,一条消息会被转两次语音。emotional_probability 降到 0.6;觉得太安静就把 emotion_threshold 降到 1(句尾「啦」「哟」也算情绪)。插件出错会自己回退成文字,不会让消息发不出去。AstrBot 自带分段回复,默认已经开着(platform_settings.segmented_reply.enable = true),但用起来经常发现「她明明打了三行,结果挤在一个气泡里」。
不是插件坏了,是切分规则对不上她的说话方式。默认正则是 .*?[。?!~…]+|.+$,只认句末标点。可陪伴人格通常要求口语、短句——她压根不打句号,全靠换行断句。正则匹配不到标点,就落到 .+$ 兜底,再叠加 DOTALL 让 . 吞掉换行,整段被当成一块收下。
| 写法 | 她的回复 | 切出几条 |
|---|---|---|
默认 .*?[。?!~…]+|.+$ | 好,那路上慢点\n\n今天下班算早的\n\n到家跟我说一句 | 1 条(整段) |
改成 [^\n。?!~…]+[。?!~…]* | 同上 | 3 条,各发各的 |
改成 [^\n。?!~…]+[。?!~…]* | 今天天气不错。我出门了啊。 | 2 条,标点保留,不退化 |
新正则的意思:用「不是换行也不是句末标点」的字符连续成块,后面跟零个或多个标点。换行和句号都能切,且不会产生捕获组——框架按 re.findall 的结果直接当字符串用,一旦正则里出现 ( ) 捕获组,返回值变成元组,代码会把它丢掉。
顺带把 words_count_threshold 从 40 提到 80:这个值是分段门槛,超过长度的回复直接不分段。她稍长一点的话就整条发出来了,提到 80 更合适。
# 改法一:面板 → 配置 → 平台设置 → 分段回复,改两项
分段回复正则 [^\n。?!~…]+[。?!~…]*
分段阈值 80
# 改法二:接口热更新(不用重启容器)
POST /api/config/astrbot/update
{"config": <完整 cmd_config.json 内容>, "conf_id": "default"}
# provider_sources / provider / platform 三项服务端会自动保留,不会被覆盖
cmd_config.json 启动时才加载进内存,改文件不重启不生效,重启还可能触发腾讯的登录态风控(见第 7.3 节)。走接口,它会 save_config + reload_pipeline_scheduler,日志里出现 Segmented-reply interval: [1.5, 3.5] 就是新配置已经生效了。on_decorating_result 钩子在分段之前执行。smart_tts 一旦把消息换成语音,链里就没有纯文本了,分段逻辑直接跳过——所以语音永远是整条一条,文字才会拆成几条。两条链路互不打架。间隔由 interval 控制(默认 "1.5,3.5",单位秒,随机取值),也可以把 interval_method 换成 log,按字数算延迟(y = log_2.6(x)),短句发得快、长句慢一点,更像真人在打字。
这是截图里最像人的部分——它会主动找你、知道自己今天干了什么、记得你前几天说过的话。靠插件实现。
astrbot_plugin_proactive_chat:安静一段时间后按概率随机发一条,内容现生成,不是从话术库里抽。四个文件放在 data/plugins/astrbot_plugin_proactive_chat/。
track 监听私聊,每次你一说话就记下会话 UMO 和活跃时间,写进 data/plugin_data/proactive_chat/state.json。_loop 后台每 tick_seconds 醒一次,判断:静默够久 + 在活跃时段 + 没超日限额 + 随机命中概率 → 才发。关键一行是 context.send_message(session, MessageChain([Plain(text)])),直接用会话 UMO 推送,不需要等用户先开口。
{
"enable": true,
"quiet_minutes": 25, // 静默多久才算「他不在」,太短会被当成骚扰
"tick_seconds": 60, // 检查间隔,别设太小
"trigger_chance": 0.06, // 每次检查的命中概率
"max_per_day": 12, // 一天上限,硬保险
"active_start_hour": 9, // 活跃时段,半夜绝不响
"active_end_hour": 23
}
真实频率靠这三个一起算:静默 25 分钟之后,每 60 秒有 6% 机会,平均再等 15 分钟左右。一天 14 小时活跃窗口,实际大概 8 到 12 条,被 max_per_day 兜住。
第一次调最容易犯的错是开太高。先用 trigger_chance 0.03 跑两天,觉得太少再往上加。反过来从高往低砍,你会先烦。
人设是粘人精,可以拉到 0.06~0.08;人设是清冷挂,0.02 就够。
坑一:改了配置文件不生效。插件参数是加载时读进内存的,改完必须重载。新版路由 POST /api/plugins/{id}/reload 会返回 405,用旧版这个:
TK=$(curl -s -X POST http://127.0.0.1:6185/api/auth/login \
-H "Content-Type: application/json" \
-d '{"username":"astrbot","password":"你的面板密码"}' \
| python3 -c "import json,sys;print(json.load(sys.stdin)['data']['token'])")
curl -s -X POST http://127.0.0.1:6185/api/plugin/reload \
-H "Authorization: Bearer $TK" -H "Content-Type: application/json" \
-d '{"name":"astrbot_plugin_proactive_chat"}'
返回 {"status":"ok","message":"重载成功。"} 就对了。配置文件读的时候要用 utf-8-sig,面板写出来的 json 带 BOM,普通 utf-8 会报错。
坑二:后台循环只在启动时拉起。@filter.on_astrbot_loaded() 是 AstrBot 启动完成时才触发的钩子,热重载不会重新触发。结果就是插件日志显示「已加载」,但那行 asyncio.create_task(self._loop()) 从没执行,一条消息都不发,排查半天以为发送失败。
改法是把循环启动写成幂等的,__init__、on_astrbot_loaded、首条消息三处都能调,谁先到谁拉起:
def _ensure_loop(self):
if self._task is not None and not self._task.done():
return self._task
self._task = asyncio.create_task(self._loop())
return self._task
async def terminate(self):
# 热重载时旧实例不取消,会出现两个循环同时发消息
if self._task and not self._task.done():
self._task.cancel()
顺带一条:容器别频繁重启。一天内为加载插件重启五六次,腾讯会判登录态异常,直接把你踢下线(KickedOffLine / ErrCode:3),之后每两分钟刷一次二维码。能用重载解决的就别重启。
上面这个是极简版,只解决「主动说话」。要人格连续性、关系状态、日程、日记、长期记忆,市场里作者 menglimi 那套更完整:
astrbot_plugin_private_companion —— 显示名「我会永远陪着你」,主动消息用的是「候选 → 时机评分 → 免打扰/额度检查 → 发送前复核」,不是固定定时器。astrbot_plugin_memory_companion —— 长期记忆,把聊过的事沉淀下来。市场搜不到就用「从 Git 安装」填 GitHub 地址。装完私聊发 陪伴 状态 看状态,陪伴 查看主动判定 看它为什么发 / 为什么没发。
代价是配置项多、和自定义人格容易打架。「世界知识」里只补角色背景和你们的关系,不要把第 5 步的人格再复制一遍。
都是从市场装的,共同点是往人设上「加状态」而不是「替她说话」,所以不会覆盖第 5 步手写的人格。
| 插件 | 作用 | 关键配置 |
|---|---|---|
astrbot_plugin_humanoid_core人形化伴侣 |
精力 / 睡眠债 / 饥饿 / 生理周期 / 社交能量,动态日程,情绪与好感,天气;私聊显示「正在输入」 | timezone_city 必改(默认「河源(记得改~)」,填城市名或 IANA 时区);admin_qq 填你的号 |
astrbot_plugin_emoji_like智能贴表情 |
LLM 判断你消息的情绪,给你的消息贴一个 QQ 表情 | emoji_like_prob 0.03 是主开关,嫌少往 0.1 调 |
astrbot_plugin_life_scheduler拟人化穿搭日常 |
每天生成穿搭 + 日程注入 system prompt | default_reference_umo 填会话 UMO;schedule_time 默认 07:00 |
astrbot_plugin_music点歌 |
点歌、卡片、语音、歌词、热评 | 见下面「音源」一段 |
astrbot_plugin_memory_companion我会牢牢记住你 |
长期记忆:分段摘要建库、全文检索召回、知识图谱、关系边、自然衰减 | 见下面「7.8 长期记忆」 |
astrbot_plugin_stealer表情包小偷 |
收图 → 视觉模型分类 → 按情绪追加发图;另有 search_meme / send_meme / steal_meme 三个工具给模型自己调 |
vision_provider_id 必填 deepseek;steal_meme 开、audit_required 关 |
meme_manager表情包管理器 |
WebUI 表情库、资源广场装包、语义检索、分类标签注入 | 只当仓库用,不要设「使用规则」,否则和 stealer 双发 |
人形化伴侣的常用指令(直接打,不带前缀):/你的状态、/查看日程、/好感度、/情绪详情、/叫我 昵称、/拟人帮助。管理员的在 /拟人 组里(/拟人 设置、/拟人 诊断、/拟人 重载)。
不装它,角色只记得「聊天记录窗口里还在的东西」。窗口一裁、一 /reset,你叫什么她就不认识了——这是很多人吐槽「AI 没记性」的真正原因,不是模型笨。
为什么选这个而不是 LivingMemory。humanoid_core/humanoid/memory_link.py 里写死了对接对象 astrbot_plugin_memory_companion,双向各做一件事:生成前按你这句话去记忆库要 3 条相关长期记忆(上限 240 字、60 秒缓存)并进她的事实块;她自己的生活过程真正结束时写一条回去(那件事聊天里看不见,只有她知道)。装别的记忆库没有这个接口,得自己写胶水。
依赖比想象中轻:只用 SQLite(含 FTS 全文检索),不需要 Milvus / 向量库;Embedding 和 Rerank 都是可选增强,retrieval.mode=auto 检测不到就退回 basic,本地评分、零外部调用。唯一必需的是一次 LLM 调用做阶段摘要。
# 关键配置(其余保持默认) memory_capture.enabled = True memory_summary.enabled = True memory_summary.provider_id = deepseek # 不填会落到全局默认 memory_injection.enabled = True memory_injection.top_k = 6 private_companion_bridge.enabled = True # 关掉它,humanoid 那边会判 disabled 就不读不写 retrieval.embedding_enabled = False # 记忆少的时候先别开 retrieval.mode = auto
它不是即时的。memory_summary.trigger_event_count 默认 20——攒够 20 条事件才压缩一次长期记忆。刚装完查库是空的,这是正常的,不是坏了。
常用指令(/mcomp 组):status 看状态、summarize 强制立刻总结一次、recent 看最近记忆、search 关键词、timeline、relations、add 内容 手动塞一条、preset companion 切陪伴场景预设、diagnostics 排障。
想立刻生效就走后门:/mcomp add 他叫刘世强,真人,让我叫他强强。这条是持久记忆,不依赖聊天窗口,比 /叫我 更抗丢。
成本:阶段摘要每 20 条事件一次,max_calls_per_session_hour 默认 6 次封顶。闲聊量级一个月几毛钱。
市场里大量插件干同一件事,装重了不是「双保险」,是两套状态同时注入提示词,她会自相矛盾——上午说在上班,下午说在家躺了一天。
实测重叠:humanoid_core 自带穿搭(outfit_enabled,见 humanoid/outfit.py)和分段日程,完全覆盖 life_scheduler。两个都开会各写一套穿搭和日程。二选一,留 humanoid_core。
其它已知重叠:astrbot_plugin_period(棉絮与铁)的生理周期 ⊂ humanoid_core;tts_emotion_router ⊂ 第 6.6 节的 smart_tts。装之前先想清楚「这件事现在有没有插件在做」。
插件内置三种通道,默认配置文件里那个不是都能用:
网易点歌 → 直连 music.163.com/api/search/get/web,实测 200 可用nj点歌 → 走 nodejs_base_url,默认 https://163api.qijieya.cn,实测 502 挂了,别用QQ点歌 等 → 走 https://music.txqq.pro,站点活着但 type=qq 返回 404,只有 type=netease 有数据发送方式默认第一个是 ark_card(签名卡片),要填 ark_key 才能用,没填就走不通。NapCat 上最稳的是把 send_modes 改成 ["record_local(本地语音)", "record_link(语音链接)"]——先下载成语音发,失败再退成链接。
命令:/点歌 晴天、/网易点歌 晴天、点歌后按钮选第几首。
这两个是同一件事的两半,装的时候必须分清谁负责发,否则一次回复会蹦出两张表情包。
| 插件 | 定位 | 发送方式 |
|---|---|---|
astrbot_plugin_stealer |
唯一的发送方:偷图、分类、按情绪追加 | 回复发完之后,独立追加一条表情,不改她的回复文字 |
meme_manager |
仓库 + 管理台:WebUI 浏览、资源广场装包、语义检索 | 往提示词里塞分类标签,让模型输出 &&分类键&& 才发 |
选 stealer 当发送方,是因为它的表情是「回复之后追加」,动不到已经定稿的人格和语气;meme_manager 那套要在回复正文里插标记,聊天记录会脏。
meme_manager 的正确用法:WebUI → 插件 → 表情包管理器 → 资源广场装包 → 只浏览,不设「使用规则」。规则一设,它也开始发,就跟 stealer 撞了。装下来的包想让 stealer 用,要在 stealer 的 WebUI「外部源」里导入(它能自动发现同实例的 meme_manager 资源包)。
别用 /表情管理 恢复默认表情包 这条指令——它装包的同时会顺手把该包设为默认,等于替你把使用规则打开了,立刻变成双发。
# stealer 关键配置(data/config/astrbot_plugin_stealer_config.json) steal_meme = true # 总开关,装了不等于开了 audit_required = false # 关掉人工审核,偷到直接入库 vision_provider_id = deepseek # 必填!留空会去找全局图片描述模型,那边也是空 meme_chance = 0.2 # 自动发表情概率 send_meme_as_qq_sticker = true # 以 QQ 表情包形式发,比图片自然
改完这个 json 必须热重载插件才生效(配置是加载时读的)。重载用 legacy 路由:POST /api/plugin/reload,body {"name":"astrbot_plugin_stealer"};/api/plugins/{id}/reload 会返回 405。
初始化时它建了 17 个情绪分类目录(happy / sad / shy / troll / sigh / thank …)全是空的,这是正常的——图库靠偷,没有内置图。发几张表情包给她,日志里出现收录记录才算跑通。
常用指令(/meme 组):status 看状态和库存、on / off 开关偷图、auto_on / auto_off 开关自动发、偷 进 30 秒强制收录、list 分类 列图、tag_stats 看标签分布。
现象:她主动发「我刚买了个小蛋糕」,半小时后又说「我买了盒草莓」,你顺口一句「你这又是蛋糕又是草莓的」,她回「我还没买呢」「我啥时候说的」「我说的是面吧」「你这记性,是不是把人记混了」。你截图甩过去,她才认。
看着像人格崩了、记忆模块没开,其实都不是。是她真的看不见自己说过那两句。
根因:主动消息插件用的是
await self.context.send_message(session, MessageChain([Plain(text)]))
send_message() 只管把消息塞给平台发出去,不往会话历史里写。历史是 pipeline 在处理「收到用户消息 → 生成回复」这条链路时写的,主动消息绕过了整条 pipeline,所以那条回复只存在于 QQ 聊天记录里,DB 里没有。
于是她读到的上下文是:你说「你这又是买蛋糕又是买草莓的」,前一条是她自己说的「那你去吃,不打扰你了」。蛋糕和草莓根本没出现过。在她看来就是你在瞎说,她当然要纠正你——这不是嘴硬,是她的世界线里确实没这回事。
查证方法:把历史 dump 出来搜关键词。142 条历史里搜「蛋糕」只命中你自己那句吐槽,说明她那边从来没有过。
from astrbot.core.conversation_mgr import ConversationManager cm = context.conversation_manager cid = await cm.get_curr_conversation_id(session) # 会话 uuid conv = await cm.get_conversation(session, cid) hist = json.loads(conv.history) # 注意:history 是 JSON 字符串
修复:发完手动补一条 assistant 消息。框架没有「只追加一条」的接口,add_message_pair() 要求 user + assistant 成对,所以只能读出来、append、整体写回:
hist.append({"role": "assistant",
"content": [{"type": "text", "text": text}]})
await cm.update_conversation(session, cid, history=hist)
读和写在同一个函数里连续执行,间隔毫秒级,撞上用户正在发消息的概率极低。别在 LLM 生成前读、生成后再写——中间那几秒正好够用户说完一句,会被覆盖掉。
顺带的第二个坑:生成主动消息时如果只把「现在几点 + 多久没说话」喂给模型,它每次都是独立起话头,跟前面的生活线完全不搭。实测会出现「20:13 说要买蛋糕 / 20:25 说买了草莓 / 聊天里说在吃面」三条互不相干的世界线。修法是把最近 8 条对话拼进 prompt:
最近你们聊的是这些:
{recent} # 「他:…」「你:…」逐条拼
要求:
- 接着上面的话头往下说,让这条像同一天里聊天的一部分
- 你提到的事要跟前面说过的事对得上,别换成另外一件
注意 prompt 里要用正向描述(「要跟前面说得对得上」),别写「不要编造没说过的事」——后者等于把「编造」这个词喂给模型,实测反而更容易编。
已污染的历史要不要回填:要。AstrBot 组装请求时是 req.contexts = json.loads(conversation.history),全量加载、不按条数截断,补进去就一定会被读到。回填前先备份 history 到文件,插到用户那句吐槽之前才是它本来该在的位置。
顺带还有一个更阴的坑:会话会被机器人自己的号污染。排查时看到日志里出现
[20:58:03] [core.event_bus:116] [default(aiocqhttp)] 2728235387/2728235387:
发送者/会话都是机器人自己的号、内容为空——某个插件发出的一条消息回环进了事件总线,被 PRIVATE_MESSAGE 过滤器当成一次正常私聊,于是 track() 把会话记成了她自己。后果是主动消息从此发给她自己,她收到后 track 再记一遍,错误会话自我确认,环就闭死了,你永远等不到主动消息。表现是「昨天还好好的,今天突然不主动找我了」。
修法是在 track() 开头挡两层:
if event.get_sender_id() == event.get_self_id():
return # 自己发的,不记
target = str(self.cfg.get("target_qq", "")).strip()
if target and str(event.get_sender_id()) != target:
return # 不是我关心的人,不记
再在 __init__ 里加兜底:读到的会话号如果不等于 target_qq,直接清空等下一个真实会话重建。否则错误会话会一直躺在 state.json 里,重载多少次都还是它。
同作者还有一排扩展插件,对应不同玩法。先明确一点:很多效果是「真数据 + 演剧情」,别指望全是真能力。
| 玩法 | 插件 | 真相 |
|---|---|---|
| 它会画画给你看 | astrbot_plugin_image_companion | 真·调生图 API |
| 一起看电影 / 语音通话 | astrbot_plugin_together_companion | 同步播放进度 + 语音,真的 |
| 看你的屏幕截图 | astrbot_plugin_screen_companion | 真的截屏 + 视觉模型识别 |
| 「我给了你一台手机」 | reality_companion / 自己写 | 渲染一张手机界面图发过来,剧情是演的 |
| 刷 B 站、看视频到凌晨 | 自定义工具插件 | 真去抓 B 站标题/弹幕,再讲成「我看了」 |
原理很简单,四步:
look_at_phone。剩下的「情绪」全靠人设和上下文,不需要额外技术。这也是为什么同样的代码,别人做出来像活的,你做出来像客服——差别在提示词。
「改你的收藏夹」「删你的照片」「改群名片」这类,走的是 OneBot 的 action 接口,技术上完全做得到。但:
跑起来只是开始。服务器上的东西没人看着,会悄悄出问题。
Docker 日志默认不限制,跑几个月能吃掉几个 G。看占用:
docker system df
给 compose 加日志上限(两个服务下都加):
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"
改完 docker compose up -d 生效。
./data人格、记忆、聊天记录、关系状态全在 /home/ubuntu/qq-companion/data 里。丢了就是从零开始。
tar czf /root/backup-$(date +%F).tar.gz -C /home/ubuntu/qq-companion data
ls -lh /root/backup-*.tar.gz
一周一次手动跑就行。要更省心就加个 crontab,或者用对象存储同步。
docker compose ps
docker stats --no-stream
容器 Up 不等于 QQ 在线(掉线后容器还活着)。而且如果服务器重启后容器没起来,你几天都不会发现。
简单做法:crontab 每 10 分钟跑一次 docker compose up -d(幂等,起来了就什么都不做),再加一句给主号发条消息自检。想专业点就上 Uptime Kuma 监控 6185。
面板默认只绑 127.0.0.1,只能靠 SSH 隧道看。掉线时要扫码、出门想知道她还在不在,都得起电脑开隧道——太麻烦。给它一个域名 + HTTPS + 一层密码,手机随时能进。
在 DNSPod 加两条 A 记录,都指向服务器 IP:
| 主机记录 | 类型 | 记录值 | 用途 |
|---|---|---|---|
| bot | A | 192.144.189.143 | NapCat 面板(扫码 / QQ 管理) |
| ai | A | 192.144.189.143 | AstrBot 面板(人格 / 模型 / 日志) |
DNS problem: NXDOMAIN。等 10 分钟,或者先用 dig +short @ns.dnspod.net bot.你的域名 确认权威服务器已经返回新 IP。机器上 80/443 已经被 nginx 占着,所以用 --webroot(standalone 会抢端口失败)。先确保 80 端口有个 server 块能吃下 /.well-known/acme-challenge/,再签:
sudo certbot certonly --webroot -w /var/lib/xunshan-acme \
-d bot.xunshanshengwu.cn -d ai.xunshanshengwu.cn \
--cert-name xunshan-bot \
--non-interactive --agree-tos --register-unsafely-without-email \
--deploy-hook "systemctl reload nginx"
--deploy-hook 很关键:证书 90 天自动续,续完必须 reload nginx 才会加载新证书。
完整配置见项目里的 nginx-xunshan-bot.conf,放到 /etc/nginx/sites-available/xunshan-bot 再软链到 sites-enabled。四个要点:
bot → 127.0.0.1:6099,ai → 127.0.0.1:6185proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;proxy_buffering off,否则长连接被攒着不吐listen 443 ssl http2;,1.25.1+ 才支持独立的 http2 on;map 块要单独放 /etc/nginx/conf.d/websocket-upgrade.conf(map 只能在 http 上下文里):
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
很容易犯的错是叠三层密码:nginx 一层、NapCat token 一层、AstrBot 账号一层。实际后面两层已经够用,外面那层纯属给自己添堵——每次打开都弹框,手机上尤其烦。
| 层 | 默认状态 | 实测效果 |
|---|---|---|
| NapCat WebUI | 需 WebUI token | 任何 /api/* 不带 token 一律返回 {"code":-1,"message":"Unauthorized"} |
| AstrBot 面板 | 需账号密码 | 错密码 401「用户名或密码错误」,未登录访问配置 401「未授权」 |
| nginx Basic Auth | 默认关闭 | 配置文件里那两行是注释状态 |
真要加(比如域名被搜到过、或者分享给别人),取消注释前先建密码文件:
openssl passwd -apr1 "你的密码" | sudo tee /etc/nginx/.htpasswd-bot
sudo chmod 640 /etc/nginx/.htpasswd-bot
sudo chown root:www-data /etc/nginx/.htpasswd-bot
然后去掉 nginx-xunshan-bot.conf 里这两个 server 块的注释:
auth_basic "Cyber Girlfriend";
auth_basic_user_file /etc/nginx/.htpasswd-bot;
noindex,站点也 server_tokens off)。| 用途 | 地址 | 登录 |
|---|---|---|
| NapCat(扫码 / QQ 管理) | https://bot.xunshanshengwu.cn/ | WebUI token:aY21puJ21Hft_eoB66QbYyBL |
| AstrBot 面板 | https://ai.xunshanshengwu.cn/ | astrbot / Xiaoyu2026 |
bot 访问根路径会 301 跳到 /webui,这是 NapCat 自己的行为,不是配置错了。
全部凭据(含 QQ 号、API key、SSH)整理在下一章 凭据速查。
crontab 每 5 分钟跑一次,逻辑写在 watchdog.sh 里。核心是把两类故障分开处理:
| 现象 | 处理 | 为什么 |
|---|---|---|
| 容器不是 running | docker compose up -d <服务名> | OOM / 重启后没自启。只拉那一个,别带服务名全量 up,否则会连带重建另一个容器 |
日志出现 KickedOffLine / 二维码 | 只告警不重启 | 重启只会换一张新二维码,你正在扫的那张立刻失效——之前踩到的 ErrCode 10 就是这么来的 |
| 其他离线迹象 | restart napcat | 依赖 ACCOUNT 环境变量走快速登录,不用扫码 |
*/5 * * * * /home/ubuntu/qq-companion/watchdog.sh >/dev/null 2>&1
判断方法不是「日志里有没有出现过在线」,而是比对最后一条在线日志和最后一条离线日志谁更靠后。日志起点要取容器本次的启动时间(docker inspect .State.StartedAt),拿固定的「最近 40 分钟」会读到重启前的旧记录,把已经掉线的机器误判成在线。启动不足 3 分钟又没有任何明确信号时,记一条「启动中」直接跳过。
重装、换机器、或者单纯忘了密码的时候,直接来这查。
| 项目 | 值 | 存在哪 / 怎么改 |
|---|---|---|
| 服务器 SSH | ubuntu@192.144.189.143 | 密钥 ~/.ssh/id_ed25519,本地别名 ssh tx |
| 机器人 QQ | 2728235387(小乖宝) | compose 的 ACCOUNT 环境变量 |
| 管理员 QQ | 3190992808 | AstrBot 面板 → 配置 → admins_id |
| AstrBot 面板 | astrbot / Xiaoyu2026 | data/cmd_config.json 的 dashboard 段(改完要重启容器) |
| NapCat WebUI token | aY21puJ21Hft_eoB66QbYyBL | napcat/config/webui.json + compose 的 WEBUI_TOKEN(两处要一致) |
| DeepSeek API Key | YOUR_API_KEY | AstrBot 面板 → 服务提供商 → DeepSeek |
| nginx Basic Auth (当前停用) | qiangge / XiaoYu@2026 | /etc/nginx/.htpasswd-bot,配置文件里两行注释掉就是没启用 |
| 你要做什么 | 用哪个 |
|---|---|
打开 bot. 域名,看 QQ 有没有掉线、要扫码 | NapCat WebUI token |
打开 ai. 域名,改人格 / 换模型 / 看聊天记录 | AstrBot 面板账号密码 |
| 登上服务器改文件 | SSH 密钥(不用密码) |
data/cmd_config.json 里 dashboard 段的 password(md5)和 pbkdf2_password(pbkdf2_sha256$600000$盐$摘要,盐和摘要都是 hex)→ 起容器。改之前一定先 cp 一份备份。# NapCat token
sudo cat /home/ubuntu/qq-companion/napcat/config/webui.json
# AstrBot 面板用户名(密码是哈希,看不到明文)
sudo python3 -c "import json;d=json.load(open('/home/ubuntu/qq-companion/data/cmd_config.json'));print(d['dashboard']['username'])"
# 机器人 QQ 号
docker inspect napcat --format '{{range .Config.Env}}{{println .}}{{end}}' | grep ACCOUNT
以下都是这台机器上真跑过一遍得出的结论,跟网上教程不一样的地方以这里为准。
deepseek-chat 了你的账号 /v1/models 实际返回:deepseek-flash、deepseek-v4-pro。填 deepseek-chat 会直接报错。当前用的是 deepseek-flash。
官方源 GPG key 下载被 reset,阿里云 docker-ce 索引同步中校验不符。最后用 Ubuntu 自带的 docker.io(29.1.3)+ docker-compose-v2(2.40.3),走腾讯云内网源,几秒装完,版本足够。
edge-tts配了 Edge TTS 会报 No module named 'edge_tts'。要么 pip 装进容器(重建就丢),要么自建镜像。用了后者:
# Dockerfile
FROM soulter/astrbot:latest
RUN pip install --no-cache-dir -i https://pypi.tuna.tsinghua.edu.cn/simple edge-tts
compose 里把 image: 换成 build: { context: . } + image: astrbot-custom:latest。记得加 .dockerignore 排除 data/ napcat/ ntqq/,否则构建会去读 root 拥有的配置文件而失败。
ACCOUNT 环境变量决定要不要每次扫码entrypoint 实际执行的是 qq --no-sandbox -q $ACCOUNT。不设 ACCOUNT 就是二维码登录,每次重启容器都要重扫。设了就走快速登录。还有 NAPCAT_QUICK_PASSWORD 作为登录态失效时的兜底。
wake_prefix 默认是 ["/"]默认要求消息以 / 开头才响应,私聊伴侣场景必须改成 []。改完要重启 AstrBot。
cmd_config.json配置里 persona 字段标了 deprecated。改人格走面板,或者调 API:
PUT /api/v1/personas/by-id
{"persona_id": "default", "system_prompt": "..."}
登录拿 token:POST /api/auth/login,body 是 {"username":"astrbot","password":"..."}。这台机器自带一条 default 人格,内容就是那句 You are a helpful and friendly assistant.——客服味的源头,必须覆盖掉。当前这条已经覆盖成「小鱼」人格,名字写在最前面的【你是谁】段里(踩坑过程见 5.4)。
在 data/cmd_config.json 里写老结构,启动时会看到 Migrating provider deepseek to new structure,它自己会拆成「源 + 模型」两层。不用手写 provider_sources。
改配置的正确姿势:docker compose stop astrbot → 改文件 → start。不停容器直接改,内存里的旧值会把你的修改覆盖回去。
| 项 | 值 |
|---|---|
| 机器人 QQ | 2728235387(小乖宝) |
| 管理员 | 3190992808 |
| 模型 | deepseek-flash |
| 语音 | Edge TTS / zh-CN-XiaoxiaoNeural,概率 35% |
| 唤醒前缀 | 空(私聊直接回) |
| 面板 | 127.0.0.1:6185(AstrBot)/ 127.0.0.1:6099(NapCat) |
按从上到下的顺序查,别跳步。
| 现象 | 先查这里 |
|---|---|
| 6185 / 6099 打不开 | SSH 隧道断没断(本地窗口是否还开着);docker compose ps 看容器是否 Up |
| 容器起来又退出 | docker compose logs astrbot | tail -50;多半是内存不够被 OOM kill,看 dmesg | grep -i kill |
| 配置保存了重启就丢 | 目录属主不对:chown -R 1000:1000 data napcat ntqq 后重启 |
| 镜像拉不下来 | 配 /etc/docker/daemon.json 镜像加速器;或换机器 save/load |
| NapCat 扫码后立刻掉线 | 小号被风控。换号,或用手机 QQ 正常用两天再试 |
| 日志没有「适配器已连接」 | URL 是不是 ws://astrbot:6199/ws,端口是否和 AstrBot 里一致,末尾 /ws 有没有丢 |
| 能收到消息但不回 | 默认对话模型没设;或模型测试没通过 / 余额不足 |
| 回了但内容是空的 | 模型返回被安全策略拦了;换模型或改提示词 |
| 语音只有文字 | TTS 总开关没开;提供商没选;改完没重启容器 |
| 语音是男性声音 / 音色不对 | Voice 字段要带模型前缀,如 FunAudioLLM/CosyVoice2-0.5B:alex |
| 插件装了但看不到入口 | 版本不满足;装完要重启;看插件页有没有红色报错 |
| 从来不发主动消息 | 主要用户没设;主动强度是最低档;在免打扰时段;当日额度用完 |
| 重启后配置全丢 | 没挂载 ./data 卷。检查 compose 里的 volumes |
用第三方协议端登录 QQ,本身就在平台规则的灰色地带,有概率封号,且申诉基本无望。所以:必须用小号,绝不拿主号试。
降低风险的习惯:主动消息频率压低、不自动加好友、不群发、不秒回所有人、不用它跑群管理。
先在插件里设个 Token 日限额,别一觉醒来账单吓人。
服务器上有 Python 环境的话,跳过容器:
curl -LsSf https://docs.astrbot.app/install.sh | bash
astrbot init
astrbot run
NapCat 单独装(Linux 一键脚本):
curl -o napcat.sh https://nclatest.znin.net/NapNeko/NapCat-Installer/main/script/install.sh
bash napcat.sh --tui
这时两边都在宿主机上,NapCat 里的地址要填 ws://127.0.0.1:6199/ws(不是容器名)。想开机自启就写个 systemd service。
不想敲命令,装 1Panel 或宝塔:图形界面里装 Docker、编辑 compose、看日志、点重启都有按钮。少记几条命令,但多占一两百 MB 内存。
去 github.com/AstrBotDevs/astrbot-launcher/releases 下 AstrBot.Launcher_x64-setup.exe,图形界面一路下一步;NapCat 下 NapCat.Shell.zip 跑 launcher.bat。连接地址用 ws://127.0.0.1:6199/ws。只适合试用,不适合长期挂。