硬件 — 概述
ZeroClaw 的硬件子系统允许代理直接控制微控制器、单板计算机（SBC）和外设。通过启用 --features hardware 来激活此功能。
支持的内容
| 目标 | 协议 | 页面 |
|---|---|---|
| STM32 Nucleo (F401RE，其他型号) | 串行 / OpenOCD | STM32 Nucleo |
| Arduino Uno Q | 串行 / USB | Arduino Uno Q |
| 树莓派 | GPIO / I2C / SPI（通过 /dev/gpiochip*、/dev/i2c-*、/dev/spidev*） | 由外设设计覆盖 |
| Aardvark I2C/SPI 主机适配器 | USB | Aardvark |
| Android（通过 Termux） | USB/蓝牙串行 | Android |
| 通用板 | Peripheral 特性 | 添加板子和工具 |
有关架构信息，请参阅 外设设计。
启用
在编译时：
cargo build --release --features hardware
或者，如果您只想选择特定的板子：
cargo build --release --features 硬件板-Nucleo 板-Arduino
运行时工具
启用该功能后，代理将获得以下工具：
gpio_read/gpio_write— 数字输入/输出i2c_read/i2c_write— I2C 总线访问spi_transfer— SPI 传输adc_read— 模拟读取（在支持的情况下）peripheral_probe— 发现已连接的板卡和传感器peripheral_flash— 将固件刷写到已连接的开发板
All tool invocations go through the same security policy as any other tool. Hardware tools only reach the device paths explicitly listed in [[peripherals.boards]] entries:
[peripherals]
enabled = true
[[peripherals.boards]]
board = "nucleo-f401re"
transport = "serial"
path = "/dev/ttyACM0"
在树莓派上运行
最常见的硬件目标。最小化设置：
# 安装
curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | bash
# 将自己添加到硬件组（重新登录后生效）
sudo usermod -aG gpio,spi,i2c $USER
# 作为用户服务安装（确保继承硬件组权限）
zeroclaw service install
默认的 systemd 单元设置了 SupplementaryGroups=gpio spi i2c。
安全
硬件工具可能会导致设备变砖。真实且昂贵的设备。
peripheral_flash用于写入固件——错误的镜像可能导致主板变砖。无论自主级别如何，该工具都需要在Supervised（监督）自主模式下获得操作员批准；无法自动批准。- 向代理未知的设备地址执行
i2c_write/spi_transfer操作可能会损坏传感器。 - 与外部驱动程序（电压冲突）冲突的 GPIO 写入会损坏引脚。
For production deployments with untrusted channels exposed, keep hardware tools off non-CLI channels via the global autonomy config (the schema has no per-channel tools_deny field):
[autonomy]
non_cli_excluded_tools = ["gpio_write", "i2c_write", "spi_transfer", "peripheral_flash"]
Tools listed here are omitted from the tool specs sent to the model on every non-CLI channel (Discord, Telegram, Bluesky, etc.). The local CLI still sees them.
数据表
每块板的引脚映射和电气特性：
- STM32 Nucleo-F401RE: https://www.st.com/en/evaluation-tools/nucleo-f401re.html
- Arduino Uno Q: https://docs.arduino.cc/hardware/uno-q
- 树莓派 GPIO：https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#gpio
- ESP32: https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf
添加新硬件
请参阅 添加开发板与工具 获取逐步指南。TL;DR：实现 crates/zeroclaw-hardware/src/ 中的 Peripheral 特性，添加一个针对特定开发板的功能标志（feature flag），并编写一个探测例程，通过 USB 描述符或串行握手来识别开发板。