BBClaw 是 OpenClaw 生态中的第三方硬件节点（Node），面向本地优先的低延迟语音与通知交互。
对讲机与 BB 机是体验灵感（实时语音 + 推送通知），由同一套固件统一承载，而非两种可切换的「模式」。
| 模块 | 功能 |
|---|---|
| 音频 | ASR 语音识别接入、VAD 语音活动检测 |
| 显示 | 1.47″ ST7789（172×320，横屏 320×172）、LVGL |
| 交互 | PTT 按键控制、触觉反馈 (马达) |
| 连接 | WiFi 入网、Adapter / Gateway 配对 |
| 节点 | Adapter 音频入口、OpenClaw 文本/事件交互 |
- MCU：ESP32-S3
- 音频：ES8311 CODEC（麦克风 / 扬声器链路）
- 显示：1.47″ ST7789，横屏 320×172，LVGL
- 交互：PTT 按键、振动马达
v1.0 方向：开发板极客方案 + 3D 打印外壳，优先可复现与体验迭代。
设备与 Adapter 在同一 WiFi 内通过 IP 直连，延迟极低。
| 链路 | 协议 | 说明 |
|---|---|---|
| BBClaw ↔ Adapter | WiFi LAN | 同一内网，IP 直连 |
| Adapter ↔ Gateway | WebSocket | 官方 node 方式注入 transcript / 订阅回复 |
| Gateway ↔ AI | OpenAI / 本地模型 | 文本理解、回复生成 |
不在家也能用 BBClaw。通过 https://bbclaw.daboluo.cc 注册账户并绑定设备，配合家中运行的 HomeAdapter，即可在任意网络环境下使用语音助手。
| 局域网 | 公网 | |
|---|---|---|
| 网络 | 同一 WiFi | 任意网络 |
| 延迟 | 极低 | 略高 |
| 距离 | 局域网内 | 无限制 |
详见 公网模式使用指南
本项目通过 firmware/boards 实现多板适配，既支持 BBClaw 原生硬件，也支持社区常用的 ESP32-S3 成品板。（适配方式参考 xiaozhi-esp32 的 board 实现。）
| BBClaw 原生版 | 实战派 | Stick S3 | 微雪手表 |
|---|---|---|---|
 |
 |
 |
 |
其中 BBClaw 原生版采用 3D 打印外壳与通用散件，方便自行打印和复刻；其他板卡可复用同一套固件能力，具体支持情况以 firmware/boards 中的配置为准。
make -C firmware init # 首次克隆后：目标 esp32s3 + 生成 sdkconfig
make -C firmware build
make -C firmware flash
make -C firmware monitor自研硬件或兼容板复刻时，按下面顺序即可跑通；细节与 adapter.yaml 示例见 使用手册。
- 环境：安装 ESP-IDF（本仓库在
firmware/下构建；常见命令也可用make -C firmware <目标>）。 - 初始化（仅首次或换分支后）：
make -C firmware init。 - 固件配置：
make -C firmware menuconfig，在 BBClaw 菜单中设置：- Transport Profile：
local_home（局域网）或cloud_saas（公网） - Local Adapter Base URL：局域网模式下填运行 Adapter 的机器地址，例如
http://192.168.1.100:18080；公网模式再配 Cloud Base URL（见菜单项） - 可选：编译期 Wi-Fi SSID / Password；不填则上电后用热点
BBClaw-Setup-xxxx（默认密码bbclaw1234）网页配网
auth_token：adapter.yaml与固件侧须一致，写法见 使用手册。
- Transport Profile：
- 局域网 Adapter（内网必做）：推荐用下面的「Adapter 一键安装」脚本；或到 GitHub Releases 下载对应平台的
bbclaw-adapter-*手动安装。写好.env后在同网段机器上启动，使固件里填的 Local Adapter Base URL 可访问。 - 编译烧录：
make -C firmware build，接 USB 后make -C firmware flash，make -C firmware monitor查看日志（WiFi 与 Adapter 就绪后即可联调）。
公网模式除固件选 cloud_saas 外，Adapter 需使用 Release 中的 internet 包，并完成云端账号与设备绑定（见 公网模式）。
脚本会根据 uname 自动选择 darwin-arm64 / darwin-amd64 / linux-amd64 / linux-arm64 二进制，下载到 ~/bbclaw-adapter/，并把可执行文件装进系统 PATH（macOS/Linux 在 /usr/local/bin 或 ~/.local/bin 建软链；Windows 把安装目录加入用户 PATH），使任意位置都能直接运行 bbclaw-adapter。
为什么必须进 PATH：设备配置功能（如语音让 AI「把音量调到 50%」）由后端 Agent 直接执行
bbclaw-adapter device ...命令完成。若二进制不在 PATH 中，会因command not found失败。
macOS / Linux
curl -fsSL https://raw.githubusercontent.com/daboluocc/bbclaw/main/scripts/install-adapter.sh | bashWindows (PowerShell)
iwr -useb https://raw.githubusercontent.com/daboluocc/bbclaw/main/scripts/install-adapter.ps1 | iex安装完成后验证 CLI 已可被找到（macOS/Linux 用 command -v bbclaw-adapter，Windows 用 Get-Command bbclaw-adapter）。若脚本提示 PATH 目录未生效，按提示把对应目录加入 PATH 后重开终端。
可选环境变量：BBCLAW_INSTALL_DIR（程序/配置目录，.env 放这里）、BBCLAW_BIN_DIR（自定义进 PATH 的可执行目录，仅 macOS/Linux）、BBCLAW_VERSION（指定版本 tag，默认 latest）。
安装后按 Adapter 外部安装 Skill 写 .env（ADAPTER_AUTH_TOKEN / OPENCLAW_WS_URL / ASR 相关变量）并启动。
bbclaw/
├── firmware/ # ESP32-S3 固件源码（C / ESP-IDF）
├── adapter/ # 本地 Agent Bridge 守护进程（Go） — 2026-04-27 从闭源仓搬入
├── design/ # 架构 / ADR 决策记录
├── docs/ # 用户手册、协议、硬件文档
├── scripts/ # Adapter 一键安装、烧录、调试脚本
├── tools/ # 本地 ASR/TTS 工具
├── CHANGELOG.md # 版本历史
└── LICENSE # Apache 2.0
Adapter 源码现在在本仓（commit bf24299，参见 ADR-011）。
若你只想跑预编译 binary，仍可用上面的「Adapter 一键安装」脚本；若你想从源码构建或贡献新 driver，参见 adapter/README.md。
Cloud（云端 SaaS：账户、计费、ASR/TTS 路由）和 Web（用户面板）仍闭源在 bbclaw-reference 仓 —— 那是 ToC 服务的护城河，与本仓的开放硬件 + 开放本地代理叙事互补。
- OpenClaw 自动化 Issue 执行策略 — 维护者标签
ready-for-agent与代理拉取规则 - Adapter 外部安装 Skill（供复制到各 Agent 技能目录）
- 使用手册 — 从零开始配置和使用
- 架构
- 公网模式
- 协议规范
- 协议 V1 基线
- xiaozhi-esp32 — 优秀的开源 ESP32 语音助手方案，BBClaw 的多板子适配体系受其架构启发，ATK-DNESP32S3-BOX 的引脚映射和硬件初始化参考了该项目的 board 实现
- LimeZu — Animated mini characters — 待机界面像素小精灵素材（免费包 Red / Blue / Green Idle 切帧）。作者允许在免费与商业项目中使用并可修改；请勿再分发或转卖原始素材包。仓库内说明见 firmware/assets/third_party/limezu/README.md。
Apache License 2.0