第 9 步｜安装客户端并接入 Codex

Agent 先核对读者的电脑平台

本章中的 Mac 操作是一个已知实践环境示例；面向外部读者时，不应假定他们拥有 Mac。Agent 应在执行当天查官方支持系统、下载文件架构与串口工具；若没有官方支持，就应明确条件与替代环境，而非让读者买新电脑或强行运行不兼容客户端。

目标

在 Mac 端完成从“USB 设备被检测到”到“看见真实 Agent 任务状态”的最小闭环。先不开语音识别或付费服务，排除额外依赖。

操作

1. 打开 最新官方 Release，选择 Apple silicon macOS 安装包。2026-11-06 核验的客户端版本是 0.1.199，但今后以最新版下载页为准。
2. 从原始 Release 下载并校验 SHA256SUMS。按照 macOS 的正常安装流程打开 DMG，拖入「应用程序」。官方说明已做 Apple Developer ID 签名/公证；不要关闭系统安全检查运行不明安装包。
3. USB 连接开发板，打开 HachimiDock 管理端，查看是否识别设备、显示正确的固件版本。
4. 用电脑打开一个正在运行的 Codex 会话。先让它做一个无风险的小任务，例如生成一段对话或解释一段 Python 代码；观察设备端是否显示会话的活动/完成状态。
5. 只在需要语音时打开“系统设置 → 隐私与安全性 → 辅助功能”里相应权限；如需 ASR/对话/内容生成服务，在官方客户端内配置自己的 API Key，不要写入教程或 GitHub。
6. 测试默认映射：SW1 短按确认、SW2 短按切页面、SW3 返回、摇杆上下左右切换、摇杆中键确认。长按 SW1 语音录制与 SW2 实时对话属于后续可选验证。

认清支持边界

官方当前列出 ChatGPT（Codex）、Claude、OpenClaw、MiMoCode、WorkBuddy、DeepSeek Harness 等适配器。但能检测到 Agent，不意味着当前程序输入框可写，更不意味着已经能监控所有远程 Session。先验证一个本机 Codex 会话，后续再研究 Agent 桥接。

验收

• 管理端已识别设备和固件版本。
• 一次真实 Codex 任务的状态能体现在设备屏幕上。
• 三个按键和摇杆的基础操作可用。
• 断开 USB 再重连仍能正常识别。
• 未在公开记录中泄露 API Key、个人路径或完整会话内容。

出问题怎么办

• 软件能开但设备不在线：先确认 USB 数据线、串口和固件版本，再重新启动客户端。
• 设备在线但 Agent 状态不更新：确认目标 Agent 程序确实在运行，查看适配器支持范围；不要把“没有找到输入框”误认为硬件故障。
• 语音不工作：基础闭环已完成时再处理权限、麦克风/扬声器以及语音服务 Key，不要让语音问题阻塞核心目标。

下一关：第 10 步：最终装壳与验收