Light v1 Docs

Mac 安装教程（测试版）

AgentCore-Light v1 Mac 测试版的下载、安装、授权信任、USB / 蓝牙连接和 AI Hook 配置流程。

AgentCore-Light v1 产品图

Mac 安装教程（测试版）

本教程适用于在 Mac 上安装和使用 AgentCore-Light v1，当前 Mac 客户端为测试版（版本 v1.1.4），支持 USB 数据线和无线蓝牙（BLE）两种方式连接状态灯。

点击下载 AgentCore-Light v1 Mac 测试版

1. 安装 AgentCore-Light

  1. 完整解压下载好的 AgentCore-Light-mac.zip。
  2. 在解压出的文件夹中，把 AgentCore-Light.app 拖到旁边的 Applications（“应用程序”）快捷方式上完成安装。
  3. 第一次使用前，先按下面的“测试版授权信任”完成授权，再打开 App。

2. 测试版授权信任（第一次使用必做）

当前是测试版，暂未进行 Apple Developer ID 签名和公证，因此第一次打开时 macOS 会拦截，必须在系统设置中授权信任后才可以使用：

  1. 打开“系统设置”。
  2. 进入“隐私与安全性”。
  3. 在“安全性”区域找到 AgentCore-Light 被拦截的提示，点击“仍要打开”。
  4. 在弹窗中再次点击“打开”。

也可以在“应用程序”中右键点击 AgentCore-Light.app，选择“打开”，再在弹窗中点击“打开”。

授权信任完成后即可正常使用。正式版将处理签名和公证，届时不再需要这一步。

3. 连接状态灯

打开 AgentCore-Light.app 后，浏览器会自动打开本地控制台 http://127.0.0.1:18793。控制台“设备”区域顶部有连接方式切换：USB 串口和无线蓝牙。

USB 连接

  1. 使用支持数据传输的 USB 数据线连接 AgentCore-Light 状态灯。
  2. 在连接方式中选择“USB 串口”，点击“启动服务”。
  3. 稍等片刻，程序会自动扫描 AgentCore-Light 状态灯设备。
  4. 等待设备区域显示“已连接”。

Mac 上常见的串口名称类似：

/dev/cu.usbmodem1101
/dev/cu.usbserial-xxxx

蓝牙连接

蓝牙连接要求状态灯已上电、靠近电脑，并使用支持蓝牙的固件。

  1. 在连接方式中选择“无线蓝牙”。
  2. 点击“启动后台蓝牙”，程序会自动扫描并连接 AgentCore-Light 蓝牙设备。
  3. 等待设备区域显示“已连接”。

蓝牙连接由后台服务保持，关闭浏览器页面后仍可继续工作。

4. 测试灯效

在控制台左侧可以测试以下状态：

  • IDLE：空闲状态
  • THINKING：思考状态
  • BUSY：执行状态
  • SUCCESS：成功状态
  • ERROR：错误状态
  • WAIT_CONFIRM：等待确认状态
  • OFF：关闭灯光

如果灯没有变化，请确认 USB 线支持数据传输、页面设备区域显示“已连接”，并在重新插拔设备后点击“重新扫描设备”。

5. 调节亮度

拖动控制台中的亮度滑块即可调节灯光亮度。

6. 接入 AI 工具

当前测试版支持以下 AI 工具：

  • Claude Code
  • Codex
  • Cursor
  • Qoder
  • CodeBuddy
  • Antigravity / Gemini
  • GitHub Copilot
  • Trae
  • OpenCode
  1. 点击控制台右上角的“AI 接入”。
  2. 找到你正在使用的 AI 工具。
  3. 点击“安装”或“重新安装”。
  4. 安装成功后，页面会显示“已安装”。

只需安装你实际使用的 AI 工具，不需要安装列表中的全部工具。

Copilot 用户

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

Codex App 用户

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

7. 设置登录后自启动

  1. 点击控制台右上角的“设置”。
  2. 找到“登录后自启动”。
  3. 点击“开启”。

开启后，登录 Mac 时 AgentCore-Light 后台服务会自动启动，插入状态灯后自动扫描并连接。

8. 停止服务

关闭浏览器页面不会停止后台串口服务。如需停止服务，请重新打开控制台，点击“停止服务”。如不再需要登录后自动运行，请同时在“设置”中关闭“登录后自启动”。

常见问题

App 打不开 / 提示无法验证开发者

请先完成上面“测试版授权信任”的步骤：打开“系统设置 → 隐私与安全性”，找到 AgentCore-Light 的拦截提示，点击“仍要打开”。如果仍无法打开，请右键点击 AgentCore-Light.app 并选择“打开”。

页面没有自动打开

请在浏览器中手动访问：

http://127.0.0.1:18793

页面显示未连接设备

  • 确认 AgentCore-Light 已插入 Mac。
  • 确认 USB 线支持数据传输。
  • 如果正在使用扩展坞，请先尝试直连 Mac。
  • 重新插拔设备后点击“重新扫描设备”。

蓝牙扫描不到设备

  • 确认状态灯已上电，且使用的是支持蓝牙的固件。
  • 确认状态灯靠近电脑。
  • 点击“重新扫描”重试；仍找不到时，重新插拔状态灯电源后再扫描。

灯效没有变化

  • 确认页面显示设备已连接。
  • 确认串口端口类似 /dev/cu.usbmodem 或 /dev/cu.usbserial。
  • 点击 OFF 后再点击 IDLE 或 THINKING 测试。
  • 重新启动 AgentCore-Light.app。

AI Hook 安装后没有反应

  • 确认已安装对应 AI 工具的 Hook。
  • 重启 Claude Code 或 Codex，并新建对话。
  • 确认 AgentCore-Light 后台服务正在运行，且状态灯设备已连接。

卸载方式

  1. 在设置中关闭“登录后自启动”。
  2. 退出 AgentCore-Light。
  3. 删除“应用程序”文件夹中的 AgentCore-Light.app。

如果之前安装过 AI Hook，测试阶段如需卸载 Hook，请联系技术支持。

重要说明

AgentCore-Light Mac 测试版通过本机 USB 串口或无线蓝牙（BLE）与状态灯通信，不需要 Python、Node.js、网页云服务或外网连接。本地控制台地址 127.0.0.1 只允许本机访问，不对外网开放。

快速安装查看说明遇到问题查看说明二次开发查看说明