the brain stays home.
limb 是一种故意不智能的联网设备。它把屏幕、扬声器、麦克风和设备上的少量 持久存储，以尽可能低层的接口交给局域网里的主机；功能、模型和会话则留在你 选择的 coding agent 中。
它不是一台内置助手，也不要求某个固定的 AI 运行时。你可以直接用 limb CLI
驱动它，把它接入 OpenClaw，或者让自己的程序通过 liblimb 使用它。
limb 把输入和输出设计成两种不同的能力：
- 麦克风等输入只能由设备本地事件限时开启。远程协议中没有“打开麦克风”或 “延长录音”的操作；输入开启时，设备指示灯必须亮起。
- 屏幕、扬声器和其它输出对已配对的主机开放，并通过带 TTL 的租约解决多个 使用者之间的冲突。
- 设备可以运行沙箱化的 WebAssembly“反射”，完成秒表、状态灯等低延迟或离线 行为；反射接触不到麦克风、摄像头和固定的主人语音通路。
- 设备不会直接连接语音云。STT/TTS provider 在主机侧选择，也可以替换为本地 实现。
完整的不变量与设计理由见 AGENTS.md，线上的唯一协议事实源是 PROTOCOL.md。
- 发现、配对和描述局域网中的 limb 设备；
- 向 240×240 屏幕写入裸 RGB565 像素；
- 播放 16 kHz、单声道 S16LE PCM，或在主机侧合成文字后播放；
- 在本地物理 gate 开启后采集 PCM，并在主机侧识别语音；
- 把关于某台设备的配置和记忆写进设备 KV；
- 构建、安装、检查和停止持久化的 WASM 反射；
- 把一台设备映射成一路 OpenClaw channel，获得连续对话和流式语音回复。
设备会通过 describe 如实报告实际能力。当前板卡没有确认的 GPIO 扩展口，也
没有声明满足时间戳要求的摄像头，因此客户端不应假定这些能力存在。
下面假定设备已经烧录固件、连入与主机相同的网络，并且你已安装 Rust 工具链。 先在仓库根目录构建 CLI：
cargo build --release -p limb
export PATH="$PWD/target/release:$PATH"发现设备并查看它真实暴露的能力：
limb scan
limb describe limb-a1b2c3将示例中的 limb-a1b2c3 换成 scan 返回的设备 ID。设备选择器也接受 mDNS
名称、IP 地址和 host:port；成功使用一次后，可以用全局选项 --last 复用
最近的设备。
持续按住设备按键 5 秒，看到 LED 慢速呼吸后，在 60 秒窗口内执行：
limb pair limb-a1b2c3 --label my-laptopCLI 会把设备只返回一次的长期 token 保存在当前用户的配置目录中。配对要求 物理在场；如果设备还没有联网，先按设备端配网说明 通过 USB 串口添加 Wi-Fi。换网络不需要重新编译固件。
安装当前 limb 可执行文件为用户级常驻服务，并查看它发现的设备：
limb daemon install
limb daemon status
limb listlimbd 只监听设备本地 gate 的加密通知并仲裁本机消费者；空闲时不与设备保持
TCP 连接，也不运行模型或保存会话。升级 CLI 后重新执行 limb daemon install
即可更新服务定义和可执行文件路径。
内置的 ListenAI provider 是默认选项，但不是协议绑定。先安全地保存 API key：
limb config set-credential listenai
limb say --device limb-a1b2c3 '你好，我是 limb。'API key 从终端提示读取，不会进入 shell 历史。provider 的替换、本地语音路径和 配置格式见 cli/providers.md。
已有裸 PCM 时可以完全绕过 TTS：
limb say --device limb-a1b2c3 --raw < mono-16k-s16le.pcm先运行 listen 建立本机订阅，再双击设备按键打开有硬截止时间的语音 gate：
limb listen --device limb-a1b2c3设备会发出只有已配对主机才能验证的短 UDP 通知；limbd 接受该 gate，并把设备
在握手期间缓存的开头音频交给 STT。默认的 listen 在第一个 final 后退出；
limb listen --follow 会跨多个物理 gate 保持同一个本机订阅。
要形成连续循环，把最终 speech NDJSON 交给一个从 stdin 读取请求、从 stdout 输出回答的命令：
limb watch --device limb-a1b2c3 --on-speech 'your-agent --once'watch 在整个运行期保持一个 daemon 订阅，所以模型调用和播报期间也不会错过
下一次本地通知。模型、上下文与会话生命周期都属于 your-agent；每轮仍需要
在设备上双击或使用本地唤醒词。更完整的 CLI 说明见
cli/README.md，首次真机验收记录见
cli/FIRST-CONTACT.md。
屏幕接口不解码 PNG/JPEG，也不提供字体或绘图原语。先在主机侧生成紧密排列的 RGB565 数据，再原样发送：
limb blit limb-a1b2c3 frame.rgb565 --preempt用户 KV 会随设备而不是随主机或 agent 迁移。例如调整扬声器数字增益：
limb kv set limb-a1b2c3 audio.out.digital_gain_db -20
limb kv get limb-a1b2c3 audio.out.digital_gain_db
limb kv del limb-a1b2c3 audio.out.digital_gain_db数值范围为 -113..30 dB；删除该键会恢复固件构建时的默认值。
反射适合语义已经封闭、需要低延迟或离线常驻的“感知 → 动作”，例如按键秒表。 它不是第二个 agent，也不能接管主人的语音通路。
CLI 可以初始化一个不带业务行为的 C 项目，并用本机 LLVM 构建、审计反射。它
不会自动下载编译器；需要 clang 和 wasm-ld，也可通过 LIMB_CLANG、
LIMB_WASM_LD 或对应命令行参数指定路径。
mkdir my-reflex && cd my-reflex
limb reflex init --name my-reflex
# 编辑 reflex.c 与 manifest.json
limb reflex build
limb reflex check工作区布局固定为 reflex.c、manifest.json 和生成的
build/reflex.wasm；init 会同时创建或补全忽略 /build/ 的
.gitignore。在工作区内无需任何路径参数，从外部执行时只传工作区目录。
build 只在模块通过 ABI、唯一导入、生命周期导出、内存、大小及 manifest
检查后才写入 build/reflex.wasm。check 完全离线；push 会在连接设备前重复
同一检查。
用同一工具链构建并安装仓库中的秒表示例：
limb reflex build device/examples/reflex/stopwatch
limb push limb-a1b2c3 device/examples/reflex/stopwatch/build/reflex.wasm \
--manifest device/examples/reflex/stopwatch/manifest.json \
--preempt
limb reflex status limb-a1b2c3安装后单击按键控制秒表；长按 1.6 秒可由基座停止当前反射。反射 ABI、资源预算 和更多示例见 device/README.md。
仓库内的 @listenai/openclaw-limb 同时
包含 channel 和设备操作/反射 skills。一台设备对应一个稳定的 OpenClaw 会话；
插件监听物理 gate 产生的语音，在同一设备上流式播出回复，但不会改变任何输入
权限。
从 monorepo 构建并安装：
cd integrations/openclaw-limb
npm ci
npm run check
npm test
npm pack --pack-destination /tmp
openclaw plugins install npm-pack:/tmp/listenai-openclaw-limb-0.1.0.tgz --force
openclaw channels add --channel limb --account limb-a1b2c3
openclaw gateway restart启用 channel 后，不要同时为同一设备运行另一个 limb listen 或 limb watch；
limbd 会让第二个消费者立即失败，并报告当前所有者。版本要求、多设备配置和
诊断命令见集成文档。
普通使用和换 Wi-Fi 都不需要重编固件。需要开发或烧录 ARCS Mini / Mini3 固件
时，请从 device/README.md 开始；两种板型共用一套应用代码，
通过 -DBOARD=arcs_mini 或 -DBOARD=arcs_mini3 选择板级适配。
仓库不分发板级 boot image。首次烧录必须从已授权的板卡发布渠道取得匹配的 boot， 不要把 Wi-Fi 凭据或本机 SDK 路径提交进仓库。
cli/ Rust CLI、liblimb 与 provider 配置
device/ ARCS Mini / Mini3 基座固件与反射示例
integrations/openclaw-limb/ OpenClaw channel 与 skills
PROTOCOL.md limb v0.2 协议事实源
AGENTS.md 产品宪法、架构决策与协作规则
除文件或第三方目录另有声明外，本仓库的源码、协议文档、skills 和示例均按
Apache License 2.0 提供。device/third_party/ 等目录中的第三方组件
保留各自的上游许可证与归属声明，其使用和再分发适用对应条款。
这是面向开发与核心假设验证的版本，不是量产安全方案。当前 demo token 在受信 局域网设备上以明文持久化；TLS、安全存储、旁路监听与重放防护仍需在量产前完成。 请只在你信任的网络中使用，并把物理 gate 指示灯视为输入是否开启的最终事实。