Windows 安装教程

本教程适用于在 Windows 上安装和使用 AgentCore-Light v1。当前客户端通过 Type-C 数据线连接状态灯；蓝牙连接功能将在后续提供。

安装前必看

收到货后请先不要粘贴双面胶。 请先完成设备连接、灯效测试和 AI Hook 测试，确认所有功能正常后，再将设备粘贴到需要的位置。

准备内容

• AgentCore-Light v1 状态灯
• Windows 电脑
• 一根支持数据传输的 Type-C 线
• Windows 安装包

1. 连接设备

使用支持数据传输的 Type-C 线，将 AgentCore-Light v1 连接到电脑。

注意：有些 Type-C 线只能充电，不能传输数据。如果程序无法找到设备，请先更换一根确认可以传输数据的线。

2. 下载 Windows 安装包

点击下载 AgentCore-Light v1 Windows 安装包

下载完成后，先将 ZIP 压缩包完整解压到一个固定目录。不要直接在压缩包预览窗口中运行程序。

3. 运行程序

打开解压后的文件夹，双击 AgentCore-Light.exe。

程序运行后会打开 AgentCore-Light 配置页面。本安装包已包含所需程序，客户无需另外安装 Python 或 Node.js。

4. 启动串口服务并测试灯效

1. 在配置页面点击“启动服务”。
2. 等待程序自动扫描 USB 串口。
3. 连接成功后，页面会显示 AgentCore-Light v1 设备已连接。
4. 使用页面中的灯控按钮切换不同状态，并调节亮度。
5. 观察实体灯的颜色和灯效是否正常变化。

只有完成这一步，才能确认 USB 线、串口连接和设备硬件都正常。

5. 安装 Agent Hook

1. 点击配置页右上角的“AI 接入”。
2. 在列表中选择你正在使用的 Agent 软件。
3. 按页面提示点击“安装”或“重新安装”。
4. 等待页面提示 Hook 安装完成。

Copilot 用户

Copilot 仅支持全局安装。如果对 Copilot 使用 --project，程序会自动降级为全局安装，并在页面或日志中显示提示。

Codex App 用户

Codex App 桌面版用户安装 Hook 后，还需要打开 设置 → 钩子，手动点击一次“信任”。桌面版无法使用 /hooks 命令完成信任。

6. 重启 Agent 并验证

Hook 安装完成后，关闭并重新打开你的 Agent 软件，然后新建一个对话进行测试。

注意：Hook 配置的改动均在 新建对话 后生效，已经打开的旧对话不会自动加载新配置。

当 Agent 进入思考、执行、完成或等待确认等状态时，观察实体灯是否同步变化。

7. 确认正常后粘贴双面胶

确认以下项目都正常后，再粘贴双面胶：

• 程序能正常启动
• 页面能自动连接 AgentCore-Light v1
• 手动灯效和亮度测试正常
• Agent Hook 已安装
• 新建对话后，AI 状态可以同步到实体灯

常见问题

页面找不到设备

• 确认已点击“启动服务”并等待自动扫描。
• 确认 Type-C 线支持数据传输。
• 更换 USB 接口或数据线。
• 关闭可能占用串口的其他软件。
• 重新插拔设备后再试。

出现重复进程或串口状态反复跳变

双击安装包中的 emergency_stop.cmd，停止所有 AgentCore-Light 进程，然后重新打开 AgentCore-Light.exe。

Hook 安装后灯效没有跟随 AI 变化

• 完全退出并重新打开 Agent 软件。
• 务必新建一个对话。
• Codex App 用户确认已在“设置 → 钩子”中完成信任。
• 返回“AI 接入”页面，确认对应 Hook 已安装。

仍然无法使用

请先不要粘贴双面胶，并保留问题页面和设备状态的截图，联系售后进一步检查。