# 常见问题与排错

> 按问题现象检查配置、连接和运行状态。

来源：https://vonvon.cc/docs/troubleshooting/
更新时间：2026-11-04

先在左上角确认当前设备，再打开全局「设置 → 诊断」，点右上角「重新检查」。这里能看到后台版本、Bot 连接、飞书设置与权限、最近没回的消息、最近崩溃和后台日志。按你看到的现象往下查；不要只凭一条旧截图判断当前状态。

![诊断按 Provider 与决策模型展示检查结果，提供运行详情和后台日志入口；示例环境尚未配置账号或密钥。](https://vonvon.cc/bot/docs/diagnostics.png)

诊断 · 示例：尚未配置账号或密钥

## 群里发了消息，Bot 没回

1.  确认运行 Bot 的设备开着、联网且未睡眠。远程设备要先切过去，确认它显示在线。
2.  在「诊断」展开这个 Bot，检查「连接」「飞书设置」「缺的权限」「Provider」。如果有“检查连接”或“一键开权限”，按页面提示处理；飞书后台刚改完权限时，可能还需要发布新版本后再检测。
3.  到群详情确认这个 Bot 已在群中启用，群不是待设置。发送一条明确 `@ Bot` 的测试消息；多会话群主区的普通聊天不会仅因开启免 @ 就自动开新话题。
4.  回到诊断页看「最近没回的消息」。这里会给出具体原因和下一步；智能模式也可能判断这条消息不该回复。若 Bot 还没回，再看「后台日志」和最近崩溃。

“最近没回的消息”只记录当前后台运行期间的相关消息，重启后台后会清空。要排查刚发生的问题，先记下时间、群、消息位置和界面原因，再重启。群设置和会话方式见[群组与会话方式](https://vonvon.cc/docs/groups/#modes)。

## 终端能用 Codex 或 Claude，Vonvon 却显示不可用

先核对设备和 Vonvon 版本。打开「设置 → Provider」，看是程序未安装、运行组件未就绪、账号/API 配置未被检测到，还是模型读取失败。Codex 和 Claude 的登录应在各自的应用或命令行完成；回到 Vonvon 后点「重新检测」。模型读取失败时刷新模型，别把保留的旧列表当作最新结果。

逐项操作见[Provider 检测排错](https://vonvon.cc/docs/providers/#not-detected)。若切换过 Provider 或更改可用模型，群里的「模型与权限」也要重新核对。

## 图片、文件或语音没被正确处理

图片没被看到时，先用单张直接发送的图片重试；一条消息最多处理 9 张，合并转发中的图片可能下载失败。文件请直接上传，别用合并转发；一条最多 9 个、单个不超过 50 MB。普通文件下载到运行 Bot 的设备后再由它读取，受限的 Codex 沙箱可能读不到工作区外的临时附件；到[群权限](https://vonvon.cc/docs/capabilities/#permissions)核对当前档位。

语音未转写时先改发文字，或在 Bot 的语音设置里检查识别状态。语音处理上限为 20 MB、60 秒；识别出空白内容或飞书资源下载失败时，Bot 应提示你重发，不应猜测原话。

## 定时任务没按预期运行

先到目标群详情的「任务」页，不要只看 Bot 页汇总。核对任务是否仍为“已启用”、下次时间和时区；点「记录」查看是失败、错过、跳过还是中断。运行 Bot 的设备关机、睡眠或后台没跑时不会准时执行，恢复后只补 7 天内最近一次。任务暂停期间的计划点不补。

同一任务上一轮未结束、群暂时停用或更新时可能记“跳过”；群解绑或当前权限档不可用会失败。连续 10 次计入失败会自动暂停。按记录修好原因后再恢复；详细步骤见[查看运行结果](https://vonvon.cc/docs/tasks/#results)和[连续失败](https://vonvon.cc/docs/tasks/#failures)。

## 更新下载了，但版本没有变化

桌面端的「下载更新」只下载并验证。回到「设置 → 应用与启动」，若显示“已下载并验证”，还要点「重启升级」并等应用重新打开，再核对版本。若显示“上次安装未生效”，点「重试」或从官网下载页手动安装。

服务端更新要等进度显示完成，并检查当前版本；失败或回滚先看错误信息和后台日志。远程设备更新期间可能短暂断开。按[桌面端更新](https://vonvon.cc/docs/updates/#desktop)、[服务端更新](https://vonvon.cc/docs/updates/#server)逐步核对。

## Bridge 导入卡住或只看到一半结果

在原来的 Mac 上打开「设置 → Bridge 导入」，先看进度或上次结果；窗口断开时后台可能还在继续，不要立刻再次点「开始导入」。预检不通过就按问题列表修复并重新检查；若回滚尚未完成，优先使用页面提供的「重试回滚」。保留旧 Bridge 目录，直到确认 Bot、群和旧会话都能按预期使用。见[导入失败与恢复](https://vonvon.cc/docs/bridge-import/#recover)。

## 远程设备连不上

先确认那台设备开着且未睡眠、Vonvon 后台运行、网络地址仍可达。首次添加时检查连接链接是否过期或已用；已经配对的设备若提示身份变化，应在确认设备归属后重新配对。各平台的防火墙和地址排查步骤见[远程连接排错](https://vonvon.cc/docs/remote/#trouble)。

## 终端找不到 vonvon 命令

Mac 桌面版打开过一次后，新开终端再试；Linux 对照安装完成时的提示。Windows 桌面版目前 没有 `vonvon` 命令，请用桌面界面。命令存在但连不到后台时，先检查当前终端是不是在运行 Bot 的设备上，再用 `vonvon daemon status` 查看状态。详情见[命令行排错](https://vonvon.cc/docs/cli/#after-error)。

## 需要反馈时，带上什么

记录 Vonvon 版本、操作系统、当前选中的设备、操作时间、复现步骤、错误原文和预期结果。可附「诊断」里的连接状态与相关日志片段；发送前遮住个人信息、API Key、应用密钥及设备连接链接。到[交流群](https://vonvon.cc/#community)反馈。