【OpenClaw具身硬件】ZeroClaw 源码阅读笔记（1）— 总体

罗西的思考

41人浏览 · 2026-08-25 20:58:40

罗西的思考 · 2026-08-25 20:58:40 发布

【OpenClaw具身硬件】ZeroClaw 源码阅读笔记（1）— 总体

文章目录

【OpenClaw具身硬件】ZeroClaw 源码阅读笔记（1）--- 总体

0x00 概要

本文是 ZeroClaw 的学习笔记。

ZeroClaw 是一个零开销、零妥协、100% Rust实现的AI助手框架，具有以下核心特点：

数字-物理桥梁：AI不仅处理数字信息，还能控制物理世界
环境感知：通过传感器获取真实环境数据
主动交互：能够主动改变物理环境状态
极致性能：优化编译配置（opt-level=“z”，lto=“fat”）生成最小二进制文件
多平台支持：支持CLI、WebGateway、桌面应用、硬件集成
模块化设计：高度可扩展的插件式架构
安全优先：内置多层安全机制和紧急停止功能

ZeroClaw 的总体如下图所示。

            设计目标: 单二进制 / 4.6 MB，能跑在 RPi 3 / 桌面 / 服务器                     
                            │                                            
    ┌───────────┬───────────┼─────────────┬───────────────┐                    
    │           │           │             │               │                    
    │           │           │             │               │                    
    ▼           ▼           ▼             ▼               ▼                    
体积控制      Runtime 抽象   硬件抽象      RAG/Memory      双模式架构                      
- opt z       - Native      - Peripheral  - keyword RAG   - Edge-Native   
- LTO fat     - Docker      - trait       - SQLite FTS    - Host-Mediated 
- feature gate- WASM 解释器  - no_std fw   - 可选 vector    - 协议先行              
- 32-bit ok   - 默认零容器   协议 crate                        多板适配

注：本系列在草稿箱里躺了几个月，才排上顺序放出来，因此可能解读的代码不是最新，还请谅解。

0x01 基础知识

因为 ZeroClaw 也是 OpenClaw，所以我们本节概略介绍基础知识。

1.1 主要功能

ZeroClaw 的主要功能如下：

核心AI引擎（src/agent）

Agent主循环：处理用户输入、调用工具、生成响应的完整工作流
上下文管理：历史对话压缩、内存加载、会话状态维护
智能路由：根据查询内容自动选择合适的模型和工具
安全策略：执行前的安全检查和权限验证

工具系统（src/tools）提供丰富的内置工具能力：

基础工具：计算器、文件编辑、浏览器操作、CLI命令执行
通信工具：邮件发送、消息推送、通知管理
定时任务：Cron作业管理（添加、删除、更新）
硬件控制：GPIO操作、传感器读取、设备控制
AI专用：代码生成、内容搜索、委派代理

通信渠道（src/channels）支持多种消息平台集成：

即时通讯：Telegram、Discord、Slack、WhatsApp、Matrix
企业应用：Lark/Feishu、DingTalk、Email
协议支持：WebSocket、HTTP Webhook、ACPT （Agent Control Protocol）
会话管理：每个渠道独立的会话历史和状态跟踪

Web网关（src/gateway) 基于Axum的HTTP服务：

REST API：提供完整的API接口用于外部集成
WebSocket：实时双向通信支持
静态文件服务：内嵌Web前端界面
安全认证：配对码验证、HTTPS支持、请求限制

AI模型提供商（src/providers）统一的模型抽象层：

主流提供商：OpenAI、Anthropic、Google Gemini、Azure、OpenAI
开源模型：Ollama、兼容API的本地模型
路由策略：智能模型选择和故障转移
成本跟踪：API调用成本监控和优化

物理设备控制能力：

USB设备发现：自动识别开发板（STM32、Arduino、ESP32）
串口通信：与微控制器的双向通信
GPIO控制：树莓派等单板计算机的引I脚控制
机器人套件：完整的机器人控制框架（驱动、视觉、语音、传感）

1.2 系统架构

在系统架构上，ZeroClaw核心理念如下：

