HachimoDock（哈基米机）

哈基米机 HachimoDock：让你的宠物 / 朋友 / 你推变成 AI Agent，和你一起工作

把 Codex、Claude Code、OpenClaw 等 CLI Agent 的状态变成桌上小宠物的表情、动作、字幕和提醒。

硬件方案 · 硬件端资料 · 图集 · 软件架构 · 复刻与部署 · 快速开始 · 常见问题

硬件端资料 / PCB / BOM / 复刻教程

项目简介

HachimoDock（哈基米机）是一套桌面端管理器 + 小屏设备端固件/运行时 + 开源硬件方案。它把电脑里正在运行的 Agent 状态同步到桌面小屏上，让 AI 工作状态从终端窗口里走出来，变成一只可以抬头看见、可以触摸互动、可以语音唤起的小搭子。

这个 GitHub 仓库主要托管软件端和固件端代码；硬件端资料在 OSHWHub 维护。

图集

桌面小屏实拍：把 Agent 状态放到工位视野里。

桌面端管理：设备绑定、Agent 跟随、形象和组件配置。

核心亮点

状态跟随与互动

Agent 状态变化时，小屏同步切换表情和动作。

一眼识别当前状态，不必盯着终端窗口。

字幕和短标签提示 Agent 正在做什么。

自定义形象与组件

上传宠物照片、头像或原创角色，生成自己的桌面搭子。

负一屏组件承载番茄钟、喝水提醒、Token 消耗等轻量工具。

硬件方案

本仓库给出软件和固件配套；PCB、BOM、硬件装配和复刻资料请看： OSHWHub 硬件端页面。

ESP32 不是当前 board-runtime/ 已支持目标；如需使用，需要另起移植工程。

_{方案一 Radxa A7Z 的核心物料示意。}

硬件端资料

硬件端不只是一张接线图，包含从主控、屏幕、PCB、外壳到装配的复刻路径：

软件架构

flowchart LR
  agent["CLI Agent<br/>Codex / Claude Code / OpenClaw"]
  desktop["HachimoDock（哈基米机）桌面端<br/>Tauri + React"]
  bridge["Bridge sidecar<br/>session / MQTT / USB"]
  board["board-runtime<br/>C service + shell/Python helpers"]
  screen["桌面小屏<br/>宠物动画 / 字幕 / 负一屏组件"]

  agent --> desktop
  desktop --> bridge
  bridge -->|"USB serial 或 MQTT"| board
  board --> screen

桌面端读取 Agent session、归一化状态和字幕，再通过 USB serial 或 MQTT 下发到设备端。设备端 board-server 写入 .current-state、.current-speech、.stats-display 等本地状态文件，显示进程、输入进程和 widget runtime 通过这些文件协作。

复刻与部署

首次复刻到默认硬件 Radxa Cubie A7Z 时，先读 board-runtime/DEPLOY.md。这篇是当前标准部署入口， 覆盖从空白 microSD 卡写系统、首次写入 Wi-Fi、SSH 部署、SPI 屏幕显示、 本地 MQTT/bridge 到 Pet Manager 绑定的完整流程。

Raspberry Pi

cd board-runtime
export BOARD_HOST="<pi-user>@<pi-ip>"
HOST="$BOARD_HOST" sh scripts/deploy-rpi.sh

Radxa Cubie A7Z

macOS / Linux / WSL / Git Bash：

cd board-runtime
MQTT_URL="mqtt://<pc-lan-ip>:1883" \
HOST=radxa@<board-ip> \
SUDO_PASSWORD=<sudo-password> \
CONFIGURE_SPI_LCD=1 \
sh scripts/deploy-radxa-a733.sh

Windows PowerShell：

cd board-runtime
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\deploy-radxa-a733.ps1 `
  -HostName radxa@<board-ip> `
  -SudoPassword <sudo-password> `
  -MqttUrl mqtt://<pc-lan-ip>:1883 `
  -ConfigureSpiLcd

设备 IP、用户名、密码、board id 和 desktop id 不要写死在文档或业务代码里。调试具体板子时使用 BOARD_HOST="<pi-user>@<pi-ip>" 和 BOARD_IP="<pi-ip>"。

部署细节见 board-runtime/DEPLOY.md，安全部署与鉴权见 board-runtime/docs/security-hardening.md。

快速开始

_{桌面端负责绑定、跟随、形象、组件和诊断。}

启动桌面端

git clone https://github.com/YizhengWw/HachimoDock.git
cd HachimoDock/ref
npm install
npm run dev

只调试前端页面时：

cd ref
npm run dev:web

构建桌面应用：

cd ref
npm run build

更多说明见 ref/README.md。

编译设备端

cd board-runtime
cmake -S . -B /tmp/board-runtime-build-check
cmake --build /tmp/board-runtime-build-check --target board-server

更多说明见 board-runtime/README.md。

常见问题

这个 GitHub 仓库包含什么？

包含软件端和固件端：

