故障排查
不要一开始就反复重装。按下面顺序查看状态，通常可以快速判断应该修驱动、修连接还是修插件。
先判断故障在哪一层
| 现象 | 故障层 | 优先动作 |
|---|---|---|
| 托盘和控制台都打不开 | 驱动层 | 从开始菜单重新启动，再检查本地服务状态；仍然失败时才重新安装 |
| 控制台能打开，但设备未连接 | 链路层 | USB 检查数据线与 COM 口；蓝牙检查扫描、绑定和设备蓝牙 |
| 设备已就绪，但 AI 任务不变化 | 插件层 | 确认装对客户端、已经重启客户端，并信任或启用了对应 Hook |
| 任务会变化，但灯效不符合预期 | 设备层 | 检查电量、固件版本、固件本地状态和当前主链路 |
确认本地驱动是否在线
先确认托盘中的知言家 logo存在并能打开控制台。如果需要进一步区分“驱动未启动”和“设备未连接”，可以检查：
%LOCALAPPDATA%\zy_home_vibe_coding_driver\service.json是否存在。- 浏览器能否打开
http://127.0.0.1:25263/api/app/status。如果发现文件记录了不同的baseUrl，以发现文件为准。 - 状态接口能返回 JSON，但设备仍显示未连接时，问题已经进入 USB 或蓝牙链路层，不需要重新安装驱动。
官网首页的本地驱动面板也会尝试读取同一状态接口，可作为快速交叉检查。
驱动启动报"端口被系统保留 / 拒绝监听"
如果驱动开机后无法监听 127.0.0.1:25263（报错像"端口被系统保留或权限策略拦截"，而非"端口已被占用"），通常是宿主侧存在一条错误的 netsh portproxy 规则占用了端口。用 PowerShell 检查：
powershell
netsh interface portproxy show all若看到 0.0.0.0 25263 → 127.0.0.1 25263，请删除它（需管理员，可用 Start-Process powershell -Verb RunAs）：
powershell
netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=25263然后重启驱动。WSL 桥接的正确写法是监听 WSL 虚拟网卡 IP（如 172.31.96.1:25263），而不是 0.0.0.0，见快速开始：接入 WSL 里的 AI 工具。
使用 PING 交叉验证
右键托盘选择“测试链路 PING”。PING 正常说明电脑到设备的协议链路可用，但不会验证 AI 插件是否正确安装。
正常“未发现设备”不是服务故障
扫描结果为空时，控制台应该继续保持可用。靠近设备、确认蓝牙已经开启后重新扫描即可。USB 扫描为空时，则按顺序检查数据线、USB 口和 COM 口。
检查插件是否只是“已安装但未启用”
- Codex / Claude Code：重启客户端，并在核对命令路径后确认 Hook 信任。
- opencode：确认当前项目或全局插件目录中存在驱动插件，并重新打开会话。
- TRAE：文件状态显示“已安装（需在 TRAE 中启用）”时，仍需进入 Agent Hooks，启用用户级驱动 Hook 并选择“本地自动运行”。
导出诊断包
问题仍未解决时，右键托盘进入“诊断与日志”，点击“导出诊断包”。保留生成的 zip，联系支持人员时按要求提供，避免只靠截图猜测问题。诊断包可能包含本机路径、版本、连接状态和经过裁剪的日志；发送前请确认接收方可信，不要上传到公开论坛或公共网盘。
导出前请尽量记录：
- 问题发生的大致时间。
- 使用 USB 还是蓝牙。
- 控制台当时显示的链路状态。
- 问题发生前最后执行的操作。
具体恢复动作也可以在常见问题中按现象查找。