零开销、零妥协：极致优化的二进制大小和内存占用
100% Rust实现：完全避免运行时依赖，确保跨平台一致性
单一的二进制文件：简化部署和维护，无需复杂的依赖管理
本地优先：所有数据和处理都在用户设备上完成

这个架构设计使得ZeroClaw既能作为轻量级CLI工具使用，也能部署为企业级AI服务平台，同时支持硬件集成和机器人应用场景。总体架构图如下：

1-系统架构

1.2.1 层级关系

ZeroClaw 可以分为三层。

层级	模块	功能
CLI Entry	main.rs	程序入口
Core Subsystems	config/	配置与 Schema
	agent/	编排循环
	providers/	LLM 适配器
	channels/	消息平台
	tools/	工具执行
	memory/	存储后端
	security/	策略与配对
	runtime/	执行适配器
	gateway/	HTTP/Webhook 服务器
	daemon/	监督运行时
	peripherals/	硬件控制
	observability/	遥测与指标
	rag/	硬件文档
	cron/	调度器
	skills/	用户能力
Integrations	Composio	1000+ 应用
	Browser	Brave 集成
	Tunnel	Cloudflare/boringproxy

1.2.2 模块图

ZeroClaw 的模块图如下：

High-level component structure 1

颜色	类别
🟠 橙	CLI Entry (入口)
🔵 蓝	Core Subsystems (核心子系统)
🟢 绿	Integrations (集成)

1.2.3 依赖关系

上述模块之间的依赖关系如下：

main.rs  ──→ Config, Agent, Gateway, Daemon, Channels

Agent    ──→ Providers, Tools, Memory, Security, Runtime, Peripherals, RAG, Skills

Channels ──→ Agent
Gateway  ──→ Agent

Daemon   ──→ Gateway, Channels, Cron, Observability

Tools    ──→ Composio, Browser
Gateway  ──→ Tunnel

1.3 CLI

CLI 的图太难渲染，用语言描述如下：

主节点：zeroclaw CLI 作为起点，辐射出15个子命令模块（如 onboard, agent, gateway 等）。
子命令分支：agent 进一步分为 -m message（单次执行）和 Interactive REPL（交互式终端）。daemon 扩展为 Supervised runtime（包含 Gateway + Channels + Scheduler 的组合功能）。

Ways ZeroClaw can be run 1

原始公式如下：

flowchart TD
    Start[zeroclaw CLI] --> Onboard[onboard<br/>Setup wizard]
    Start --> Agent[agent<br/>Interactive CLI]
    Start --> Gateway[gateway<br/>HTTP server]
    Start --> Daemon[daemon<br/>Long-running runtime]
    Start --> Channel[channel<br/>Messaging platforms]
    Start --> Service[service<br/>OS service mgmt]
    Start --> Models[models<br/>Provider catalog]
    Start --> Cron[cron<br/>Scheduled tasks]
    Start --> Hardware[hardware<br/>Peripheral discovery]
    Start --> Peripheral[peripheral<br/>Hardware management]
    Start --> Status[status<br/>System overview]
    Start --> Doctor[doctor<br/>Diagnostics]
    Start --> Migrate[migrate<br/>Data import]
    Start --> Skills[skills<br/>User capabilities]
    Start --> Integrations[integrations<br/>Browse 50+ apps]

    Agent --> AgentSingle[-m message<br/>One-shot]
    Agent --> AgentInteractive[Interactive REPL<br/>stdin/stdout]

    Daemon --> DaemonSupervised[Supervised runtime<br/>Gateway + Channels + Scheduler]

ZeroClaw CLI 命令结构如下：

命令	功能
`onboard`	设置向导
`agent`	交互式 CLI
`gateway`	HTTP 服务器
`daemon`	长期运行运行时
`channel`	消息平台
`service`	OS 服务管理
`models`	提供商目录
`cron`	定时任务
`hardware`	外设发现
`peripheral`	硬件管理
`status`	系统概览
`doctor`	诊断工具
`migrate`	数据导入
`skills`	用户能力
`integrations`	浏览 50+ 应用

1.4 消息流程

