硬件子系统

ZeroClaw 的硬件子系统允许代理直接控制微控制器、单板计算机（SBC）和外设。通过启用 --features hardware 来激活此功能。

支持的内容

硬件子系统通过 USB VID/PID 识别开发板。规范注册表中的开发板：

开发板	架构	USB VID:PID
`nucleo-f401re`	ARM Cortex-M4	`0x0483`:`0x374b`
`nucleo-f411re`	ARM Cortex-M4	`0x0483`:`0x3748`
`arduino-uno`	AVR ATmega328P	`0x2341`:`0x0043`
`arduino-uno`	Arduino Uno Q / ATmega328P	`0x2341`:`0x0078`
`arduino-mega`	AVR ATmega2560	`0x2341`:`0x0042`
`cp2102`	USB-UART 桥接器	`0x10c4`:`0xea60`
`cp2102n`	USB-UART 桥接器	`0x10c4`:`0xea70`
`esp32`	ESP32 (CH340)	`0x1a86`:`0x7523`
`esp32`	ESP32 (CH340)	`0x1a86`:`0x55d4`

子系统使用的传输方式：

传输	描述
`serial`	基于 USB CDC 串口的换行符分隔 JSON
`swd`	SWD 调试探针 (probe-rs)
`uf2`	UF2 大容量存储固件烧录
`native`	直接 Linux GPIO/I2C/SPI（rppal、sysfs）

有关架构，请参阅外设设计；有关各开发板的接线方式，请参阅各开发板的设置指南（Nucleo、Arduino Uno Q、Raspberry Pi、Android）。

启用

在编译时：

sh

cargo build --release --features hardware

硬件功能包括 hardware（核心子系统）、peripheral-rpi（树莓派原生 GPIO）和 probe（probe-rs SWD 检视）。有关各开发板的配置字段，请参阅配置参考。

运行时工具

使用 hardware 功能时，该代理将获得以下内置工具：

gpio_read
gpio_write
pico_flash
device_read_code
device_write_code
device_exec

所有工具调用都会经过与其他工具相同的安全策略。硬件工具只能访问 [[peripherals.boards]] 条目中明确列出的设备路径：

在树莓派上运行

最常见的硬件目标。最小化设置：

sh

curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | sh

# 将自己添加到硬件组（重新登录后生效）
sudo usermod -aG gpio,spi,i2c $USER

# 作为用户服务安装（确保继承硬件组权限）
zeroclaw service install

默认的 systemd 单元设置了 SupplementaryGroups=gpio spi i2c。

安全

硬件工具可能会导致设备变砖。真实且昂贵的设备。

pico_flash 会写入固件；错误的镜像可能导致开发板变砖。无论自主级别如何，该工具都要求操作员在 Supervised 自主级别下进行批准；无法自动批准。
与外部驱动程序（电压冲突）冲突的 GPIO 写入会损坏引脚。

对于暴露了不可信通道的生产部署，请通过全局的 autonomy.non_cli_excluded_tools 列表将硬件工具排除在非 CLI 通道之外（该 schema 没有按通道设置的 tools_deny 字段）。列在其中的工具会在每个非 CLI 通道（Discord、Telegram、Bluesky 等）上从发送给模型的工具规格中省略。本地 CLI 仍然可以看到这些工具。

数据表

每块板的引脚映射和电气特性：

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

Keyboard shortcuts

ZeroClaw Docs