常见问题¶

按「症状」查，不按模块查。每条给出现象、原因和怎么办；能一句话说清的 就一句话，需要展开的才展开。

启动¶

启动就退出，说「还差这些才能启动」¶

不是报错。首次运行会生成配置然后停下，等你把必填项填上。照着它列的两项填完再启动 一次即可，见从零跑起来第三步。

报「悬空引用」之类的配置校验错误¶

现象：加载配置时直接退出，指出某个名字找不到。

原因：三份配置之间的引用是单向链条——任务引用模型名，模型通过 api_provider 引用厂商名。改了其中一处名字而没改另一处，链就断了。

怎么办：加载期做的是完整交叉校验，它会指名道姓告诉你哪个引用悬空。顺着 models.toml 的 api_provider 和 providers.toml 的 name 对一遍。

这是刻意设计：带着一个悬空引用继续跑，表现会是「某个任务莫名其妙不工作」，比启动 时直接报错难查得多。

启动卡在「服务正在启动 名称：xxx」不动¶

原因：那个后台服务的启动钩子没有返回。长期运行的循环必须 create_task 之后 立即返回，把循环本身注册成启动钩子会让生命周期永久 await 下去，其后的服务全部起 不来。

怎么办：这是缺陷，请报 issue 并附上卡住的那一行。四条状态门测不出这一类， uv run python pytests/boot_probe.py 能。

控制台里的中文是乱码¶

原因：Windows 控制台按本地代码页解码，UTF-8 的中文在管道里就已经坏掉。

怎么办：设 PYTHONUTF8=1，或用 Windows Terminal。无头自检的结果会写进 YUELI_SELFTEST_OUT 指定的 UTF-8 文件，就是因为管道里的中文事后无法还原。

管理面板¶

打开是「尚未构建」¶

前端产物没生成。跑一次 npm run build（产物落 out/webui）。API 与 QQ 不受影响， 只是没有界面。不想在服务器上装 Node，可以在别处构建后把 out/webui 拷过去。

面板要我输 token¶

本机访问本来是自动登录的（请求来自回环地址时后端直接建会话）。要你手输，说明自动 登录那一步失败了——多半是通过非回环地址访问的。

token 在启动时控制台打印的「WebUI 已就绪」框里，也可以从 data/runtime/backend.json 读。每次启动重新生成，所以上次那个不能用了。它不进日志文件，也不进 WebUI 日志流。

直接调 API 时用 Authorization: Bearer <token>。

面板打不开 / 想远程访问¶

面板只监听 127.0.0.1，且不打算改。远程访问走 SSH 端口转发 （ssh -L 7999:127.0.0.1:7999 <主机>），不要把它直接暴露到公网。

模型调用¶

报「账户余额不足或免费额度用尽」¶

这一类不会重试。免费额度用尽归入账务失败：同样的请求再发一次得到的还是同样的 拒绝，重试只是多消耗一次配额和一段等待。

怎么办：检查余额与「仅用免费额度」设置，或把对应模型从候选清单里移掉。任务的 候选是一个列表，移掉一个还有下一个顶上。

她突然不回话，日志里是 PROHIBITED_CONTENT¶

现象：某几段对话稳定失败，换个说法又好了。

原因：服务商的内容策略拦截。不能按内容归因——同一段提示词在同族模型上必然 同判，看不出是哪一句触发的。

怎么办：给这个任务配一个异族模型作为候选（不同厂商、不同模型族），路由会 在同族全部失败后换过去。同族之间互相顶替是无效的。

首字很慢 / 老是超时¶

任务级的首字超时和连接级的重试是两件事。连接内尚未输出内容时会按 max_retries 重试，但整体仍受任务级首字超时截断——要让重试跑满，得先调大首字超时。两个参数分别 在 providers.toml 和 models.toml 里。

QQ 与群聊¶

适配器起来了但连不上任何协议端¶

原因：config/adapter.toml 里写的插件目录名，与那个插件目录下 config.toml 的段名对不上。目录名即适配器身份，两者必须一一对应。

怎么办：uv run python scripts/check/self_check.py 会检查这一项并指出不一致。

连上了但收不到消息，或者文本和 @ 解析不出来¶

协议端的消息上报格式 messagePostFormat 必须改成 array。默认值下文本段和 @ 段 无法按当前协议解析。见 QQ 与群聊接入。

群里叫她没反应¶

按顺序查三处：

1. 群号在不在白名单里。白名单按群号判断，即使你本人正在名单外的群里发言， 那个群也不会被豁免——消息在适配器侧就被丢弃，不创建人物、不写记忆、不请求模型。
2. 叫的名字配了没有。bot.toml 的 [bot] name 和 aliases 决定哪些称呼能叫到 她。配置值出现在消息里即命中，不做额外的词形判断。
3. 回复概率。[group_chat] name_mention_probability 决定名字或别名命中后的回复 概率；协议 @ 是否必回由 at_mention_must_reply 单独决定。

未提及她的群消息仍会落进那个群自己的历史（她记得发生过什么），只是不调用回复模型。

她在群里知道我屏幕上是什么吗¶

不知道，而且这不是「默认关闭」的开关——group 是配置结构里不存在的出口，填进去 会在加载期直接报错。屏幕感知只能开给桌宠和私聊，私聊那条也只对 owner.qq 本人生效。

她在私下里记住的事，在群里仍然记得——那是记忆，不是屏幕感知。

桌宠¶

开着桌宠开关但外壳没起来¶

外壳按仓库里实际存在的东西选启动方式：有 node_modules 就走 npm run dev，只有 构建产物就直接跑本地 Electron。两者都没有会报错并告诉你该执行哪条命令，后端本身 照常运行。

点了没反应 / 输入栏拿不到焦点 / 窗口位置越搬越偏¶

这三个都是 Electron 侧的已知陷阱，共同点是不报任何错。见 Electron 侧的三个不报错的坑。

数据¶

升级后想回退到旧库¶

先完全退出程序，用 data/backups/ 里对应版本的备份覆盖 memory.db，再在 SQLite 中把 PRAGMA user_version 设回那个版本号。

不要手工删新列，也不要指望有反向迁移——迁移是单向的，尤其事实归属与人格关系拆 分之后的多人数据不能可靠降级。详见数据库迁移与恢复。

数据和配置能不能放到别处¶

可以。uv run bot.py --data-dir <目录> --config-path <目录>。桌宠外壳会拒绝把运行 时根目录解析到 C 盘；无头运行没有这道限制。

还是没解决¶

开 issue 的时候带上这三样，能省掉一轮来回：

1. 控制台从启动到出问题的完整输出（去掉 token 那一行）。
2. uv run python scripts/check/self_check.py 的输出。
3. 你改过的配置项（不要贴 api_key）。