控制流如下：

User Request
    │
    ▼
Agent Decision (LLM)
    │
    ▼
Tool Selection (Hardware Capabilities)
    │
    ▼
Peripheral Execution (Physical Operation)
    │
    ▼
Result Feedback to User

控制流步骤

步骤	操作
1	User Request (用户请求)
2	Agent Decision (LLM 决策)
3	Tool Selection (硬件能力选择)
4	Peripheral Execution (物理操作执行)
5	Result Feedback to User (结果反馈给用户)

消息在系统中的详细流程如下：

Message Flow Through The System

1.5 Agent Loop

此处需要重点关注 Hardward RAG 相关的逻辑，后续文章会有相关解读。

Agent Loop Execution Flow

1.6 扩展

1.6.1 多层扩展结构

ZeroClaw 的可扩展性如下：

Trait 驱动：所有核心扩展点（Provider、Channel、Tool、Memory 等）通过 Rust trait 定义
插件系统：WASM插件支持（可选特性）。插件系统的设计意图是让第三方不需要编译整个项目就能扩展ZeroClaw，但目前还处于脚手架阶段。
技能系统：用户自定义技能创建和管理
模块化设计：各组件松耦合，易于替换和扩展

┌──────────────────────────────────────────────────────────┐
│  EXTENSION ECOSYSTEM                                     │
├──────────────┬──────────────┬───────────────┬────────────┤
│  PROVIDERS   │  CHANNELS    │    TOOLS      │  HARDWARE  │
├──────────────┼──────────────┼───────────────┼────────────┤
│ • OpenAI     │ • WhatsApp   │ • Shell/File  │ • ESP32    │
│ • Anthropic  │ • Telegram   │ • Browser     │ • STM32    │
│ • Gemini     │ • Slack      │ • Git         │ • Raspberry│
│ • Ollama     │ • Discord    │ • MCP         │   Pi       │
│   (local)    │ • 20+        │   Protocol    │ • Arduino  │
│ • 20+ others │   platforms  │ • 90+ built-in│ • Aardvark │
└──────────────┴──────────────┴───────────────┴────────────┘

多层次的扩展架构使ZeroClaw能够在保持轻量级（<5MB内存占用）、本地优先和高安全性的同时，提供丰富的硬件和软件集成能力，满足从简单控制到复杂物联网应用的各种需求。

1.6.2 外设作为扩展点

新特征：`Peripheral`

/// A hardware peripheral that exposes capabilities as tools.
#[async_trait]
pub trait Peripheral: Send + Sync {
    fn name(&self) -> &str;
    fn board_type(&self) -> &str;  // e.g. "nucleo-f401re", "rpi-gpio"
    async fn connect(&mut self) -> anyhow::Result<()>;
    async fn disconnect(&mut self) -> anyhow::Result<()>;
    async fn health_check(&self) -> bool;
    /// Tools this peripheral provides (gpio_read, gpio_write, sensor_read, etc.)
    fn tools(&self) -> Vec<Box<dyn Tool>>;
}

流程

启动： ZeroClaw 加载配置，读取 peripherals.boards。
连接： 为每个开发板创建 Peripheral 实现，调用 connect()。
工具： 收集所有连接外设的工具；与默认工具合并。
代理循环： 代理可以调用 gpio_write、sensor_read 等 —— 这些调用委托给外设。
关闭： 对每个外设调用 disconnect()。

开发板支持

开发板	传输方式	固件 / 驱动	工具
nucleo-f401re	串口	Zephyr / Embassy	gpio_read, gpio_write, adc_read
rpi-gpio	原生	rppal or sysfs	gpio_read, gpio_write
esp32	串口/websocket	ESP-IDF / Embassy	gpio, wifi, mqtt

1.6.3 软件扩展

ZeroClaw 以 trait 驱动为核心，同时有一套 WASM 插件系统正在建设中。

