Mac 安装教程（测试版）

本教程适用于在 Mac 上安装和使用 AgentCore-Light v1，当前 Mac 客户端版本为 v0.3.0-test。目前通过 USB 数据线连接状态灯；蓝牙连接功能将在后续提供。

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

1. 安装 AgentCore-Light

1. 双击打开下载好的 AgentCore-Light-mac-v0.3.0-test.dmg。
2. 将 AgentCore-Light.app 拖到 Applications / “应用程序”文件夹。
3. 打开“应用程序”，找到 AgentCore-Light.app。
4. 第一次打开时，如果 macOS 提示“无法验证开发者”或“无法打开”，请右键点击 App，选择“打开”，然后在弹窗中再次点击“打开”。

当前版本是测试版，暂未进行 Apple Developer ID 签名和公证，因此 macOS 可能会拦截。正式版将处理签名和公证。

2. 连接状态灯

1. 使用支持数据传输的 USB 数据线连接 AgentCore-Light 状态灯。
2. 打开 AgentCore-Light.app。
3. 浏览器会自动打开本地控制台 http://127.0.0.1:18793。
4. 进入控制台后，点击“启动服务”。
5. 稍等片刻，程序会自动扫描 AgentCore-Light 状态灯设备。
6. 等待设备区域显示“已连接”。

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

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

3. 测试灯效

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

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

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

4. 调节亮度

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

5. 接入 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 命令完成信任。

6. 设置登录后自启动

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

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

7. 停止服务

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

常见问题

App 打不开

请右键点击 AgentCore-Light.app 并选择“打开”。如果仍无法打开，请前往“系统设置 → 隐私与安全性”，找到 AgentCore-Light 的拦截提示，然后点击“仍要打开”。

页面没有自动打开

请在浏览器中手动访问：

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 串口通信，不需要 Python、Node.js、网页云服务、BLE 蓝牙或外网连接。本地控制台地址 127.0.0.1 只允许本机访问，不对外网开放。