ZeroClaw 产品需求文档（PRD）
版本：0.1.6 | 日期：2026-02-23
产品愿景
让每个人都能拥有一个安全、高效、可控的 AI 智能体，无论是在云服务器上，还是在一块 10 美元的开发板上。
ZeroClaw 要解决的核心问题是：现有的 AI Agent 框架（如基于 Python 的 LangChain）太重了——动辄占用 1GB 内存、启动慢、部署复杂、安全性靠开发者自觉。而 ZeroClaw 用 Rust 从零构建，追求的是：
- 8.8MB 二进制，树莓派也能跑
- 开箱即用的安全防护，不用自己操心
- 想接什么模型接什么模型，想连什么平台连什么平台
- 配置一个文件搞定，改一行就能切换
目标用户
用户画像 1：独立开发者 / 技术爱好者
"我想搞一个自己的 AI 助手，能在 Telegram 上跟我聊天，帮我管理服务器，但不想花时间折腾 Python 环境和一堆依赖。"
- 需要简单部署（一个二进制文件 + 一个配置文件）
- 需要多平台接入（Telegram、Discord 等）
- 对性能有追求，不想让 Agent 吃掉服务器的内存
- 想自己控制 Agent 能做什么不能做什么
用户画像 2：企业技术团队
"我们需要一个内部 AI 助手平台，要安全、可审计、能部署在私有云，最好能接入飞书/钉钉/企业微信。"
- 需要企业级安全（沙箱、白名单、密钥加密、审计日志）
- 需要接入国内平台（飞书、钉钉、QQ、智谱 GLM）
- 需要可观测性（Prometheus/OTEL）
- 需要 PostgreSQL 后端支持团队共享记忆
用户画像 3：硬件/嵌入式开发者
"我想让 AI 控制我的树莓派和 STM32 开发板，做一个智能家居控制中心。"
- 需要极致的二进制大小和内存占用
- 需要硬件外设支持（GPIO、串口、传感器）
- 需要在 ARM/RISC-V 架构上运行
- 需要离线运行能力（Ollama 本地模型）
用户画像 4：开源贡献者
"我想给这个项目贡献代码，加一个新的模型提供者或者聊天平台。"
- 需要清晰的扩展接口（trait 定义明确）
- 需要完善的文档和开发指南
- 需要 CI/CD 保障贡献质量
- 需要合理的代码组织和命名规范
核心功能清单
P0 — 核心功能（已实现）
多模型支持
| 功能 |
状态 |
说明 |
| OpenAI (GPT-4/4o) |
✅ |
原生函数调用、视觉、流式 |
| Anthropic (Claude) |
✅ |
原生工具、视觉、推理内容 |
| Google Gemini |
✅ |
原生函数声明、视觉 |
| OpenRouter |
✅ |
200+ 模型路由 |
| AWS Bedrock |
✅ |
托管部署 |
| GitHub Copilot |
✅ |
OAuth 认证 |
| Ollama（本地） |
✅ |
离线运行 |
| 智谱 GLM |
✅ |
中文大模型 |
| 自定义兼容接口 |
✅ |
支持任意 OpenAI/Anthropic 兼容 API |
| 弹性包装器 |
✅ |
自动重试、超时、降级 |
| 模型路由 |
✅ |
按任务类型路由到不同模型 |
多频道支持
| 频道 |
状态 |
特色 |
| Telegram |
✅ |
轮询/Webhook，附件处理 |
| Discord |
✅ |
意图系统，服务器/频道过滤 |
| Slack |
✅ |
Bolt 兼容 |
| WhatsApp |
✅ |
Cloud API + Web QR 双模式 |
| Matrix |
✅ |
端到端加密 |
| 飞书/Lark |
✅ |
Webhook + WebSocket |
| Email |
✅ |
SMTP/IMAP 异步 |
| iMessage |
✅ |
macOS 原生 |
| Signal |
✅ |
Signal Desktop API |
| Mattermost |
✅ |
自托管企业IM |
| IRC |
✅ |
RFC 1459 |
| 钉钉 |
✅ |
阿里巴巴生态 |
| QQ |
✅ |
腾讯生态 |
| Nostr |
✅ |
去中心化协议 |
| NextCloud Talk |
✅ |
自托管 |
| CLI |
✅ |
命令行交互 |
| Webhook |
✅ |
通用 HTTP |
Agent 能力
| 功能 |
状态 |
说明 |
| 多轮对话 |
✅ |
自动历史管理和压缩 |
| 工具调用 |
✅ |
原生 + 提示引导两种模式 |
| 流式输出 |
✅ |
实时草稿更新 |
| 自动记忆 |
✅ |
对话自动保存和召回 |
| 混合搜索 |
✅ |
关键字 + 向量加权混合 |
| 文件操作 |
✅ |
读/写/编辑，路径安全校验 |
| Shell 命令 |
✅ |
白名单控制 |
| 浏览器 |
✅ |
WebDriver 自动化 |
| HTTP 请求 |
✅ |
网络调用 |
| 定时任务 |
✅ |
Cron 表达式 + 一次性 + 固定间隔 |
| 子 Agent 委派 |
✅ |
将任务分配给子 Agent |
| 图片理解 |
✅ |
多模态视觉 |
| PDF 阅读 |
✅ |
文档解析 |
安全
| 功能 |
状态 |
说明 |
| 配对认证 |
✅ |
6 位一次性码，类似蓝牙配对 |
| 频道白名单 |
✅ |
默认拒绝所有 |
| 文件系统隔离 |
✅ |
workspace_only + 黑名单 |
| 命令白名单 |
✅ |
只允许指定命令 |
| 沙箱 |
✅ |
Landlock/Bubblewrap/Firejail |
| 密钥加密 |
✅ |
ChaCha20-Poly1305 |
| 凭据脱敏 |
✅ |
日志和输出自动脱敏 |
| 速率限制 |
✅ |
可配置 |
| 紧急停止 |
✅ |
E-Stop 一键停止 |
| Webhook 签名 |
✅ |
HMAC-SHA256 校验 |
P1 — 重要功能（已实现）
| 功能 |
状态 |
说明 |
| 硬件外设 |
✅ |
STM32、树莓派、ESP32、Arduino |
| 身份/人格系统 |
✅ |
Markdown 或 JSON 格式定义 Agent 身份 |
| 技能系统 |
✅ |
TOML 清单管理可用技能 |
| Composio 集成 |
✅ |
1000+ OAuth 应用 |
| 可观测性 |
✅ |
Log + Prometheus + OTEL |
| 热重载 |
✅ |
修改配置不重启生效 |
| 数据迁移 |
✅ |
从 OpenClaw 迁移 |
| 健康检查 |
✅ |
所有子系统健康监控 |
| 心跳 |
✅ |
保活和状态上报 |
| Shell 补全 |
✅ |
Bash/Zsh/Fish/PowerShell/Elvish |
P2 — 增强功能（已实现或部分实现）
| 功能 |
状态 |
说明 |
| Docker 运行时 |
✅ |
沙箱化执行环境 |
| 推送通知 |
✅ |
Pushover |
| Web3 消息 |
✅ |
Nostr + Linq |
| 语音转文字 |
✅ |
Transcription 频道 |
| 多语言文档 |
✅ |
英/中/日/俄/法/越 |
| 一键部署 |
✅ |
bootstrap.sh 脚本 |
非功能性需求
| 指标 |
目标 |
当前 |
| 二进制大小 |
< 15MB |
~8.8MB ✅ |
| 基础内存 |
< 10MB |
< 5MB ✅ |
| 启动时间 |
< 1s |
< 100ms ✅ |
| 最低硬件 |
$10 SBC |
树莓派 Zero ✅ |
安全
| 指标 |
要求 |
| 默认安全 |
所有权限默认关闭，需明确授权 |
| 密钥管理 |
加密存储，运行时不落盘明文 |
| 网络暴露 |
默认仅本地绑定 |
| 审计 |
所有敏感操作可追踪 |
可用性
| 指标 |
要求 |
| 部署 |
单二进制 + 单配置文件即可运行 |
| 配置 |
TOML 格式，人类可读 |
| 错误提示 |
明确的错误信息和修复建议 |
| 文档 |
6 种语言，覆盖所有功能 |
可扩展性
| 指标 |
要求 |
| 新 Provider |
实现 trait + 注册工厂 |
| 新 Channel |
实现 trait + 注册工厂 |
| 新 Tool |
实现 trait + 注册工厂 |
| 新硬件 |
实现 Peripheral trait |
| Feature Flag |
可选编译，不增加基础包体积 |
可维护性
| 指标 |
要求 |
| 代码规范 |
Rust 标准命名（snake_case/PascalCase） |
| CI/CD |
格式检查 + Clippy + 测试 + 审计 |
| PR 流程 |
模板化、标签化、自动化 |
| 测试 |
集成测试 15+，单元测试 100+ |
竞品对比
vs 重型框架（LangChain/LlamaIndex/AutoGen）
| 维度 |
ZeroClaw |
LangChain 等 |
| 语言 |
Rust |
Python |
| 二进制大小 |
8.8MB |
N/A（需要 Python 运行时 + 依赖） |
| 内存占用 |
< 5MB |
数百 MB ~ 1GB+ |
| 部署 |
单二进制 |
Python 环境 + pip 依赖 |
| 安全 |
内置多层防护 |
需自行实现 |
| 硬件支持 |
原生嵌入式 |
不支持 |
| 频道集成 |
25 个内置 |
需额外库 |
| 类型安全 |
编译期保证 |
运行时报错 |
ZeroClaw 的优势：性能、安全、部署简单、硬件支持
LangChain 的优势：生态更大、上手门槛低（Python）、社区更活跃
vs 轻量框架（OpenClaw/CrewAI）
| 维度 |
ZeroClaw |
OpenClaw |
| 语言 |
Rust |
Go |
| 内存占用 |
< 5MB |
~1GB+ |
| 安全模型 |
9 层纵深防御 |
基础级 |
| 频道数量 |
25 |
~10 |
| Provider 数量 |
11 |
~5 |
| 硬件支持 |
✅ |
❌ |
| 记忆系统 |
混合搜索 |
基础存取 |
| 可观测性 |
Log + Prometheus + OTEL |
基础日志 |
| 维度 |
ZeroClaw |
Dify/Coze |
| 部署 |
自托管 / 边缘 |
云托管为主 |
| 数据主权 |
完全自控 |
平台托管 |
| 定制性 |
代码级无限定制 |
GUI 拖拽，上限明确 |
| 成本 |
仅 API 费用 |
平台费 + API 费 |
| 硬件 |
支持嵌入式 |
不支持 |
| 离线 |
Ollama 支持 |
不支持 |
使用场景
场景 1：个人 Telegram AI 助手
部署：树莓派 4 / 轻量 VPS
模型：OpenAI GPT-4o 或 Ollama 本地模型
频道：Telegram
工具：Shell + 文件操作 + HTTP 请求
安全：workspace_only + 命令白名单
用户通过 Telegram 跟 Agent 聊天，让它帮忙查信息、管理文件、执行脚本。成本：仅 API 调用费。
场景 2：企业内部知识助手
部署：Kubernetes / Docker
模型：Azure OpenAI 或 AWS Bedrock
频道：飞书 + 钉钉 + Slack
记忆：PostgreSQL（团队共享）
安全：沙箱 + 白名单 + OTEL 审计
员工通过企业 IM 提问，Agent 从知识库中检索答案，记住团队上下文。
场景 3：智能家居控制中心
部署：树莓派 Zero
模型：Ollama（本地 7B 模型）
频道：CLI + Telegram
硬件：GPIO 控制灯光/传感器
安全：workspace_only + 最小权限
"帮我把客厅灯打开" → Agent 调用 GPIO 工具 → 点亮 LED。
场景 4：DevOps 运维助手
部署：运维服务器
模型：Claude / GPT-4
频道：Slack + Webhook
工具：Shell + Git + HTTP + 定时任务
安全：命令白名单 + 文件系统隔离
接收告警 Webhook → Agent 自动诊断 → 执行修复脚本 → 在 Slack 报告。
场景 5：多平台内容管理
部署：VPS
模型：OpenRouter（按任务选模型）
频道：Discord + Telegram + Email
工具：浏览器 + HTTP + 文件
记忆：SQLite 混合搜索
统一管理多个社区平台的消息、自动回复、内容整理。
CLI 命令体系
ZeroClaw 提供了完整的命令行工具：
| 命令 |
说明 |
zeroclaw onboard |
交互式初始化向导 |
zeroclaw agent |
启动 Agent（单次或持续运行） |
zeroclaw gateway |
启动 HTTP 网关 |
zeroclaw daemon |
守护进程模式 |
zeroclaw service |
系统服务管理 |
zeroclaw doctor |
诊断检查 |
zeroclaw status |
查看运行状态 |
zeroclaw estop |
紧急停止 |
zeroclaw cron |
定时任务管理 |
zeroclaw models |
模型管理 |
zeroclaw providers |
列出可用 Provider |
zeroclaw channel |
频道管理 |
zeroclaw integrations |
集成管理 |
zeroclaw skills |
技能管理 |
zeroclaw migrate |
数据迁移 |
zeroclaw auth |
认证管理 |
zeroclaw hardware |
硬件设备管理 |
zeroclaw peripheral |
外设管理 |
zeroclaw memory |
记忆管理 |
zeroclaw config |
配置管理（含 JSON Schema 导出） |
zeroclaw completions |
生成 Shell 补全脚本 |
风险与限制
技术风险
| 风险 |
影响 |
缓解措施 |
| Rust 学习曲线高 |
社区贡献门槛较高 |
完善文档、提供模板、代码注释 |
| 编译时间长 |
开发迭代慢 |
增量编译、feature flag 减少编译范围 |
| 异步 Rust 复杂 |
新手容易踩坑 |
统一使用 tokio，避免混用运行时 |
产品风险
| 风险 |
影响 |
缓解措施 |
| 模型 API 依赖 |
服务中断影响可用性 |
Reliable 包装器自动重试和降级 |
| 安全漏洞 |
Agent 被滥用 |
多层防护、安全审计、E-Stop |
| 平台 API 变更 |
Channel 实现失效 |
解耦设计，快速修复单个实现 |
| 25 个频道维护负担 |
部分频道可能滞后 |
Feature flag 隔离，社区共同维护 |
已知限制
| 限制 |
说明 |
| 无 GUI |
纯命令行 + 配置文件，没有 Web 管理界面 |
| 无内置 RAG |
有混合搜索，但不是完整的 RAG 管线 |
| 单节点 |
不支持分布式 Agent 集群 |
| 无多租户 |
一个实例服务一个 Agent 身份 |
版本路线图（推断）
基于代码成熟度和文档中的线索：
v0.2.x — 稳定化
- 完善所有频道的测试覆盖
- 配置迁移和向后兼容
- 性能基准测试自动化
- 安全审计和渗透测试
v0.3.x — 增强
- 更完善的 RAG 管线（文档加载、分块、索引）
- WebUI 管理面板（可选）
- 多 Agent 协作
- 插件市场
v1.0 — 生产就绪
- API 稳定性承诺
- 语义化版本控制
- 企业支持选项
- 完整的安全合规文档
成功指标
| 指标 |
目标 |
| GitHub Stars |
持续增长 |
| 活跃贡献者 |
50+ |
| 生产部署数 |
可量化的用户案例 |
| 平均问题关闭时间 |
< 7 天 |
| 二进制大小 |
始终 < 15MB |
| 测试覆盖率 |
> 70% |
| 文档完整性 |
所有功能都有文档 |