• 软件端：ref/，也就是 HachimoDock（哈基米机）桌面管理器。
• 固件端 / 设备运行时：board-runtime/，部署到 Raspberry Pi 或 Radxa Cubie A7Z。
• 硬件端：PCB、BOM、装配和复刻资料在 OSHWHub 硬件端页面。

一定要用 Radxa Cubie A7Z 吗？

不是。当前文档同时照顾 Radxa Cubie A7Z 和 Raspberry Pi Zero 2 W。A7Z 是默认复刻硬件，性能更高；Pi 方案更适合完整体验 USB gadget、触摸、旋钮/按钮和语音链路。

屏幕、麦克风、喇叭和旋钮能换型号吗？

可以，但需要确认接口和驱动。屏幕建议保持 2.8 英寸 240×320 SPI、ILI9341；Raspberry Pi 方案已验证 XPT2046/ADS7846 触摸和 EC11/按钮。Radxa A7Z 方案当前默认验证 LCD 显示，触摸、旋钮和语音需要后续 overlay、GPIO 和声卡适配。

屏幕一定要带触摸吗？

不是必须。无触摸版本也能用于状态显示；带 XPT2046 触摸屏可以体验触摸反馈和更多交互。

必须做定制 PCB 底板吗？

不是必须。定制 PCB 主要是为了减少杜邦线、让结构更整洁。调试阶段可以先用杜邦线直连；想做成完整产品形态时再按 OSHWHub 的硬件资料打样。

大概成本多少？

方案一 Radxa A7Z 的电子料大约在几百元级别，具体取决于主控、屏幕、音频模块、外壳和打样方式。方案二 Raspberry Pi Zero 2 W 的成本受主板供货、声卡和转接件影响更大。

支持哪些 Agent？

面向 CLI Agent 设计，内置适配 Codex、Claude Code、OpenClaw 等。状态协议开放，第三方 Agent 也可以接入。

设备一定要联网吗？

取决于方案。Raspberry Pi 可走 USB gadget 直连；Radxa A7Z 当前默认走 Wi-Fi + MQTT/SSH，需要网络。

语音交互怎么用？

当前完整验证的是 Raspberry Pi 方案：按住按钮说话，板端把语音转成文本后通过输入事件送到桌面端，再注入目标 Agent。语音识别链路需要可用网络和 STT 服务。Radxa A7Z 方案当前默认不启动板端语音 PTT。

能自己加组件吗？

可以。组件中心使用 .clawpkg 结构，内置 skill 可以根据自然语言生成负一屏组件，并在 USB 或 SSH/MQTT 链路可用时下发到设备。

用什么开源协议？

软件代码按 AGPL-3.0-only 发布（桌面端 bridge 衍生自 AGPL-3.0 的 Clawd on Desk，AGPL 强 copyleft 不能降级为 GPL）；硬件设计、3D 结构件、官方宠物素材和第三方资源请以仓库内 LICENSE、COPYRIGHT、docs/open-source-compliance-prep.md 以及对应资源随附声明为准。

怎么反馈问题或参与贡献？

可以在 GitHub 提 Issue、Discussion 或 PR。硬件复刻相关问题建议同时参考 OSHWHub 硬件端页面。

文档

验证

cd ref
npm test
npm run build

cd board-runtime
cmake -S . -B /tmp/board-runtime-build-check
cmake --build /tmp/board-runtime-build-check --target board-server

设备端部署后检查：

export BOARD_HOST="<board-user>@<board-ip>"
export BOARD_IP="<board-ip>"
ssh "$BOARD_HOST" 'systemctl is-active board-runtime'
curl -fsS http://$BOARD_IP/board-runtime-config.json

致谢 / Acknowledgements

HachimoDock 的实现参考、借鉴并集成了以下开源项目，特此致谢：

• Clawd on Desk（AGPL-3.0）— 桌面端 Agent 桌宠形态与桌面端 bridge 的实现参考来源。
• OpenClaw（MIT）— CLI Agent 运行时与插件 SDK。
• Claude Code — 主力 coding agent 与 hook 状态协议。
• Codex — 被适配的 CLI Agent 之一；同时支持 Cursor、Gemini CLI、GitHub Copilot CLI 等。

作者 / Author

HachimoDock 由 Yizheng Wang（@YizhengWw）与 Wenchao Wang 共同设计与开发。

贡献者 / Contributors：Wanzheng Liu、Zinuo Tian。

• 📧 邮箱：[email protected]
• 💬 微信交流群：扫描下方二维码加入

如果 HachimoDock 对你有帮助，欢迎给仓库点一个 ⭐ Star、点击 Follow 关注后续更新，也欢迎提 Issue / PR 一起把它做得更好。

License

Copyright (C) 2026 Yizheng Wang.

This project is licensed under the GNU Affero General Public License version 3 only (AGPL-3.0-only). See LICENSE for the full license text and COPYRIGHT for the copyright notice.