快速安装

准备一根支持数据传输的 Type-C 线。先不要粘贴双面胶，等测试正常后再粘贴。

Windows 或 Linux：让 AI 安装（推荐）

Windows x64 或 Linux x86_64 用户，在 Claude Code、Codex、Cursor 等支持 Hook 的 AI 工具中发送：

请根据 light.buildfpga.com/ai.txt 安装 AgentCore-Light。

按 AI 的提示确认下载、安装和授权。完成后请新建一个 AI 对话，发送一条普通消息，并确认实体灯会变化。Linux 仅支持 Ubuntu 20.04 及以上版本，并由 AI 安装指南 处理安装、串口权限和后台服务。

Mac：安装测试版

1. 下载 Mac 测试版。
2. 完整解压安装包，将里面的 AgentCore-Light.app 拖到“应用程序”。
3. 测试版第一次打开会被 macOS 拦截：打开“系统设置 → 隐私与安全性”，找到 AgentCore-Light 的拦截提示，点击“仍要打开”完成授权信任。
4. 打开 App 后，在自动打开的本地控制台点击“启动服务”。
5. 设备显示“已连接”后，测试灯效；再在“AI 接入”中只安装你正在使用的 Hook。
6. 重启 AI 工具并新建对话，确认灯会跟随变化。

完整说明见 Mac 安装教程。

Windows：手动安装

1. 用 Type-C 数据线连接状态灯和 Windows 电脑。
2. 下载 Windows 安装包，完整解压后双击解压目录中的 AgentCore-Light.exe。
3. 在打开的页面点击“启动服务”，等待设备显示“已连接”。
4. 用页面的灯控按钮测试灯效；正常后点击“AI 接入”，只安装你正在使用的 AI 工具 Hook。
5. 重启该 AI 工具并新建对话，发送一条普通消息，确认灯会跟随变化。

Linux：手动安装

需要 x86_64 的 Ubuntu 20.04 及以上版本，或其他带桌面环境的主流 Linux 发行版。

1. 下载 Linux 安装包，完整解压。
2. 用 Type-C 数据线连接状态灯和电脑。
3. 终端进入解压目录，执行 chmod +x AgentCore-Light，再执行 ./AgentCore-Light。
4. 浏览器打开 http://127.0.0.1:18793，点击“启动服务”，等待设备显示“已连接”。
5. 如果提示串口权限不足，执行 sudo usermod -aG dialout $USER，然后注销并重新登录（或重启电脑）再试。不要用 sudo ./AgentCore-Light 运行程序。
6. 在“AI 接入”中只安装你正在使用的 AI 工具 Hook；重启该 AI 工具并新建对话测试。

需要开机后自动后台运行时，在解压目录执行 ./AgentCore-Light install，安装为用户级 systemd 服务；希望未登录桌面时也运行，再执行 sudo loginctl enable-linger $USER。详细说明见安装包内 README.md。

两个容易忽略的事项

• 如果找不到设备，先换一根确认支持数据传输的 Type-C 线，再重新插拔设备。
• Codex App 桌面版安装 Hook 后，需要在“设置 → 钩子”中手动点一次“信任”。

仍无法使用？查看 常见问题，并在问题解决前不要粘贴双面胶。