PromLight 开箱教程
本文旨在带领大家快速上手使用 PromLight.
AI一键安装（推荐）
对 Claude Code / Codex 等支持 Hook 的 AI 说：
根据 `light.ghostyu.com/ai.txt` 帮我装好 PromLight
Note：配置完成后，AI 会自动启动 PromLight PC程序。该程序在后台运行、并已设置开机自启动，不会弹出窗口。如需查看状态或手动调试，在浏览器打开 web 控制台
http://127.0.0.1:7800即可。
AI 会自行读取安装手册、下载并配置，遇到"开机/配对"这类物理操作会停下提示您。
只剩两步需您亲手做：
- 开机： 长按机身按键约 3 秒，红🔴 → 黄🟡 → 绿🟢 依次点亮，绿灯开始闪烁即进入蓝牙广播。
- 蓝牙配对： 在系统蓝牙设置里找到
PromLight并连接。
检测配置是否生效：Claude 新开一个对话；Codex 在 设置 → 钩子 里手动点击信任（桌面版无法用 /hooks 命令信任）。完成，指示灯将自动随 AI 状态变化。
手动安装
若想手动安装请按下面分步操作，过程完全透明可控。
准备：下载 PC 端软件
访问 PromLight 官网，点击下载按钮，下载对应自己系统的软件包，解压至一个简短、固定的目录：
- Windows： 放入非系统盘，例如
D:/PromLight/PromLight.exe。 - macOS： 强烈建议放入
~/Applications/，例如~/Applications/PromLight/PromLight.app。
第 4 步生成的 Hook 配置会写入软件的绝对路径，因此安装位置要稳定。 请勿放在桌面、下载、OneDrive 同步目录，或含空格、中文的路径，以免日后移动导致配置失效。
第 1 步 开机与关机
机身按键长按约 3 秒即可开机或关机。
- 开机： 红🔴、黄🟡、绿🟢 三颗灯依次点亮，随后绿灯🟢 开始闪烁，表示已进入蓝牙广播，可被电脑搜索连接。
- 关机： 三颗灯全部熄灭，停止广播并进入休眠。
开机后 1 分钟内未配对成功会自动关机省电，再次长按开机即可。
第 2 步 蓝牙配对（仅首次）
首次配对一次，之后自动连接，过程与连接蓝牙耳机类似。
- Windows： 设置 → 蓝牙和其他设备 → 添加设备 → 蓝牙 → 选择
PromLight→ 连接。 - macOS： 系统设置 → 蓝牙 → 找到
PromLight→ 连接。
连接失败时，可关闭电脑蓝牙约 10 秒再打开重试。设备最多保存一台 PC的绑定信息；若已绑定却连不上，删除历史配对信息后重新配对即可。
第 3 步 运行 PromLight 程序
- Windows： 双击
D:/PromLight/PromLight.exe。 - macOS： 双击
PromLight.app。
程序会在后台自动运行，并自动设置开机自启动——之后开机即自动启动、自动连上已配对的设备，无需每次手动打开，也没有需要保持打开的窗口。
控制与调试改用 web 控制台：在浏览器打开 http://127.0.0.1:7800，在页面输入框测试连接，所有灯一起闪烁即正常（输入 help 查看更多命令）：
led all blink
web 控制台默认端口为
7800；若被占用打不开，可改用其他端口，详见《高级教程》「端口与 web 控制台」节。
第 4 步 接入 AI（配置一次即可）
让 AI 在状态变化时通知 PromLight。在 PromLight web 控制台（http://127.0.0.1:7800）的输入框输入一条命令即可：
setup all
它会自动给本机已装的 AI（Claude / Codex / Cursor / Copilot / Qoder）一次性写好全局配置（缺省即全局，对所有项目生效）。只想接入其中一个，把 all 换成对应名字即可，例如 setup claude、setup codex。
前提：hook 通过
python调用agent_hook.py，需电脑已装 Python 3 且python在 PATH 可直接调用。若指示灯对 AI 状态毫无反应，先用python --version核实（详见使用限制）。
配置后让它生效：
- Claude Code / Cursor / Copilot / Qoder：新开一个对话即生效。
- Codex：在 Codex 桌面程序打开 设置（Settings）→ 钩子（Hooks），在右侧的 hooks 列表中逐条点击信任（仅首次），即生效。桌面版无法用
/hooks命令信任，请在此手动点击信任。
各 AI 因事件机制不同，能点亮的状态略有差异（如 Copilot 无「等待确认」黄闪），完整对照见《高级教程》「各 Agent 的状态覆盖」节。 只想给单个项目启用、或想先生成配置再手动复制？见《高级教程》「接入配置」节。
默认灯效
| 指示灯 | 含义 |
|---|---|
| 🔴🟡🟢 三颗灯闪烁一下 → 🟢 绿灯常亮 | 新对话开始 |
| 🟡 黄灯常亮 | 正在处理（思考、修改文件、执行命令） |
| 🟡 黄灯闪烁 | 正在等待您确认或回复 |
| 🔴 红灯闪烁 | 本轮出现错误 |
| 🟢 绿灯常亮 | 处理完成，当前空闲 |
| 🟢 绿灯长周期呼吸 | 对话结束 |
自定义灯效、多设备路由等高级功能见《高级教程》。
完成与排错
日常使用：开机后 PromLight 自动在后台运行并连上设备 → 正常使用 AI，指示灯将自动反映 AI 状态。
指示灯无反应时，依次确认：① 蓝牙已连接；② PromLight 程序正在运行（后台常驻；可在浏览器打开
http://127.0.0.1:7800确认）；③ AI 接入已配置并已新开对话（Codex 还需在 设置 → 钩子 里手动点击信任）；④python可用（python --version）。 自定义颜色、多盏灯、按项目或按 AI 分灯等见《高级教程》。完整使用限制见 使用限制，更多问题见 常见问题。