常见问题
PromLight 使用中的高频问题速查。更完整的说明见 开箱教程、高级教程 与 使用限制。
兼容与前提
支持哪些系统？ 仅支持 Windows 与 macOS（不支持 Linux、手机或平板）。
支持哪些 AI？ 需要支持 Hook 的 AI，目前已适配 Claude Code、OpenAI Codex、Cursor、GitHub Copilot 与 Qoder。各 AI 能点亮的状态略有差异，完整对照见高级教程「各 Agent 的状态覆盖」。
电脑需要什么条件？
需具备蓝牙（4.2 及以上；无内置蓝牙可加 USB 蓝牙适配器），并安装 Python 3 且 python 在 PATH 中可直接调用。
为什么一定要装 Python？没装会怎样？
状态上报脚本 agent_hook.py 由 AI 的 hook 以 python 调起。若 python 不可用（未安装，或 Windows 上命中了 Microsoft Store 的占位别名），脚本会静默失败、指示灯毫无反应且没有任何报错。可先运行 python --version 确认返回真实版本号。
配对与连接
怎么开机？ 长按机身按键约 3 秒，红 → 黄 → 绿依次点亮，绿灯开始闪烁即进入蓝牙广播，可被电脑搜索连接。开机后 1 分钟内未连接会自动关机省电。
怎么关机？ 长按按键约 3 秒，三颗灯全部熄灭即进入休眠（休眠功耗极低）。
怎么首次配对？
- Windows：设置 → 蓝牙和其他设备 → 添加设备 → 蓝牙 → 选择 “PromLight” → 连接。
- macOS：系统设置 → 蓝牙 → 找到 “PromLight” → 连接。
只需配一次，之后自动连接。
连不上 / 自动连接失败怎么办？ 关闭电脑蓝牙，约 10 秒后再打开重连。设备同一时间只记住两台电脑的绑定信息；若电脑已配对过该设备、但出现「连上就断开」，请删除电脑上的配对信息后重新尝试配对。若仍连接失败，可尝试重启电脑——这能解决 99% 的蓝牙连接问题。
一盏灯能同时连多台电脑吗？ 不能，设备同时只保存一台 PC 的绑定。反之，一台电脑可驱动多盏 PromLight（按项目或按 AI 分灯，详见高级教程）。
灯不亮 / 没反应
按顺序排查：
- 蓝牙是否已连接（系统蓝牙里显示“已连接”）。
- PromLight 程序是否在运行——程序在后台常驻、开机自启；若被手动退出则停止反馈（可在浏览器打开
http://127.0.0.1:7800确认是否在运行）。 - 在 PromLight web 控制台手动发送 led 命令——浏览器打开
http://127.0.0.1:7800，发送命令；如果灯可以控制，则说明问题出在 Hook 上。 - 是否已让配置生效：Claude Code 需新开一个对话；Codex 需在 设置 → 钩子 里手动点击信任一次。
python是否可用：跑python --version，确认不是 Microsoft Store 占位别名。- 安装路径是否为纯英文、无空格、非同步盘——中文/空格路径会导致 hook 不生效，移到合规路径后重新写入配置。
Codex 配好了 hook，灯却一直不亮？
在 Codex 桌面程序里，hook 只在项目内的对话中触发：你必须先创建 / 打开一个项目，并在该项目里对话，Codex 才会唤起 hook。信任 hook 的方式是：点击 Codex 左下角的设置（Settings），找到钩子（Hooks），在右侧的 hooks 列表中逐条点击信任即可生效。Codex 桌面版无法用 /hooks 命令信任，请用上述设置里手动点击信任的方式。不属于任何本地项目的普通对话不会产生 hook 事件，灯自然不亮——先确认当前是在项目内对话。
PromLight 启动时，提示端口被占用了？
PromLight 用到两个本机端口：web 控制台默认 7800、Hook 通信默认 47800。某个被其他程序占用时，会导致程序启动失败或对应功能失效。
修改程序所在目录里自动生成的 config.json，把对应端口改掉后重启 PromLight 即可：
- web 控制台端口冲突（打不开
http://127.0.0.1:7800）：改web_port字段，例如{"web_port": 7801}。 - Hook 端口冲突：改
port字段，例如{"port": 47801}。
不确定是哪个端口被占用、或想查端口占用情况，可让 AI 帮你查询。
日常使用
指示灯默认行为是什么意思？
| 指示灯 | 含义 |
|---|---|
| 🔴🟡🟢 三颗闪一下 → 🟢 绿灯常亮 | 新对话开始 |
| 🟡 黄灯常亮 | 正在处理（思考、改文件、执行命令） |
| 🟡 黄灯闪烁 | 正在等待你确认或回复 |
| 🔴 红灯闪烁 | 本轮出现错误 |
| 🟢 绿灯常亮 | 处理完成，当前空闲 |
| 🟢 绿灯长周期呼吸 | 对话结束 |
程序必须一直开着吗？ 程序双击运行后会在后台常驻并设置开机自启动，开机即自动运行，通常无需手动打开。只要不手动退出它，指示灯就持续响应。
能自定义颜色、亮度、闪烁效果吗？ 可以，并支持多设备路由、按项目 / AI 分灯等，详见高级教程。
为什么有的状态我的灯从没显示过（比如一直没见过红灯）？ 不同 AI 对外提供的事件不同，能点亮的状态也不同：例如 Codex / Cursor 不报「出错」红灯，Copilot 没有「等待确认」黄闪，Qoder 只有「正在处理 / 出错 / 完成空闲」。这是 AI 的能力差异，并非设备故障，完整对照见高级教程「各 Agent 的状态覆盖」。
硬件：续航、充电与距离
续航多久？怎么充电？ 内置 400mAh 锂电池，约 4~5 天（按每天 8 小时计）。通过 Type-C 接口充电——该接口仅用于充电，不传输数据，设备与电脑始终通过蓝牙无线通信。
有效距离多远？ 空旷无遮挡约 20 米；墙壁、家具等障碍会缩短实际距离。
隐私与安全
PromLight 会上传我的对话或代码吗？
不会。hook 只把状态事件（开始/处理中/等待/完成/出错）发给本机 PromLight 程序（本地回环 127.0.0.1），不经过任何云端，也不读取对话或文件内容。
一键安装脚本安全吗？
脚本经 https 提供，并在下载后自动校验安装包的 SHA256（与发布的 .sha256 旁文件比对），不匹配即中止。谨慎用户也可手动核验，方法见安装手册。