架构概览¶
ZeroClaw 采用 trait 驱动的模块化架构，每个子系统都可以通过配置独立替换，无需修改代码。
核心架构¶
子系统列表¶
| 子系统 | Trait | 内置实现 | 扩展方式 |
|---|---|---|---|
| AI 模型 | Provider | 23+ 提供商 | custom:https://your-api.com |
| 通讯渠道 | Channel | CLI、Telegram、Discord、Slack 等 | 任意消息 API |
| 内存 | Memory | SQLite、Lucid、Markdown | 任意持久化后端 |
| 工具 | Tool | shell、文件、内存、浏览器 | 任意能力 |
| 可观测性 | Observer | Noop、Log、Multi | Prometheus、OTel |
| 运行时 | RuntimeAdapter | Native、Docker | WASM（计划中） |
| 安全 | SecurityPolicy | 配对、沙盒、允许列表 | - |
| 身份 | IdentityConfig | OpenClaw、AIEOS v1.1 | 任意格式 |
| 隧道 | Tunnel | Cloudflare、Tailscale、ngrok | 任意隧道二进制文件 |
| 心跳 | Engine | HEARTBEAT.md 周期任务 | - |
| 技能 | Loader | TOML 清单 + SKILL.md | 社区技能包 |
| 集成 | Registry | 50+ 集成，9 个类别 | 插件系统 |
目录结构¶
zeroclaw/
├── src/
│ ├── main.rs # CLI 入口和命令路由
│ ├── lib.rs # 模块导出
│ ├── agent/ # 代理编排循环
│ ├── gateway/ # Webhook/网关服务器
│ ├── security/ # 策略、配对、密钥存储
│ ├── memory/ # 内存后端和向量搜索
│ ├── providers/ # AI 模型提供商
│ ├── channels/ # 通讯渠道
│ ├── tools/ # 工具执行
│ ├── runtime/ # 运行时适配器
│ └── config/ # 配置模式
├── docs/ # 架构和流程文档
├── tests/ # 测试
└── examples/ # 示例配置
运行时支持¶
当前支持¶
✅ Native - 原生运行时 ✅ Docker - 沙盒运行时
计划中¶
🚧 WASM - WebAssembly 运行时
当配置不支持的 runtime.kind 时，ZeroClaw 会以清晰的错误退出，而不是静默回退到 native。
内存系统¶
ZeroClaw 实现了一个自定义的全栈搜索引擎，无外部依赖：
内存层次¶
| 层级 | 实现 |
|---|---|
| 向量数据库 | Embeddings 存储为 SQLite 中的 BLOB，余弦相似度搜索 |
| 关键词搜索 | FTS5 虚拟表，BM25 评分 |
| 混合合并 | 自定义加权合并函数（vector.rs） |
| Embeddings | EmbeddingProvider trait - OpenAI、自定义 URL 或 noop |
| 分块 | 基于 markdown 行的分块器，保留标题 |
| 缓存 | SQLite embedding_cache 表，LRU 逐出 |
| 安全重索引 | 原子性重建 FTS5 + 重新嵌入缺失向量 |
内存配置¶
[memory]
backend = "sqlite" # "sqlite", "lucid", "markdown", "none"
auto_save = true
embedding_provider = "openai"
vector_weight = 0.7
keyword_weight = 0.3
安全架构¶
ZeroClaw 在每一层都强制执行安全策略：
安全分层¶
- 网关层
- 默认绑定
127.0.0.1 - 拒绝无隧道的
0.0.0.0 -
配对代码认证
-
应用层
- 工作区作用域
- 允许列表控制
-
速率限制
-
执行层
- 沙盒运行时
- 文件系统限制
-
命令过滤
-
存储层
- 加密密钥
- 安全日志
- 敏感数据屏蔽
扩展点¶
添加新的 Provider¶
在 src/providers/ 实现 Provider trait 并注册到 factory。
添加新的 Channel¶
在 src/channels/ 实现 Channel trait，保持 send、listen、health_check 语义一致。
添加新的 Tool¶
在 src/tools/ 实现带严格参数模式的 Tool trait，验证并清理所有输入。
添加新的 Runtime¶
在 src/runtime/ 实现 RuntimeAdapter trait 并注册到 factory。
设计模式¶
Trait + Factory¶
- Trait: 定义接口契约
- Factory: 负责实例化和注册
- Config: 通过配置选择实现
沙盒隔离¶
- Native：进程级隔离
- Docker：容器级隔离
- 通信：显式消息传递
策略模式¶
- 每个子系统支持多种策略
- 运行时动态选择
- 配置驱动