先按症状找到对应条目。每次排查后，建议用“试听”页面验证设备，用一个真实 AI 任务验证接入。

## 找不到 AI Light 设备

可能原因包括设备未供电、距离过远、电脑蓝牙关闭、权限被拒绝或系统蓝牙服务异常。

1. 确认设备已经供电。
2. 把设备放到电脑附近。
3. 关闭再打开电脑蓝牙。
4. 检查系统是否允许 AI Light 使用蓝牙。
5. 返回“设备”页面选择“重新查找设备”。
6. Linux 用户还应确认系统蓝牙服务正在运行，且当前账户有访问权限。

## 设备连接失败

1. 重新查找，确认设备仍在列表中。
2. 确认设备没有被另一台电脑占用。
3. 让设备重新上电后再连接。
4. 退出并重新打开 AI Light。
5. 记录错误提示和应用版本。

## 设备频繁断开或一直重连

1. 缩短设备与电脑之间的距离。
2. 排除遮挡和强无线干扰。
3. 等待自动重连完成，最多尝试 5 次。
4. 如果设备已经手动处理，选择“停止重连”，再重新连接。
5. 仍然异常时，忘记设备并重新配对。

## 应用状态变化，但实体状态灯不亮

1. 检查侧栏底部是否显示“设备已连接”。
2. 打开“试听”，选择一个标准状态。
3. 使用“试听当前灯效”重播效果。
4. 检查当前主题是否把该状态设置为熄灭或极低亮度。
5. 换用 Default 经典主题再次验证。
6. 断开并重新连接设备。

## 灯光正常但没有提示音

并非每个主题、每个状态都带提示音。Minimal 极简主题默认无声，其他主题也可能只在“出错了”时发声。

1. 在“主题”页面确认当前主题是否包含声音。
2. 用“试听”测试“已完成”和“出错了”。
3. 换用带提示音的主题再次验证。
4. 如果灯效正常但所有带声音的测试都无声，记录设备故障提示并联系支持。

## AI 编程工具无法连接

如果出现 npm 或配套组件相关错误：

1. 在终端运行 `node --version` 和 `npm --version`，确认两者可用。
2. 如果命令不存在，安装当前受支持的 Node.js 稳定版本。
3. 确认 npm 软件源可以访问。
4. 重新打开 AI Light，再次选择“连接”。
5. 如果仍失败，保留完整错误提示，不要反复手工修改工具配置。

## 接入已连接但任务状态不更新

1. 确认 AI Light 应用仍在运行，而不是已从托盘退出。
2. 新建一次任务；已经运行中的旧会话可能没有加载新 Hook。
3. 检查连接的是本机运行的 Claude Code 或 Codex。
4. 在“接入”页面先断开，再重新连接。
5. 确认手动“试听”可以改变应用状态，以排除应用本身加载失败。
6. 云端任务或没有经过本机 Hook 的操作不会自动同步。

## 状态长时间停留在“已完成”或“出错了”

某些主题会让终态保持显示，直到下一条任务事件到来；另一些主题会在短暂展示后自动回到空闲。

需要立即清除时，打开“试听”页面并选择“停止灯效”。

## 主题无法导入或保存

1. 查看导入窗口或提示消息中的具体原因。
2. 确认文件扩展名为 `.ailight-theme.json`。
3. 确认主题名称没有与内置主题重复。
4. 如果是手写 JSON，使用 JSON 校验工具检查格式。
5. 以某个内置主题创建新主题，再逐步应用修改，可以更容易定位问题。

## 关闭窗口后找不到应用

关闭窗口只会隐藏 AI Light。请在 macOS 菜单栏、Windows 通知区域或 Linux 系统托盘中找到 AI Light 图标，然后选择“显示窗口”。

如果托盘中也没有图标，重新启动 AI Light。

## 开机自启没有生效

1. 检查 AI Light 设置中的“开机自启”。
2. 检查操作系统的登录项或启动应用列表。
3. 如果应用被移动或重新安装，先关闭再重新开启该设置。
4. 确认系统策略没有禁止用户级启动项。

## 获取进一步支持

提交问题时请尽量提供：

- 操作系统名称和版本；
- AI Light 应用版本；
- 使用的 AI 编程工具及版本；
- 问题发生前的操作步骤；
- 完整错误提示；
- 设备页面显示的连接、电量或故障信息；
- 问题能否通过“试听”稳定复现。

公开提交信息前，请移除用户名、目录、令牌和其他敏感内容。

故障排查