A · 运行时架构分层
ZeroClaw 的运行时从输入到输出分为五个层级，每层通过 Trait 解耦，可独立替换。
graph TB
subgraph INPUT["① 输入层 (Input Layer)"]
CH1[Discord] & CH2[Telegram] & CH3[Matrix] & CH4[Email]
CH5[CLI] & CH6[Webhook] & CH7[Voice] & CH8[30+ others]
GW[Gateway REST/WebSocket]
ACP[ACP JSON-RPC IDE]
end
subgraph CORE["② 核心处理层 (Core / Agent Loop)"]
AL[Agent Loop]
SC[Security Policy]
SOP[SOP Engine]
SCHED[Cron Scheduler]
APPR[Approval Manager]
end
subgraph EXEC["③ 执行层 (Execution Layer)"]
PROV[LLM Providers\nAnthropic / OpenAI / Ollama / 20+]
TOOLS[Tools\nShell · Browser · HTTP · Hardware]
MEM[Memory Engine\nVector + Keyword Hybrid]
HOOK[Hook Runner\nTool Receipts]
end
subgraph INFRA["④ 基础设施层 (Infra)"]
CFG[Config TOML]
LOG[Logger]
PLUG[WASM Plugins]
HW[Hardware I2C/GPIO/SPI]
end
subgraph STORE["⑤ 存储层 (Storage)"]
DB[(SQLite Memory)]
VEC[(Vector Index)]
FS[Filesystem Workspace]
end
INPUT --> CORE
CORE --> EXEC
EXEC --> INFRA
INFRA --> STORE
style INPUT fill:#1a2332,stroke:#f78166,color:#e6edf3
style CORE fill:#1a2332,stroke:#79c0ff,color:#e6edf3
style EXEC fill:#1a2332,stroke:#56d364,color:#e6edf3
style INFRA fill:#1a2332,stroke:#dea584,color:#e6edf3
style STORE fill:#1a2332,stroke:#8b949e,color:#e6edf3
① 输入层 — Channel Adapters + Gateway
discord
telegram
matrix
email
cli_input
webhook
voice
slack
gateway (REST/WS)
acp (JSON-RPC)
② 核心层 — Agent Loop + Security + SOP
agent::loop_
agent::dispatcher
agent::context_analyzer
security
approval
sop
cron
routines
trust
verifiable_intent
③ 执行层 — Providers + Tools + Memory
providers
tools (shell/browser/http)
memory
rag
hooks
skills
skillforge
multimodal
④ 基础设施层 — Config + Hardware + Plugins
config
hardware
peripherals
plugins (WASM)
platform
observability
health
i18n
⑤ 存储层 — SQLite + Vector Index + Filesystem
SQLite (memory DB)
Vector Index (built-in)
Workspace FS
identity store
B · Workspace Crate 依赖关系
ZeroClaw 使用 Cargo workspace 组织代码，主 crate 依赖以下独立库：
graph LR
BIN["zeroclaw (bin)"]
subgraph RUNTIME["zeroclaw-runtime"]
RT[agent\nloop / dispatcher\nclassifier / memory_loader]
end
subgraph CHANNELS["zeroclaw-channels"]
CH[Channel Adapters\ndiscord / telegram / matrix / email]
end
subgraph PROVIDERS["zeroclaw-providers"]
PR[LLM Backends\nanthropic / openai / ollama / 20+]
end
subgraph TOOLS["zeroclaw-tools"]
TL[Tool Implementations\nshell / browser / http / hardware]
end
subgraph MEMORY["zeroclaw-memory"]
ME[Memory Engine\nSQLite + Vector Hybrid Search]
end
subgraph GATEWAY["zeroclaw-gateway"]
GW[HTTP/WebSocket Server\nWeb Dashboard]
end
subgraph HARDWARE["zeroclaw-hardware"]
HW[GPIO/I2C/SPI/USB\naardvark-sys bindings]
end
CFG["zeroclaw-config"]
API["zeroclaw-api"]
LOG["zeroclaw-log"]
PLUG["zeroclaw-plugins"]
TUI["zeroclaw-tui"]
MACROS["zeroclaw-macros"]
TCP["zeroclaw-tool-call-parser"]
INFRA["zeroclaw-infra"]
RK["robot-kit"]
AS["aardvark-sys"]
BIN --> RUNTIME & CHANNELS & PROVIDERS & TOOLS & MEMORY & GATEWAY & HARDWARE
BIN --> CFG & API & LOG & PLUG & TUI
RUNTIME --> CFG & LOG & MACROS & TCP & INFRA & MEMORY
CHANNELS --> CFG & LOG & API
PROVIDERS --> CFG & LOG & API
TOOLS --> CFG & LOG & MEMORY
HARDWARE --> RK & AS
GATEWAY --> API & LOG & CFG
style BIN fill:#f78166,color:#0d1117,stroke:#f78166
style RUNTIME fill:#1a2832,stroke:#79c0ff,color:#e6edf3
style CHANNELS fill:#1a2832,stroke:#56d364,color:#e6edf3
style PROVIDERS fill:#1a2832,stroke:#dea584,color:#e6edf3
style TOOLS fill:#1a2832,stroke:#56d364,color:#e6edf3
style MEMORY fill:#1a2832,stroke:#79c0ff,color:#e6edf3
style GATEWAY fill:#1a2832,stroke:#f78166,color:#e6edf3
style HARDWARE fill:#1a2832,stroke:#dea584,color:#e6edf3
B · Crate 职责详解
17 个 Workspace Crate 各司其职：
zeroclaw-runtime
Agent 核心运行时：Loop、Dispatcher、Classifier、Context Analyzer、History、Memory Loader、Security Policy
核心
zeroclaw-channels
所有通讯渠道的适配器：Discord、Telegram、Matrix、Email、Slack、Webhook、Voice
输入
zeroclaw-providers
LLM 后端抽象：Anthropic、OpenAI、Ollama 及 20+ 兼容接口，支持 fallback chain
执行
zeroclaw-tools
工具实现：Shell 执行、HTTP 客户端、浏览器控制、文件操作等
执行
zeroclaw-memory
全栈内存引擎：SQLite 持久化 + 内置向量嵌入（无外部依赖）+ 混合搜索
存储
zeroclaw-gateway
HTTP/WebSocket 网关：REST API、Web Dashboard、实时流式聊天
输入
zeroclaw-hardware
硬件抽象：GPIO / I2C / SPI / USB，支持 Raspberry Pi、STM32、Arduino、ESP32
硬件
zeroclaw-config
TOML 配置加载、验证与 schema 生成
基础
zeroclaw-api
共享数据类型、Trait 定义、API 契约（跨 crate 接口层）
基础
zeroclaw-plugins
WASM 插件系统：加载、沙箱执行、插件注册表
扩展
zeroclaw-tui
终端 UI：交互式聊天界面、日志面板、配置向导
UI
zeroclaw-log
结构化日志与可观测性（spans、tracing）
基础
zeroclaw-macros
过程宏：工具定义、Trait 派生、代码生成
基础
zeroclaw-tool-call-parser
LLM 输出的 Tool Call 解析器，处理流式和完整响应
执行
zeroclaw-infra
公共基础设施：错误类型、结果包装、异步工具函数
基础
robot-kit
机器人控制工具套件（与 aardvark-sys 配合用于嵌入式设备）
硬件
aardvark-sys
Aardvark USB I2C/SPI 适配器的底层 FFI 绑定
硬件
A · Agent 核心组件
Agent struct 是运行时核心，包含以下关键组件：
classDiagram
class Agent {
+model_provider: Box~dyn ModelProvider~
+model_name: String
+temperature: f32
+tools: Vec~Tool~
+tool_specs: Vec~ToolSpec~
+tool_dispatcher: ToolDispatcher
+memory: Arc~dyn MemoryBackend~
+memory_loader: MemoryLoader
+history: ConversationHistory
+security_summary: String
+autonomy_level: AutonomyLevel
+workspace_dir: PathBuf
+approval_manager: Option~ApprovalManager~
+activated_tools: Vec~McpTool~
+hook_runner: Option~HookRunner~
+response_cache: Option~ResponseCache~
+builder() AgentBuilder
+from_config_with_session_cwd_and_mcp() Agent
+seed_history()
+trim_history()
+channel_handles() ChannelHandles
}
class AgentBuilder {
+model_provider()
+tools()
+memory()
+temperature()
+workspace_dir()
+security_summary()
+approval_manager()
+build() Agent
}
class AutonomyLevel {
<<enum>>
Supervised
Autonomous
Strict
}
class ModelProvider {
<<trait>>
+stream_chat()
+complete()
+name() str
}
class MemoryBackend {
<<trait>>
+store()
+search()
+recall()
}
Agent --> AgentBuilder
Agent --> AutonomyLevel
Agent --> ModelProvider
Agent --> MemoryBackend