Trait驱动（核心，已完善）
- 新实现编译进二进制，零运行时开销一这是当前实际生产使用的方式
- Trait驱动在编译期验证接口契约，零运行时开销，与Rust 的所有权/类型系统深度集成。
- 所有核心扩展点（Provider、Channel、Tool、Memory 等）通过 Rust trait 定义
- 取舍是：扩展必须编译进二进制（不能热插拔），新增 provider/channel/tool 需要改代码并重新构建。
WASM插件系统（实验性，部分完成）
- 位于 src/plugins/，通过 --features plugins-wasm 启用
- 使用Extism作为WASM运行时
- 支持的插件类型：Tool、Channel、Memory、Observer
- 有完整的权限模型（HttpClient、FileRead、FileWrite、EnvRead、MemoryRead/Write)
- 有Ed25519签名验证机制（Disabled/Permissive/Strict三种模式）
- 但WASM执行桥还未实现 -WasmTool.execute()里写着// ToDo:Call into Extism plugin runtime，目前返回占位错误

1.7 安全与约束机制

1.7.1 安全边界

┌─────────────────────────────────────────────────────────────────────────────────┐
│                           Security Layers                                       │
├─────────────────────┬─────────────────────┬─────────────────────┬───────────────┤
│   Path Whitelist    │   GPIO Pin Limits   │  Firmware           │  Network      │
│   (/dev/ttyACM*)    │   (No Reset Pins)   │  Validation         │  Isolation    │
│                     │                     │  (Version Check)    │  (Sandbox)    │
└─────────────────────┴─────────────────────┴─────────────────────┴───────────────┘

层级	约束
Path Whitelist	/dev/ttyACM*
GPIO Pin Limits	No Reset Pins
Firmware Validation	Version Check
Network Isolation	Sandbox

1.7.2 执行环境约束

┌─────────────────────────────────────────────────────────────────────────────────┐
│                        Execution Constraints                                    │
├─────────────────────┬─────────────────────┬─────────────────────┬───────────────┤
│   Wasm Sandbox      │   Template Library  │  Dynamic Linking    │  Pre-compiled │
│   (Isolated)        │   (Parameterized)   │  (Platform-specific)│  (Fast/Secure)│
└─────────────────────┴─────────────────────┴─────────────────────┴───────────────┘

约束类型	特性
Wasm Sandbox	Isolated
Template Library	Parameterized
Dynamic Linking	Platform-specific
Pre-compiled	Fast/Secure

0x02 硬件系统理念

ZeroClaw 让微控制器（MCU，Microcontroller Unit）和单板计算机（SBC，Single Board Computer）能够动态解释自然语言命令，生成硬件特定代码，并实时执行外设交互。这种硬件系统使得 ZeroClaw 不仅仅是一个软件AI助手，而是一个能够与物理世界交互的智能代理，为用户提供真正的“ 物理AI助手“体验。

2.1 硬件抽象层架构

ZeroClaw 的硬件架构被抽象为如下层：

层级	组件	说明
Boards	Nucleo-F401RE	STM32F401RETx
	Arduino Uno	ATmega328P
	Uno Q	ESP32 WiFi bridge
	RPi GPIO	Native Linux
	ESP32	Direct serial
Transport	Serial port	/dev/ttyACM0, /dev/ttyUSB0
	USB probe-rs	ST-Link JTAG
	Native GPIO	Linux sysfs
Peripherals	create_peripheral_tools	工厂函数
	gpio_read/write	数字 I/O
	arduino_upload	Sketch 刷写
	hardware_memory_map	地址范围
	hardware_board_info	芯片识别
	hardware_memory_read	寄存器转储
	hardware_capabilities	引脚枚举
Hardware RAG	datasheet_dir	.md 文档
	Chunked embedding	语义搜索
	Pin alias mapping

ZeroClaw 的硬件层次架构如下图所示：

Hardware Peripherals Integration

颜色	类别
🔵 蓝	Board (开发板)
🟠 橙	Transport (传输层)
🟢 绿	Peripheral (外设系统)
🔴 红	RAG (检索增强生成)

2.2 流程

从下至上

我们来把硬件信号到Agent的端到端路径简洁说明一下。

