进阶
排错
安装卡住、ta 不醒、被系统杀掉、重启后离线、安全模式、模型报错、飞书与灵魂同步、Linux 与 Windows 电脑上的常见问题。
#安装阶段
| 现象 | 原因与处理 |
|---|---|
| 「这台手机上已经有一个运行基座在运行」 | 多半是以前装在 Termux 里的旧版还在运行,占着同一个端口。按 从 Termux 版换过来 迁移:确认灵魂已推送,卸载 Termux 版(或在 Termux 里 sv down quetzal),再回来安装 |
| 「运行基座 180 秒内没有响应」 | 内置运行基座没能启动。先点一次 重试。日志在 App 数据目录的 files/home/quetzal/data/runtime.log,要在电脑上用 adb shell run-as xyz.quetzal.console 读取,只有调试版 App 可以;可以带着日志到 GitHub 提 issue |
| 「读不到网关令牌」「核对网关失败」 | 运行基座已经启动,但令牌对不上,多半是数据目录被手动改过。在 控制 → 高级 → 运行 重启后再试 |
#ta 一直不醒
按顺序检查:
- 控制 → 模型:至少一个供应商、一把 Key、一个已启用的模型,且测试连通成功。没有模型时醒来率为 0。
- 控制 → 节律:没有暂停;活跃度不是 0。
- 顶栏没有急停。
- 控制 → 高级 → 预算:今日预算没有用尽;电量高于最低电量且在充电;温度正常。
- 刚装好的一两个小时里,驱动力还在积累,ta 很安静是正常的。可以戳一下。
#离线 / 被系统杀掉
- 「此刻」页出现离线横幅时,点启动:App 重新启动自己的前台服务(通知栏里那条「ta 住在这台手机里」)。
- 反复被杀:确认 Quetzal 在电池优化忽略名单里,并在厂商的自启动 / 后台管理里放行。个别厂商系统有独立的"省电精灵"类组件,它不看白名单,需要在系统设置里关闭或禁用它。
- 重启后、App 升级后离线:有锁屏密码的手机要先解锁一次。厂商系统没放行「自启动」时,开机与升级的广播会被拦下,打开一次 App 即可恢复;放行「自启动」后就不会再出现。
#安全模式
运行基座 10 分钟内启动超过 5 次,就进入安全模式,ta 会主动告诉你"进入了安全模式"。这时只开网关与飞书,不醒来、不调用模型。原因通常是配置损坏或模型层异常。看日志(手机:App 数据目录的 files/home/quetzal/data/runtime.log;Linux 与 Windows:quetzal logs),修复后在 控制 → 高级 → 运行 重启。
#模型相关
| 现象 | 处理 |
|---|---|
| 测试连通失败 | 检查 API 地址是否含版本路径(如 /v1)、协议是否选对、Key 是否有效 |
| 回复中途失败并换了模型 | 这是正常的:流式输出 90 秒没有新数据块就判定失败,换下一个模型 |
| 图片被去掉了 | 没有能看图的模型。给某个模型手动打上 vision 标记,或启用目录里支持图片输入的模型 |
| 保存被拒绝「配置已过期」 | 别处先改过配置。重新加载后再改 |
#飞书
- 显示未连接:查看 控制 → 飞书 的错误信息;一键创建的应用要在飞书中确认后才会下发凭据。
- 收不到「此刻」卡片:打开与机器人(以 agent 显示名命名)的单聊,发一句话。
- 卡片按钮无反应:机器人需要开启长连接事件订阅。一键接入会自动开启;手动接入的,请检查应用后台的事件订阅方式。
#灵魂同步
| 现象 | 处理 |
|---|---|
| 接入失败「地址必须是 SSH」 | 用 git@github.com:你/仓库.git,不能用 https |
| 推送被拒 | Deploy key 没勾 Allow write access;或公钥没加到这个仓库 |
| 「身份不同,拒绝合并」 | 仓库里住着另一个 agent。给这个 agent 新建一个仓库 |
| 两边记忆看起来不一致 | 同步由事件触发:等 ta 下一次醒来 / 对话,或在 控制 → 高级 → 同步 点「立即同步」 |
#网页控制台(Linux)
- 打开
http://127.0.0.1:7788/要配对码:网关只对同一台机器的浏览器免配对码,用局域网 IP 或主机名访问不算同一台机器,请改用127.0.0.1或localhost。从别的机器访问有三种做法:用ssh -L 7788:127.0.0.1:7788 <那台机器>转发后在本机浏览器打开;开了--lan时打开https://<那台机器的地址>:7789/,核对证书指纹后输入配对码;或者在 App 里配对。 - App 提示「运行基座已改为加密连接,请重新配对」:旧版 App 保存的是
http://<地址>:7788,新的运行基座在局域网上只接受 HTTPS。在配对页保存新地址(只填 IP,App 自动用https://…:7789),核对证书指纹后重新配对。 - 页面空白或中文显示成方块:用
quetzal status看服务是否在运行,再强制刷新浏览器。网页版自带中文字体,不依赖外网。 - 装完没有自动打开浏览器:没有桌面会话(服务器、ssh 登录)时,安装器只打印地址。用
quetzal open再试。 - 一键安装脚本中途失败:它会打印日志的最后几行,完整日志在
~/.quetzal/install.log。修好原因后再跑一次同一条命令即可,重复运行没有副作用。apt被锁住多半是系统正在后台更新,等几分钟再试。Alpine 请先apk add bash curl;NixOS 请先自备 Node.js 22.13+(nvm 的二进制跑不了)。 - 重启后 ta 没醒:
loginctl show-user $USER -p Linger的结果不是yes,就执行sudo loginctl enable-linger $USER(没有登录会话时,用户服务默认不运行)。没有 systemd 的机器,看crontab -l里有没有@reboot …/quetzal-supervise;没有 cron 守护进程的话,开机后手动运行一次。 - 应用列表里的「Quetzal」打开的是普通浏览器标签,任务栏没有 Quetzal 图标:独立窗口需要 Chromium 系浏览器(Chrome / Chromium / Edge / Brave / Vivaldi),只有 Firefox 时用默认浏览器打开。
#Windows
- 安装时被拦下、没有「仍要运行」:电脑开着「智能应用控制」。一行命令会打开「Windows 安全中心 → 应用和浏览器控制 → 智能应用控制」请你关掉,然后继续安装。浏览器下载的安装包遇到 SmartScreen 提示时,点「更多信息」→「仍要运行」。
- ta 的命令一律不执行:沙箱没装好,例如没同意安装时的那次管理员权限请求。按控制台的提示重新运行安装。
- 开机后没人登录时 ta 不运行:账户没有「作为批处理作业登录」的权限,开机任务没注册上,只有登录时的任务。安装日志里会写明。
- ta 说「需要有人登录桌面」:截图与操作屏幕、通知、剪贴板、打开网页、播放声音、拍照、录音要等有人登录 Windows、托盘里出现 Quetzal 以后才能用。
- 日志:
quetzal logs(home\logs\runtime.log);quetzal status看版本与守护任务。
更多见 Windows。
#还是不行
到 GitHub Issues 描述现象,附上 控制 → 高级 → 运行 显示的版本与相关日志(请先去掉日志里的个人信息)。