【OpenClaw具身硬件】ZeroClaw 源码阅读笔记（4）--- 代码执行

【OpenClaw具身硬件】ZeroClaw 源码阅读笔记（4）--- 代码执行

0x00 概要

本文是 ZeroClaw 的学习笔记。

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

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

ZeroClaw 的总体如下图所示。

关于代码生成和执行，总体情景如下：

0x01 代码合成

代码合成（Code Synthesis）指AI系统根据自然语言描述或高级规范自动生成可执行的Rust代码，它使得AI助手不仅能够理解和回答问题，还能够主动创建和执行解决方案。

1.1 核心思想

核心设计思想：ZeroClaw 自己不写代码，而是做“编排层”，把复杂编码任务委派给专业 coding agent。即，ZeroClaw做高层编排 → 编码细节交给ClaudeCode自己的Read/Edit/Bash循环。

代码合成是Two-Tier Delegation 架构。

具体的 Tool 如下。

Tool	后端	特点
claude_code	Claude Code CLI (claude -p)	最丰富：allowed_tools、session 复用、json_schema 结构化输出
claude_code_runner	tmux + HTTP hooks	异步长任务：立即返回 session ID，通过 webhook 推送进度到 Slack
codex_cli	OpenAI Codex CLI （codex -q)	OpenAI 侧编码
gemini_cli	Gemini CLI （gemini -p)	Google 侧编码
opencode_cli	OpenCode CLI （opencode run)	开源替代

其关键特点如下：

“不自己写代码“的哲学：ZeroClaw定位是编排层，代码合成委派给Claude/Codex/Gemini，自己只负责安全、调度、路由
多后端沙箱：不是象征性的沙箱，是5 种真实 OS-level isolation （Landlock/Firejail/Bubblewrap/Seatbelt/Docker）
风险分级 +审批：命令按 High/Medium/Low 分级，Supervised 模式下 Medium 以上需 approved=true
环境零泄露：env_clear()+白名单，杜绝 API Key 通过子进程泄露
异步长任务支持：claude_code_runner 通过 tmux +HTTP hook 做真正的“后台编码"，支持 SSH 接入观察
Pipeline 减少推理：多步操作合并为一次调用，降低 token 成本

1.2 业务逻辑

具体应用场景

GPIO控制代码生成：

用户说“让LED闪烁“
AI生成相应的RustGPIO控制代码
代码被编译并部署到目标设备

传感器读取代码：

用户请求“读取温度传感器数据“
生成I2C/SPI通信的Rust代码
执行并返回传感器读数

能力体现

代码合成能力主要体现在：

Agent智能决策：根据用户需求动态生成合适的Rust代码
Tools工具系统：提供安全的代码生成和执行环境
硬件集成：自动生成设备控制和固件代码
安全保障：在严格的约束下确保代码生成的安全性

技术实现方式

LLM驱动：利用大型语言模型理解用户意图并生成相应代码
模板填充：基于预定义的代码模板进行参数化生成
约束优化：在安全策略和性能要求的约束下生成最优代码

动态执行能力：

生成的Rust 代码可以通过WASM或动态执行机制运行
支持沙箱环境中的安全代码执行
提供执行结果反馈和错误处理

1.3 实现细节

代码生成流程：用户输入→意图识别→代码生成→安全验证→编译执行→结果返回

生成种类

ESP32固件生成：

根据用户配置自动生成ESP32的Rust固件代码
位于firmware/esp32/src/目录下
支持自动部署到ESP32设备

Arduino固件生成：

自动生成Arduino.ino格式的固件
通过zeroclaw peripheral flash命令触发
集成arduino-cli进行编译和上传

Peripheral外设模块的硬件控制代码生成：

根据连接的外设类型生成相应的控制代码
自动适配不同的硬件平台（STM32、ESP32、树莓派等）
生成优化的底层硬件操作代码

Rust 代码

ZeroClaw选择Rust是基于其独特的技术优势组合：

性能与安全的完美平衡：既提供C/C++级别的性能，又保证内存安全
资源效率：极小的内存占用和二进制大小，适合边缘计算场景
并发安全：天生的并发安全特性，适合多任务AI助手架构
跨平台能力：统一代码库支持从桌面到嵌入式的全平台部署
生态系统成熟：丰富的库和工具链支持快速开发

这种选择完美契合了ZeroClaw"零开销、零妥协“的核心理念，使得项目能够在保持极致性能的同时，提供企业级的安全性和可靠性保障。

另外，Rust 代码可以通过Termux运行在Android之上。

Arduino CLI的功能定位

主要功能

固件编译：将.ino文件编译为ESP32/Arduino可执行的二进制文件
设备烧录：将编译好的固件上传到Arduino/ESP32开发板
库管理：管理Arduino库依赖和版本

代码生成能力

间接代码生成：ArduinoCLI本身不直接生成代码，而是由ZeroClaw生成.ino代码后调用ArduinoCLI进行编译
模板填充：ZeroClaw基于预定义模板生成完整的Arduino项目结构
自动配置：根据用户需求自动生成合适的引脚配置和功能代码