流程概览：硬件→固件/驱动→传输层（serial/gRPC/websocket/MQTT）→ZeroClaw外设适配器（Peripheral）→暴露为工具（如gpio_read/gpio_write）→代理循环/规则（SoP/cron/Hands）调用工具并产生响应/动作。

固件与协议：设备上运行的固件（例如eSp32）实现轻量协议（串口JSON或gRPC/nanoRPC），将硬件事件/命令（GPIO、I2C、传感器数据）序列化传给主机；主机也用同协议下发控制命令。参见示例与说明： hardware-peripherals-design.zh-CN.md。

ZeroClaw侧接收与适配：ZeroClaw为每种板卡实现Peripheral（外设）适配器，负责连接（serial/gRP C/native）、能力暴露（tool列表）、健康检查与命令转发。代理通过这些工具接口直接读写硬件（见P
eripheral设计与工具注册流程，文档说明在上面的硬件设计文件）

数据流向如下：

Boards → Transport → Peripherals → ToolRegistry → Agent loop integration
                                          ↑
RAG (Context injection) ------------------┘

至上而下

至上而下就是用户角度的数据流，其详细数据流向如下：

详细数据流向如下：

1-用户角度的数据流

2.3 双模式硬件架构

ZeroClaw 是双模式的硬件架构。

ZeroClaw双模式=“看设备能力分配大脑位置"：能跑就端上跑（Mode 1），跑不动就主机跑、设备只当手脚（Mode2）。一份代码、一份协议、一套Tool接口一这是把LLM Agent从云端真正下沉到MCU的最务实路径。

┌──────────┬────────────────────────────┬──────────┬─────────┬─────────────────────────┐
│ 设备类别  │ 典型代表                   │ 内存      │ OS      │ 能跑完整 Rust + tokio +  │
│          │                            │          │         │ sqlite 吗?              │
├──────────┼────────────────────────────┼──────────┼─────────┼─────────────────────────┤
│ 小型 Linux│ Raspberry Pi 3/4/5、x86   │ ≥ 256 MB  │ Linux   │ ✅ 能 (这是主战场)       │
│ SBC      │ 边缘盒、ARM 工控机、车规 SoC  │ - 8 GB   │         │                         │
├──────────┼────────────────────────────┼──────────┼─────────┼─────────────────────────┤
│ 裸 MCU /  │ STM32 Nucleo、Arduino      │ KB - 几  │ 无 OS / │ ❌                      │
│ RTOS 板  │ Uno、ESP32(-S3)、RP2040     │ MB SRAM  │ RTOS     │ 跑不了主体, 但可跑协议端  │
└──────────┴────────────────────────────┴──────────┴─────────┴─────────────────────────┘

Mode 1: Edge-Native（端原生/独立运行）

ZeroClaw完整二进制跑在设备上，Agent loop/Channel/RAG/ Memory 全在端。比如：Linux设备（RPi3/4/5/x86盒/车规SoC）

1-Edge-Native

开发板启动 gRPC/nanoRPC 服务器，与本地外设通信。

1-ZeroClaw on ESP32

工作流如下：

用户发送 WhatsApp 消息：“打开引脚 13 上的 LED”
ZeroClaw 获取开发板特定文档（例如 ESP32 GPIO 映射）
LLM 合成 Rust 代码
代码在沙箱中运行（Wasm 或动态链接）
GPIO 被切换；结果返回给用户
优化后的代码被持久化，供未来"打开 LED"请求使用

所有操作都在设备上完成。 不需要主机。

Mode 2: Host-Mediated（主机中介开发/调试）

ZeroClaw 跑在主机（Mac / Linux），裸 MCU 上只跑协议端固件，维护到目标的硬件感知链接，即两端通过 USB/串口/JTAG 通信。用于开发、内省和烧录。

1-Host-Mediated

比如：

1-ZeroClaw on Mac

用户视角工作流

用户：“读ESP32上GPIO 5的电平“

主机ZeroClaw→discover.rs找到·ESP32串口（或用配置中已知端口）
Agent 的read_gpio Tool →transport.rs发送 JsoN命令到串口
ESP32固件解析→调eSp-idf-hal读GPIO→回JSON
主机LLM拿到结果→回答用户

