添加开发板和工具：ZeroClaw 硬件指南

本指南说明如何向 ZeroClaw 添加新的硬件板和自定义工具。

快速入门：通过 CLI 添加看板

sh

# 添加开发板
zeroclaw peripheral add nucleo-f401re /dev/ttyACM0
zeroclaw peripheral add arduino-uno /dev/cu.usbmodem12345
zeroclaw peripheral add rpi-gpio native   # 适用于树莓派 GPIO（Linux）

# 重启守护进程以应用
zeroclaw daemon --host 127.0.0.1 --port 42617

支持的板子

开发板通过 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`

[[peripherals.boards]] 中的 board 值会与这些注册表名称（以及少数特定于传输方式的别名，例如在 peripherals/mod.rs 中处理的 arduino-uno-q / rpi-gpio）进行匹配。

手动配置

主板在 peripherals 和 peripherals.boards 下进行配置。完整的字段索引请参阅配置参考，其中包括 datasheet_dir（RAG 源）。

将 .md 或 .txt 文件放入 docs/datasheets/（或你的 datasheet_dir）中。按板卡命名文件：nucleo-f401re.md、arduino-uno.md。文件会被提取、分块，并检索到代理的上下文中，用于板卡特定问题。自 #8519 起不再支持 PDF datasheet 解析；在建立索引前，请先将 PDF 转换为 .md 或 .txt。

别名（推荐）

添加一个 ## Pin Aliases 部分，以便代理可以将 “red led” 映射到引脚 13：

# My Board

## Pin Aliases

| alias       | pin |
|-------------|-----|
| red_led     | 13  |
| builtin_led | 13  |
| user_led    | 5   |

或者使用键值格式：

## Pin Aliases
red_led: 13
builtin_led: 13

添加新的板卡类型

创建数据表：docs/datasheets/my-board.md，包含引脚别名和 GPIO 信息。
添加到配置：zeroclaw peripheral add my-board /dev/ttyUSB0
实现外设（可选）：对于自定义协议，在 crates/zeroclaw-hardware/src/peripherals/ 中实现 Peripheral trait，并在 create_peripheral_tools 中注册。

完整设计请参阅 docs/hardware/hardware-peripherals-design.md。

添加自定义工具

在 crates/zeroclaw-tools/src/ 中实现 Tool 特质。
在 create_peripheral_tools（用于硬件工具）或代理工具注册表中注册。
在 crates/zeroclaw-runtime/src/agent/loop_.rs 中向 agent 的 tool_descs 添加工具描述。

CLI 参考

有关 zeroclaw peripheral 和 zeroclaw hardware 子命令的详细信息，请参阅生成的 CLI 参考文档。

故障排除

找不到串口：在 macOS 上使用 /dev/cu.usbmodem*；在 Linux 上使用 /dev/ttyACM0 或 /dev/ttyUSB0。
使用硬件构建：cargo build --features hardware
用于 Nucleo 的 Probe-rs：cargo build --features hardware,probe

ZeroClaw Docs