拆 ZeroClaw 架构：四个 Trait 撑起一个 Agent 运行时

大家好，我是安东尼（tuaran.me），一名专注于前端与 AI 工程化的独立开发者。

我在建设「博主联盟」------连接AI产品方与技术博主的品牌增长平台，帮AI产品精准触达开发者，也帮博主拿到兼职资源与成长机会。

同时也在做「前端下一步」------一个聚焦前端、AI Agent 与大模型的技术情报站，帮你从技术革新焦虑中解脱，得到技术转向判断。

这篇文章，希望对你有所启发。

上一篇科普里提过，ZeroClaw 的核心是四个 Rust Trait：Provider / Channel / Memory / Tool。这一篇把它们一个个拆开，看看一个"Rust Trait 驱动的 Agent 运行时"长什么样、又为什么要这么设计。

为什么是 Trait，不是插件系统

很多 Agent 框架走的是"运行时插件 + 动态加载"的路（Python 的 entry points、Node 的 require 注入）。ZeroClaw 反过来------编译期组装：

所有扩展点都是 trait
实现散落在不同 crate 里，按 feature flag 编进二进制
配置文件只决定用哪一个实现 ，不决定怎么加载

好处很 Rust：编译器帮你做契约校验，运行时不会出现"插件签名对不上"这种错误。代价是------新增 Provider/Channel 一般要重新编译。这点后面"安全"和"上手"两篇会再提。

Provider Trait：抽象 LLM 提供商

职责：把不同家厂的 Chat/Completion API 统一成"一次请求 → 一段输出 + 工具调用建议"。

它要处理几件脏活：

不同家的 function/tool calling 协议：OpenAI、Anthropic、Ollama 写法都不一样
流式响应的差异：SSE vs 自定义分块
上下文窗口 与截断策略
重试/限流：429、超时、provider 端错误码

ZeroClaw 把这些塞进 Provider 层之后，上游 Agent 循环只需要面对一个"trait 对象"。换 Anthropic ↔ OpenAI ↔ OpenRouter ↔ Ollama，对业务层是无感的。

Channel Trait：抽象消息平台

职责：把"消息进来 / 消息出去"标准化。

要消化的差异远比想象中多：

触发模型：Webhook（Telegram、Discord Slash Command）vs 长轮询 vs 持久 socket（Matrix、IRC）
消息形态：纯文本、Markdown、富媒体、语音转写、文件上传
会话标识：用户/频道/线程的三段式 ID 各不相同
回执与编辑：Telegram 能编辑历史消息，邮件不能

社区在 HN 上有一个高频问题：怎么自己加一个 Channel？ 答案就是实现 Channel trait + 注册一下，剩下的对接 Provider 和 Tool 都不用改。这正是这种架构的卖点。

Memory Trait：抽象记忆/检索

职责：让 Agent 拥有跨会话的"记得住的东西"。

ZeroClaw 默认走 SQLite + FTS5 + 向量列的混合检索，思路是：

关键词召回用 BM25（FTS5 自带）
语义召回用向量相似度
两路结果在应用层做加权合并

这种"hybrid search"在 RAG 圈已是常识，但塞进一个 5MB 的二进制里还能跑得动，是它能在边缘设备落地的关键之一。需要更大规模时切到 Postgres + pgvector，是同一个 Trait 的另一种实现，业务代码不用动。

Tool Trait：抽象"外部能力"

职责：把 Agent 想做的事------执行 shell、抓网页、调 HTTP、读硬件、调 MCP Server------统一成"工具调用"。

设计上有两点值得强调：

工具是被允许才能调用的------deny-by-default 的白名单是默认行为，不是可选项。
支持 MCP（Model Context Protocol）作为工具来源。也就是说，OpenAI/Anthropic 生态里那些 MCP Server，可以直接被 ZeroClaw 当作 Tool 接进来，不用再写一层适配。

这两点合起来，让 ZeroClaw 的"工具层"既比传统 shell-exec 安全，又比闭门造车的私有协议开放。

一次请求是怎么穿过这四层的

简化的调用链：

rust 复制代码

Channel.recv()  ->  消息标准化
  -> Memory.recall()  载入相关记忆
  -> Provider.chat()  让模型决策（可能产出工具调用）
  -> Tool.invoke()    实际去做事（带白名单/沙箱校验）
  -> Provider.chat()  把工具结果再喂回去
  -> Memory.write()   记一笔到记忆库
  -> Channel.send()   把最终回复发出去

整个 loop 就是 ZeroClaw 二进制里的"Agent 引擎"。Trait 让每一层都可替换，编译期组装让每一层都是零开销抽象------这两件事加起来，是它敢宣传"<10ms 启动 / <5MB 内存"的工程基础。

给打算扩展它的人一点提示

加 Provider：照着 anthropic / openai 的实现抄一份，重点是 tool-calling 的协议适配。
加 Channel：先想清楚是 webhook 还是长连接，会话 ID 怎么映射。
加 Tool：能用 MCP 就别自己造轮子，能进白名单就别开后门。
替换 Memory：先衡量你是不是真的需要 Postgres------SQLite + FTS5 在十万级文档以下都还很能打。

下一篇会把官方那张"-99% 内存 / -400× 启动时间"的对比图拆开看，分清哪些是真功夫、哪些是营销话术。

参考：官方 README、Deconstructing ZeroClaw、知乎架构拆解。