或：

用户发送 Telegram 消息：“这个 USB 设备上的可读内存地址是什么？”
ZeroClaw 识别连接的硬件（VID/PID、架构）
执行内存映射；建议可用的地址空间
将结果返回给用户

或：

用户：“将这个固件烧录到 Nucleo”
ZeroClaw 通过 OpenOCD 或 probe-rs 写入/烧录
确认成功

或：

ZeroClaw 自动发现：“STM32 Nucleo 位于 /dev/ttyACM0，ARM Cortex-M4”
建议：“我可以读取/写入 GPIO、ADC、闪存。你想做什么？”

重要：ESP32 端不跑LLM、不跑Agent loop、不知道用户问了什么。它只是一个 JSON-over-serial 的“远程外设服务器”。

模式对比

方面	边缘原生	主机介导
ZeroClaw 运行位置	设备	主机（Mac、Linux）
硬件链接	本地（GPIO、I2C、SPI）	USB、J-Link、Aardvark
LLM	设备端或云端（Gemini）	主机（云端或本地）
使用场景	生产环境、独立运行	开发、调试、内省
渠道	WhatsApp 等（通过 Wi-Fi）	Telegram、CLI 等

2.4 硬件发现与连接流程

1-硬件发现与连接流程

硬件发现流程步骤如下：

步骤	组件	功能
1	USB Enumeration	discover_hardware
2	VID/PID Match	DeviceRegistry
3	Board Registry Registration	注册板卡
4	Peripheral Connection	外设连接
5	Transport Attachment	传输层附加
6	Auto-detect Pico BOOTSEL	自动检测

2.5 硬件工具

类别	工具
GPIO	gpio_read, gpio_write
系统信息	rpi_system_info
SPI	spi_transfer
I2C	i2c_scan, i2c_read, i2c_write
内存	memory_read
ADC	adc_read
Flash	flash_write
传感器	sensor_read
设备执行	device_exec

2.6 硬件参考

ESP32 GPIO 参考

引脚别名

别名	引脚
builtin_led	2
red_led	2

常用引脚（ESP32 / ESP32-C3）

GPIO 2：许多开发板上的内置 LED（输出）
GPIO 13：通用输出
GPIO 21/20：常用于 UART0 TX/RX（如果使用串口请避免占用）

协议

ZeroClaw 主机通过串口发送 JSON（波特率 115200）：

gpio_read：{"id":"1","cmd":"gpio_read","args":{"pin":13}}
gpio_write：{"id":"1","cmd":"gpio_write","args":{"pin":13,"value":1}}

响应：{"id":"1","ok":true,"result":"0"} 或 {"id":"1","ok":true,"result":"done"}

Arduino Uno

引脚别名

别名	引脚
red_led	13
builtin_led	13
user_led	13

概述

Arduino Uno 是基于 ATmega328P 的微控制器开发板。它有 14 个数字 I/O 引脚（0–13）和 6 个模拟输入（A0–A5）。

数字引脚

引脚 0–13： 数字 I/O。可设置为 INPUT 或 OUTPUT。
引脚 13： 板载内置 LED。可将 LED 连接到 GND 或用作输出。
引脚 0–1： 也用于串口（RX/TX）。如果使用串口请避免占用。

GPIO

输出使用 digitalWrite(pin, HIGH) 或 digitalWrite(pin, LOW)。
输入使用 digitalRead(pin)（返回 0 或 1）。
ZeroClaw 协议中的引脚编号：0–13。

串口

UART 位于引脚 0（RX）和 1（TX）。
通过 ATmega16U2 或 CH340（克隆板）实现 USB 连接。
ZeroClaw 固件使用的波特率：115200。

ZeroClaw 工具

gpio_read：读取引脚值（0 或 1）。
gpio_write：设置引脚为高电平（1）或低电平（0）。
arduino_upload：代理生成完整的 Arduino 草图代码；ZeroClaw 通过 arduino-cli 编译并上传。用于"制作心形"、自定义图案等场景 —— 代理编写代码，无需手动编辑。引脚 13 = 内置 LED。

TransFormer-封面