跳到正文

进阶

排错

安装卡住、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 描述现象,附上 控制 → 高级 → 运行 显示的版本与相关日志(请先去掉日志里的个人信息)。