自动生成流程

用户请求→ZeroClaw生成.ino代码→调用ArduinoCLI编译→烧录到设备
核心组件
- Agent模块：负责整体决策和代码生成逻辑
- Peripheral模块：管理外设配置和硬件抽象
- Too1s模块：提供具体的代码生成和执行工具
- Firmware目录：包含预定义的固件模板和示例
生成流程概述
- 用户意图识别：Agent分析用户自然语言请求
- 硬件需求解析：确定所需的传感器、执行器和引脚配置
- 模板选择：从预定义模板中选择合适的Arduino项目结构
- 代码合成：填充模板参数，生成完整的.ino文件
- 依赖分析：确定需要的Arduino库和配置
- 自动部署：调用ArduinoCLI进行编译和烧录

1.4 ClaudeCode Tool如何被大模型使用

我们以ClaudeCode Tool为例，看看ZeroClaw如何生成代码。

第一步：tool.spec()生成工具描述

每个工具实现Tooltrait的三个方法：

fn name()----->"claude_code"
fn description()---->"Delegate a coding task to Claude Code...
fn parameters_schema(）----->{type:"object",properties:{prompt,allowed_tools,session_id...}}

tool.spec()把这三者打包成ToolSpec。

第二步：注册到Agent

//AgentBuilder::build()
let tool_specs=tools.iter().map(|tool| tool.spec()).collect();
//tool_specs：Vec<ToolSpec> -所有工具的描述列表

第三步：转换为LLM Function Calling格式

每次调用LLM时，provider.chat(ChatRequest{messages，tools:Some(&tool_specs)}）把工具传给provider：

//openai.rs:convert_tools() 
NativeToolSpec {
    kind:"function",
    function:NativeToolFunctionSpec{
        name:"claude_code",
        description:"Delegate a coding task..."
        parameters:{/*JsoN Schema */}
    }
}

OpenAI/Anthropic/Gemini等各provider各自负责把ToolSpec转换成自己平台的格式（OpenAI用tools字段，Anthropic用tools数组，Gemini用funciton_declarations)

第四步：LLM返回tool_call，ZeroClaw分发执行

LLM响应:{tool_calls:[{name:"claude_code"，arguments:{prompt:"..."}}]} 
↓
dispatcher.dispatch("claude_code",args) 
↓
ClaudeCodeTool::execute(args)
└── 启动子进程: claude -p "..."
    │
    └── Claude Code CLI 的 agent loop:
        ├── 生成代码 -> Edit("src/main.py", ...)
        ├── 执行代码 -> Bash("python src/main.py")
        │              ↑ 在同一台机器上执行
        └── 返回结果给 zeroclaw
↓
结果返回给LLM继续对话

0x02 代码执行

ZeroClaw中的 WASM / Dynamic Exec 机制是一个安全、灵活、高效的动态代码执行平台，它使得：

AI生成的代码能够安全执行：通过WASM沙箱和严格的权限控制
硬件操作变得简单直观：用户无需编写底层硬件代码
系统保持高度可扩展性：支持多种编程语言和执行环境
性能和安全性得到平衡：既保证了执行效率，又确保了系统安全

这种设计完美体现了ZeroClaw"零开销、零妥协“的理念，让用户能够充分发挥创造力，同时享受企业级的安全保障。

2.1 核心概念

基本定义

WASM（WebAsSembly）：一种可移植、体积小、加载快的二进制格式，可在多种环境中安全执行
DynamicExec（动态执行）：在运行时动态生成并执行代码的能力
组合使用：ZeroClaw将两者结合，实现安全的动态代码执行环境

在架构图中的位置

Code synthesis → Wasm / dynamic exec → GPIO / I2C / SPI → persist

流程解释：AI生成的代码→WASM沙箱执行→硬件操作→持久化存储

WASM执行机制

功能特性：

安全的沙箱环境执行用户代码
支持Rust、C、Go等语言编译的WASM模块
提供主机函数调用接口（Host Functions）

Dynamic Exec动态执行

代码生成与执行流程

AI代码合成：Agent根据用户需求生成Rust代码
编译阶段：将生成的代码编译为可执行格式
执行阶段：在受限环境中运行生成的代码
结果收集：捕获执行结果和可能的错误

执行环境类型

沙箱进程：通过子进程隔离执行，限制系统权限
WASM沙箱：对于支持WASM的语言，在WASM运行时中执行
解释器模式：对于脚本语言，使用相应的解释器执行

8 层纵深执行架构

2.2 关键组件

ShellTool

ZeroClaw主要是使用ShellTool-带沙箱的 shell 命令执行：

超时保护：默认 60s超时自动 kill
输出截断：stdout/stderr 各限 1MB，防止 OOM
环境净化：env_clear()后仅传入安全白名单变量（PATH/HOME/TERM 等），绝不泄露 API Key
命令风险分级：Low/ Medium / High，配合 AutonomyLevel（Supervised / Full）做审批门控
工作区边界：所有路径经 canonicalize()防止 symlink 逃逸

5种沙箱后端（Sandbox trait）：

后端	平台	隔离强度
Landlock	Linux 5.13+	内核级文件系统限制
Firejail	Linux	用户态沙箱
Bubblewrap	Linux	轻量级 namespace
Seatbelt	macos	Apple sandbox-exec
Docker	全平台	容器隔离

启动时自动探测最强可用后端（detect.rs），对每个 shell 命令执行前调用 sandbox.wrap_command()。

SOP工作流引擎

SOP（Standard Operating Procedure）是一个多步骤自动化工作流引I擎，从 TOML/Markdown
文件定义，支持多种触发源和执行模式。

触发器（5种事件源）

MQTT topic →      ──┐                                        
Webhook path →    ──┼                                        
Cron表达式 →       ──┼──► SopEngine.match_trigger() → start_run()   
Peripheral 信号 →  ──┼                                        
Manual手动 →      ───┘ 

条件匹配支持 JsoN Path：S.sensor.temperature > 85

Skill 动态加载系统

三层来源

用户本地：~/.zeroclaw/workspace/skills//SKILL.toml 或 SKILL.md
Open Skills 社区仓库：自动从 besoeasy/open-skills GitHub 仓库同步（7天一次）
ClawHub 注册中心：clawhub.ai 在线下载安装（50MB 上限 ZIP）

Skill→Tool 转换

Skill 定义 （SKILL.toml）
    - [[tools]] kind="shell"   →   SkillShellTool(命令模板+参数替换{{arg}})
    - [[tools]] kind="http"    →   HTTP 请求 tool
    - prompts: [...]           →   注入 system prompt

工具名自动加前缀：skill_name.tool_name 防碰撞。

自动创建（SkillCreator）

Agent学习自动化：当 Agent 成功执行多步 tool 链时，自动提取为可复用 Skill：

≥2步才触发
用embedding 去重（cosine similarity 检测已有相似 skill）
LRU淘汰（超过上限自动删最旧）
生成 SKILL.toml 持久化

自我改进（SkillImprover）

Agent 成功使用一个 Skill 后可以改进它：

Cooldown防止频繁改
原子写入（写temp →validate→rename）
审计元数据（improvementreason +timestamp）追加到文件

2.3 代码执行架构对比

代码执行架构对比：ZeroClaw vs Devin vs SWE-agent vs OpenHands

	ZeroClaw	Devin	SWE-agent	OpenHands
隔离粒度	每次命令	每个 session	每个 task	每个 session
隔离技术	5种沙箱可选	云端完整VM	Docker容器	Docker容器
持久性	无状态（命令级）	有状态（完整Linux桌面）	有状态（容器内git repo）	有状态（容器挂载workspace）
文件系统	workspace目录+路径白名单	完整VM文件系统	容器内完整FS	容器内完整FS
网络	无限制（依赖OS层）	全功能网络	容器网络	容器网络
谁写代码	委派给外部coding agent	自己的Agent直接写	自己的Agent直接写	CodeAct Agent直接写
编辑方式	file_write/file_edit（字符串替换）	IDE内直接操作	自研ACI命令（scroll_up, edit等）	Python code execution
代码理解	无 AST/LSP（纯文本）	完整IDE（有LSP）	自研ACI（专门为LLM设计的文件接口）	IPython kernel执行

关键区别：

Devin: 把 LLM 当“开发者”，给它完整 IDE + 浏览器 + terminal。
SWE-agent: 发现 LLM 用标准命令（vim/nano）效率极低，专门设计了“Agent-Computer Interface”——一套为 LLM 优化的命令（open file.py 50-100、edit 50:55 ....、scroll_down）。
OpenHands: 用 CodeAct—LLM 生成 Python 代码，在 IPython kernel 里执行，代码本身就是“工具调用”。

ZeroClaw特点：不用完整容器/VM，而是命令级沙箱一每条shell 命令单独包裹（Landlock/Firejail/Seatbelt），轻量但隔离粒度细。适合端侧（手机/嵌入式）场景，不适合需要跨命令有状态的复杂编程任务。

架构哲学对比总结

Devin: “给LLM一台完整电脑“ → 重（完整VM）、强（全能力）
SWE-agent: “给LLM专门设计的命令接口“ → 中（Docker）、精（为benchmark优化）
OpenHands: "让LLM写Python 当工具调用" → 中（Docker）、灵活（代码即动作）
ZeroClaw: “Agent只编排，不亲自写代码“ → 轻（命令级沙箱）、安全优先、端侧适用

Zeroclaw 独特优势

端侧可部署：不依赖 Docker/VM，Landlock/Seatbelt 可以在手机/嵌入式上跑
安全纵深最强：5层沙箱+环境净化+风险分级 +审批门
Deterministic SOP:已知工作流完全不过 LLM，O token 成本
自主学习闭环：执行 →提取 Ski11→下次复用 →自动改进
.多 Coding Agent 路由：不锁定单一 LLM，可按任务选 Claude/Codex/Gemini

ZeroClaw劣势/短板

无有状态环境：不像 Devin/OpenHands 有持久 workspace 容器，跨命令状态要靠文件系统
代码理解能力弱：无 AST/LSP/代码搜索，纯文本 file_read/file_edit
不适合SWE-bench 类任务：设计目标不是“自主修bug"，而是“编排+安全+端侧“
mini-SWE-agent 的警示：100 行 Python 就能达到 65% SWE-bench verified，说明“精巧接口 > 复杂架构

2.4 具体应用场景

动态硬件控制

场景描述：用户说“创建一个温度超过30度就打开风扇的程序“
执行流程：
- AI生成包含温度读取和风扇控制的Rust代码
- 代码被编译为WASM模块
- WASM模块定期读取温度传感器
- 当温度>30时，调用GPI0控制风扇

自定义数据处理

场景描述：用户需要对传感器数据进行特殊算法处理
执行流程：
- 用户提供算法描述或伪代码
- AI生成相应的数据处理函数
- 函数在WASM沙箱中执行，处理实时传感器数据
- 返回处理结果给主程序

2.5 执行流程

Claude Code产生的代码如何被执行

用户消息
 ↓
ZeroClaw agent loop (src/agent/loop_.rs) 
 ↓
LLM决策→调用claude_code工具 
 ↓
ClaudeCodeTool::execute()
 └── 启动子进程: claude -p "..."
 ↓
tokio::process::Command::new("claude")
    .arg("-p").arg(prompt)//你的任务
    .arg("--output-format").arg("json")
    .arg("--allowedTools"）.arg（"Bash"）//可选：允许执行shell
    .current_dir(workspace_dir) //工作目录锁定在workspace内
    .env_clear() //清除所有环境变量
    .env("HOME"，...)//只透传白名单变量
 ↓
等待claude进程返回JSON
 ↓
解析{result，session_id} 返回给 ZeroClaw

shell 工具

ZeroClaw 自己的代码执行 (通过 shell 工具) 也运行在同一台机器上, 流程如下:

ZeroClaw agent
    ↓ LLM 决定调用 shell 工具
ShellTool::execute({ command: "python gen_code.py" })
    ↓
runtime.build_shell_command(command, workspace_dir)
    ↓
sandbox.wrap_command(&mut cmd)   <- 沙箱包装 (Landlock/Bubblewrap 等)
    ↓
cmd.env_clear() + 只透传白名单环境变量
    ↓
cmd.output().await               <- 子进程在本机 workspace_dir 里执行
    ↓
stdout/stderr 返回给 LLM

0x03 消息机制

ZeroClaw 不是 “附加” IoT 功能，而是从底层设计为边缘 IoT+AI Agent 的运行时，硬件控制、IoT 协议、低功耗部署都是原生核心能力，适合快速搭建带自然语言交互的智能物联网系统。

事件驱动与主动行为：外设可把异步事件（传感器触发、GPIO 中断）通过transport推送到 ZeroClaw；ZeroClaw将事件变成会话/事件（或触发SOP/cron/Hands），代理可以主动发出消息或运行工具。

定时/自动化由cron、SOP（事件驱动工作流）和Hands编排实现，能在条件满足时主动执行动作或发送> 通知（见README的Gateway/cron/SOPs说明）。

3.1 消息协议

典型消息格式（文档示例）：主机外设间的串口JSON请求/响应，例如：

Serial Fallback (Host-Mediated, legacy)

Simple JSON over serial for boards without gRPC support:

Request (host → peripheral):

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

Response (peripheral → host):

{"id":"1","ok":true,"result":"done"}

3.2 Daemon

zeroclaw daemon启动一个长期运行的异步进程，同时管理多个组件：

zeroclaw daemon
    ├─gateway服务器（axumHTTP+WebSocket） 
    ├─channels监听循环（TG/Discord等） 
    ├─cron调度器
    ├─heartbeat心跳
    └─状态写入器（每5秒写磁盘状态）

流程图

以下流程图涵盖了以下核心逻辑：

组件并行启动：
- Daemon 启动后会立即并行生成四个核心部分：状态写入器（每5秒刷新）、网关、渠道、心跳和调度器。
- 条件检查：渠道、心跳和调度器会根据配置文件（config.toml）中的设置决定是否启动对应的 Worker。例如，如果未配置 Cron，则直接标记为 OK 并跳过。
监督与循环：
- 每个核心组件（Gateway, Channels, Heartbeat, Scheduler）都拥有独立的 Supervisor（监督者） 和 Loop（循环）。
- 4 大核心循环（Gateway/Channel/Heartbeat/Scheduler）均实现运行→退出判断→异常处理→退避重试→重新循环的闭环，分支（正常退出 / 异常退出）完全对齐；
- 异常处理：如果组件意外退出或报错，系统会记录错误并进行退避等待（Backoff），随后尝试重新进入循环，确保服务的稳定性。
核心功能：
- Gateway：负责 HTTP/WebSocket 服务，处理外部连接。
- Channels：连接 TG、Discord 等聊天平台。
- Heartbeat：定期执行后台感知任务，赋予 AI “自主意识”。
- Scheduler：基于 Cron 表达式触发定时任务。
优雅退出：
- 当接收到 Ctrl+C 信号时，Daemon 会中止所有任务并等待线程结束，确保数据完整保存后停止。即，所有组件初始化完成→进入运行状态，接收 Ctrl+C 后→终止所有任务→等待任务结束→守护进程正常停止，链路完整；

✅ 配色样式：

🔴 supervisor：组件孵化相关节点（State Writer/Gateway Supervisor 等）；
🟢 running：唯一运行状态节点；
🔵 component：各循环的核心运行方法节点；

完整架构

zeroclaw daemon::run()
│
├── tokio::broadcast::channel<JsonValue>(256)   ←  实时事件总线
│   所有组件通过它向 dashboard 推送状态
│
├── spawn_state_writer()
│   每 5 秒写 daemon_state.json (健康快照)
│
├── spawn_component_supervisor("gateway")
│   →  gateway::run_gateway(host, port, config, event_tx)
│   axum HTTP + WebSocket 服务器
│   崩溃自动重启 (指数退避: initial_backoff →  max_backoff)
│
├── spawn_component_supervisor("channels")   ←  仅当有 channel 配置时
│   →  channels::start_channels(config)
│   同时监听所有配置的 channel (TG/Discord/Slack...)
│
├── spawn_component_supervisor("mqtt")         ← 仅当启用时
│   →  run_mqtt_sop_listener()
│   IoT/SOP 事件 fan-in
│
├── spawn_component_supervisor("heartbeat")   ←  仅当启用时
│   两阶段模式: Phase 1 用 LLM 决策要执行哪些任务
│             Phase 2 执行选定任务
│   Dead-man's switch: 超时未 tick 自动发告警
│
└── spawn_component_supervisor("scheduler")  ←  仅当 cron.enabled 时
    → cron::scheduler::run(config, event_tx)
    定时任务执行

0x04 IOT

ZeroClaw有完整、原生的 IoT / 边缘硬件控制功能，专为低功耗嵌入式与物联网设备设计，是其核心定位之一。

4.1 三层协同的完整 IoT 场景

关键特点：

MQTT 不经 LLM: IoT 事件 → SOP 条件匹配 → Deterministic 执行, 全程 0 token
Peripheral 即 Tool: 硬件能力作为 LLM 可调用函数暴露
条件引擎: JSON Path 表达式 + 数值比较, fail-closed (条件不满足就不触发)
QoS 支持: MQTT QoS 0/1/2, TLS (mqtts://), auto-reconnect
Cooldown + 并发控制: 防止传感器抖动导致 SOP 疯狂重复执行
端侧部署: 整个 runtime 是 Rust 单二进制, 可跑在 RPi / 嵌入式 Linux

4.2 核心 IoT 硬件能力（原生支持）

硬件外设控制接口
- 支持GPIO、I2C、SPI、UART / 串口等标准嵌入式总线，直接驱动传感器、继电器、LED、电机等。
- 兼容主流 IoT 硬件：Raspberry Pi (Zero/3/4/5)、ESP32、STM32 Nucleo、Arduino等。
- 提供统一Peripheral trait 抽象，可插拔适配不同 MCU / 开发板，无需改核心代码。
IoT 通信协议
- 内置MQTT客户端 / 服务端，支持订阅 / 发布，对接 IoT 平台 / 网关。
- 支持WebSocket、Webhook，用于云端 / 边缘双向事件推送。
- 支持gRPC/nanoRPC，实现设备间 / 设备 - 主机的低延迟远程控制。
边缘部署特性（IoT 核心）
- 超轻量：单二进制 < 3.4MB、内存 < 5MB，冷启动 < 10ms，适配电池 / 低功耗场景openzeroclaw.com。
- 跨架构：ARM、x86、RISC-V，支持 Linux / 嵌入式 Linux，可直接跑在 Pi Zero、ESP32 等边缘节点openzeroclaw.com。
- 两种运行模式：
  - Edge-Native（本地独立）：ZeroClaw 直接运行在 ESP32 / 树莓派，本地解析自然语言、控制硬件、执行自动化。
  - Host-Target（主机 - 从机）：ZeroClaw 在 PC / 服务器，通过 USB/J-Link 远程控制 STM32/Arduino 等 MCU。

4.3 IoT 场景的 AI Agent 能力（核心价值）

自然语言转硬件指令：语音 / 聊天（TG / 钉钉 / 飞书）直接控制设备（如 “打开客厅灯”“读取温湿度”），LLM 自动生成 Rust 硬件代码并执行。
事件驱动自动化：结合Cron 定时、MQTT 传感器触发、GPIO 电平变化，执行预设 SOP（如温度超阈值自动开风扇、定时上报数据）。
边缘智能：本地运行轻量模型 / 调用云端 LLM，做异常检测、预测、决策，减少云端依赖、降低延迟、保护隐私。
远程运维：通过隧道（Cloudflare/Tailscale/ngrok）+ 多通道，外网安全访问内网 IoT 设备，远程调试 / 控制openzeroclaw.com。

4.4 典型 IoT 应用示例

智能家居：树莓派 + ZeroClaw，语音 / APP 控制灯光、插座、温湿度监控，MQTT 接入 HomeAssistant。
工业边缘：部署在网关，采集传感器数据、本地分析、异常告警、控制执行器。
便携 / 电池设备：ESP32 运行 ZeroClaw，低功耗、离线可用，做环境监测 / 智能开关。

4.5 IoT 适配机制

ZeroClaw为 IoT做了三层适配：

第一层：MQTT Channel（消息入口）

IoT 设备 → MQTT Broker> ZeroClaw MQTT Listener→ SOP Engine

关键设计决策：MQTT不走Channel trait（不进入聊天循环），而是直连SOP引擎：

// mgtt.rs第1-4行的注释：
// ! This is NOT a Channel` trait implementor - it routes MQTT messages
// ! to the SoP engine via dispatch_sop_event, not to the chat loop.

为什么？因为 IoT事件是机器信号（温度 85°C、门开了），不是“对话“。不应进入LLM推理循环浪费token，而是直接匹配SOP触发条件执行预定义流程。

流程：

订阅 sensors/# 等 MQTT topic
收到 publish → 构建 SopEvent
→dispatch_sop_event()匹配触发器
→匹配到的SOP用start_run()启动
→Deterministic模式直接执行（0 LLM调用）

条件评估：

//condition.rs：支持JSoN Path 条件
evaluate_condition("$.temperature >85",Some(r#"{"temperature":90}"#))
//→true→触发SOP

第二层: Peripheral Trait (硬件外设)

Agent ↔ Peripheral ↔ 物理硬件

        ↓           ↓

   STM32 Nucleo   RPi GPIO
   (Serial/UART)  (sysfs/gpiod)

Peripheral = Agent 的"手和脚":

pub trait Peripheral: Send + Sync {
    fn name(&self) -> &str;         // "nucleo-f401re-0"
    fn board_type(&self) -> &str;   // "nucleo-f401re"
    async fn connect(&mut self) -> Result<()>;
    async fn disconnect(&mut self) -> Result<()>;
    async fn health_check(&mut self) -> bool;
    fn tools(&self) -> Vec<Box<dyn Tool>>; // gpio_read, gpio_write, sensor_read
}

连接后，Peripheral 的 tools 直接注入 Agent 工具注册表—LLM 可以调用 gpio_write（pin=13，value=HIGH）控制硬件。

已实现：

nucleo_flash-STM32 Nucleo 板固件烧录
arduino_flash / arduino_upload -Arduino 上传
rpi -Raspberry Pi GPIo （仅 Linux + peripheral-rpi feature）
serial-通用串口通信
uno_a_bridge -Arduino Uno 通信桥接

第三层: SOP + Peripheral 联动

SOP 触发器支持 Peripheral 类型:

# SOP.toml
[[triggers]]
type = "peripheral"
board = "nucleo-f401re-0"
signal = "button_pressed"
condition = "> 0"

这意味着：硬件按钮按下→触发SOP→Deterministic 执行（0 LLM）→输出到另一个Peripheral/MQTT

4.6 总结

0x05 SOP 标准操作流程

SOP 是由 SopEngine 执行的确定性流程。它们提供显式的触发器匹配、审批门控和可审计的运行状态。实际上，SOP 可以被认为是短路机制：高频、标准化场景（如"打开空调"）直接走 SOP 规程，跳过 LLM 推理，响应时间 < 100ms。

输入 → 安全预检 → Context 收集 → SOP 匹配
├─ 匹配到 SOP → 执行预定义流程（不经过 LLM）
└─ 未匹配 → 模型路由 → LLM 推理 → Tool 调用 → 安全后检 → 响应输出

具体如下：

5.1 核心设计哲学

其执行模式如下：

5.2 流程

快速路径

连接事件： 连接与扇入 — 通过 MQTT、webhook、cron 或外围设备触发 SOP。
编写 SOP： 语法参考 — 所需的文件布局和触发器/步骤语法。
监控： 可观测性与审计 — 运行状态和审计条目的存储位置。
示例： 食谱 — 可复用的 SOP 模式。

运行时契约（当前）

SOP 定义从 <workspace>/sops/<sop_name>/SOP.toml 加载，外加可选的 SOP.md。
CLI zeroclaw sop 当前仅管理定义：list、validate、show。
SOP 运行由事件扇入（MQTT/webhook/cron/外围设备）或代理内工具 sop_execute 启动。
运行进度使用工具：sop_status、sop_approve、sop_advance。
SOP 审计记录持久化在配置的内存后端的 sop 类别下。

事件流程

graph LR MQTT[MQTT] -->|主题匹配| Dispatch WH[POST /sop/* or /webhook] -->|路径匹配| Dispatch CRON[调度器] -->|窗口检查| Dispatch GPIO[外围设备] -->|板卡/信号匹配| Dispatch Dispatch --> Engine[SOP 引擎] Engine --> Run[SOP 运行] Run --> Action{动作} Action -->|执行步骤| Agent[代理循环] Action -->|等待审批| Human[操作员] Human -->|sop_approve| Run

入门指南

在 config.toml 中启用 SOP 子系统：

[sop]
enabled = true
sops_dir = \"sops\"  # 省略时默认为 <workspace>/sops

创建 SOP 目录，例如：

~/.zeroclaw/workspace/sops/deploy-prod/SOP.toml
~/.zeroclaw/workspace/sops/deploy-prod/SOP.md

验证和检查定义：

zeroclaw sop list
zeroclaw sop validate
zeroclaw sop show deploy-prod

通过配置的事件源触发运行，或在代理轮次中使用 sop_execute 手动触发。

有关触发器路由和认证详情，请参见连接。

生命周期

Run 的生命周期如下。

确定性模式（Deterministic）特殊路径

这是 ZeroClaw SOP 最有价值的设计——不需要 LLM 的自动化流水线：

start_deterministic_run()
  |
  |  run_id 前缀为 "det-"（区分于普通 "run-"）
  ▼
resolve_deterministic_action(step, input=Null)
  |
  ├─ step.kind == Checkpoint?
  |     yes: persist_deterministic_state() → .state.json
  |          → 返回 CheckpointWait（暂停）
  |          → 人工 resume_deterministic_run() 恢复
  |
  |     no: → 返回 DeterministicStep { step, input }
  ▼
运行时执行步骤 → 产生 step_output
  |
  ▼
advance_deterministic_step(run_id, step_output)
  |
  |  step_output → 作为下一步的 input（管道！）
  |  run.llm_calls_saved += 1  ← 统计省了多少 LLM 调用
  ▼
下一步... 或完成
  |
  | 完成时：deterministic_savings.total_llm_calls_saved += saved
  |         deterministic_savings.total_runs += 1

断点恢复 — 进程重启后可恢复：

- persist_deterministic_state() → {run_id}.state.json 写入 SOP 目录
- 包含：run_id, sop_name, last_completed_step, step_outputs, llm_calls_saved
- resume_deterministic_run(state) → 从上次完成的步骤继续

5.3 SOP 连接与事件扇入

我们接下来看看外部事件如何触发 SOP 运行。

ZeroClaw 通过统一的 SOP 调度器（dispatch_sop_event）路由 MQTT/webhook/cron/外围设备事件。

关键行为：

一致的触发器匹配： 所有事件源使用同一个匹配器路径。
运行启动审计： 已启动的运行通过 SopAuditLogger 持久化。
无头安全： 在非代理循环上下文中，ExecuteStep 操作会被记录为待处理（不会静默执行）。

MQTT 集成

配置

在 config.toml 中配置 broker 访问：

[channels_config.mqtt]
broker_url = \"mqtts://broker.example.com:8883\"  # 明文使用 mqtt://
client_id = \"zeroclaw-agent-1\"
topics = [\"sensors/alert\", \"ops/deploy/#\"]
qos = 1
username = \"mqtt-user\"      # 可选
password = \"mqtt-password\"  # 可选
use_tls = true              # 必须与 scheme 匹配（mqtts:// => true）

触发器定义

在 SOP.toml 中：

[[triggers]]
type = \"mqtt\"
topic = \"sensors/alert\"
condition = \"$.severity >= 2\"

MQTT payload 会被转发到 SOP 事件 payload（event.payload），然后显示在步骤上下文中。

Webhook 集成

端点

POST /sop/{*rest}：仅 SOP 端点。如果没有 SOP 匹配则返回 404。无 LLM 回退。
POST /webhook：聊天端点。首先尝试 SOP 调度；如果不匹配，回退到正常 LLM 流程。

路径匹配与配置的 webhook 触发器路径精确匹配。

示例：

SOP 中的触发器路径：path = \"/sop/deploy\"
匹配请求：POST /sop/deploy

授权

启用配对时（默认），提供：

Authorization: Bearer <token>（来自 POST /pair）
可选第二层：配置 webhook 密钥时提供 X-Webhook-Secret: <secret>

幂等性

使用：

X-Idempotency-Key: <unique-key>

默认值：

TTL：300秒
重复响应：200 OK 带 \"status\": \"duplicate\"

幂等性密钥按端点命名空间区分（/webhook 和 /sop/* 分开）。

示例请求

curl -X POST http://127.0.0.1:3000/sop/deploy \
  -H \"Authorization: Bearer <token>\" \
  -H \"X-Idempotency-Key: $(uuidgen)\" \
  -H \"Content-Type: application/json\" \
  -d '{\"message\":\"deploy-service-a\"}'

典型响应：

{
  \"status\": \"accepted\",
  \"matched_sops\": [\"deploy-pipeline\"],
  \"source\": \"sop_webhook\",
  \"path\": \"/sop/deploy\"
}

Cron 集成

调度器使用基于窗口的检查评估缓存的 cron 触发器。

基于窗口： 不会遗漏 (last_check, now] 内的事件。
每个刻度每个表达式最多一次： 如果一个轮询窗口内有多个触发点，仅调度一次。

触发器示例：

[[triggers]]
type = \"cron\"
expression = \"0 0 8 * * *\"

Cron 表达式支持 5、6 或 7 个字段。

5.4 SOP 食谱

运行时支持的 SOP.toml + SOP.md 格式的实用 SOP 模板。

人在回路部署

SOP.toml：

[sop]
name = \"deploy-prod\"
description = \"带显式审批门控的手动部署\"
version = \"1.0.0\"
priority = \"high\"
execution_mode = \"supervised\"
max_concurrent = 1

[[triggers]]
type = \"manual\"

SOP.md：

## 步骤

1. **验证** — 检查健康指标和发布约束。
   - 工具：http_request

2. **部署** — 执行部署命令。
   - 工具：shell
   - 需要确认：true

IoT 告警处理器（MQTT）

SOP.toml：

[sop]
name = \"high-temp-alert\"
description = \"处理高温遥测告警\"
version = \"1.0.0\"
priority = \"critical\"
execution_mode = \"priority_based\"

[[triggers]]
type = \"mqtt\"
topic = \"sensors/temp/alert\"
condition = \"$.temperature_c >= 85\"

SOP.md：

## 步骤

1. **分析** — 读取此 SOP 上下文中的 `Payload:` 部分并确定严重程度。
   - 工具：memory_recall

2. **通知** — 发送包含站点/设备/严重程度摘要的告警。
   - 工具：pushover

每日摘要（Cron）

SOP.toml：

[sop]
name = \"daily-summary\"
description = \"生成每日运营摘要\"
version = \"1.0.0\"
priority = \"normal\"
execution_mode = \"supervised\"

[[triggers]]
type = \"cron\"
expression = \"0 9 * * *\"

SOP.md：

## 步骤

1. **收集日志** — 收集最近的错误和警告。
   - 工具：file_read

2. **总结** — 生成简洁的事件和趋势摘要。
   - 工具：memory_store

0xFF 参考

posted @ 2026-09-08 21:17 罗西的思考阅读(36) 评论(0) 收藏举报

刷新页面返回顶部

【OpenClaw具身硬件】ZeroClaw 源码阅读笔记（4）--- 代码执行

【OpenClaw具身硬件】ZeroClaw 源码阅读笔记（4）--- 代码执行

0x00 概要

0x01 代码合成

1.1 核心思想

1.2 业务逻辑

具体应用场景

能力体现

1.3 实现细节

生成种类

Rust 代码

Arduino CLI的功能定位

1.4 ClaudeCode Tool如何被大模型使用

第一步：tool.spec()生成工具描述

第二步：注册到Agent

第三步：转换为LLM Function Calling格式

第四步：LLM返回tool_call，ZeroClaw分发执行

0x02 代码执行

2.1 核心概念

WASM执行机制

Dynamic Exec动态执行

8 层纵深执行架构

2.2 关键组件

ShellTool

SOP工作流引擎

Skill 动态加载系统

三层来源

Skill→Tool 转换

自动创建（SkillCreator）

自我改进（SkillImprover）

2.3 代码执行架构对比

2.4 具体应用场景

2.5 执行流程

Claude Code产生的代码如何被执行

shell 工具

0x03 消息机制

3.1 消息协议

3.2 Daemon

流程图

完整架构

0x04 IOT

4.1 三层协同的完整 IoT 场景

4.2 核心 IoT 硬件能力（原生支持）

4.3 IoT 场景的 AI Agent 能力（核心价值）

4.4 典型 IoT 应用示例

4.5 IoT 适配机制

第一层：MQTT Channel（消息入口）

第二层: Peripheral Trait (硬件外设)

第三层: SOP + Peripheral 联动

4.6 总结

0x05 SOP 标准操作流程

5.1 核心设计哲学

5.2 流程

快速路径

运行时契约（当前）

事件流程

入门指南

生命周期

确定性模式（Deterministic）特殊路径

5.3 SOP 连接与事件扇入

MQTT 集成

配置

触发器定义

Webhook 集成

端点

授权

幂等性

示例请求

Cron 集成

5.4 SOP 食谱

人在回路部署

IoT 告警处理器（MQTT）

每日摘要（Cron）

0xFF 参考

公告