ZeptoClaw

超轻量级个人AI助手。

---

$ zeptoclaw agent --stream -m "分析我们的API是否存在安全问题"

🤖 ZeptoClaw — 流式分析...

  [web_fetch]        获取API文档...
  [shell]            运行集成测试...
  [longterm_memory]  存储发现结果...

→ 发现12个接口，其中3个缺少认证头，1个存在开放重定向
→ 已将发现结果保存至长期记忆库，标签为“api-audit”

✓ 分析在4.2秒内完成

我们研究了市面上最好的AI助手及其权衡取舍。OpenClaw的集成能力虽强，却需要占用100MB内存、包含40万行代码；NanoClaw强调安全性，但依然离不开50MB的TypeScript代码；NemoClaw注重企业级治理，如策略锁定的沙箱、联邦推理路由等，却要以2GB的Docker容器来运行OpenClaw，且几乎没有任何内置工具；PicoClaw则实现了在10美元硬件上运行AI助手的目标，但为了达到这一目标，它不得不大幅精简功能。

而ZeptoClaw则吸取了这些经验教训：既保留了强大的集成能力、出色的安全性与完善的治理机制，又严格控制了体积——没有像其他产品那样做出任何妥协。它是一个仅6MB大小的Rust二进制文件，启动时间仅需50毫秒，内存占用仅为6MB，并内置了容器隔离、提示注入检测以及熔断器提供商栈等功能。

为什么选择ZeptoClaw

我们深入研究了哪些做法有效、哪些并不奏效。

OpenClaw证明了AI助手可以同时处理12个渠道和100多项技能，但其体积高达100MB、代码量达40万行；NanoClaw表明以安全为先是可行的，但它仍然需要50MB的TypeScript代码；NemoClaw展示了企业级治理的重要性——包括策略锁定的沙箱、联邦推理路由等，然而它却是一个包裹着OpenClaw的2GB Docker容器，且几乎没有内置工具；PicoClaw则证明了AI助手可以在10美元的硬件上运行，但为了实现这一点，它不得不剔除所有不必要的功能。

ZeptoClaw正是从这些经验中汲取了精华：无论是集成能力、安全性、治理机制，还是对体积的严格控制，都做到了兼顾，而无需在其中任何一项上做出妥协。它是一个仅6MB大小的Rust二进制文件，启动时间仅需50毫秒，内存占用仅为6MB，并配备了容器隔离、提示注入检测以及熔断器提供商栈等核心功能。

	OpenClaw	NemoClaw	NanoClaw	PicoClaw	ZeptoClaw
体积	~100MB	~2GB（Docker）	~50MB	<1MB	~6MB
语言	JS/TS	JS/TS/Python	TypeScript	Go	Rust
内置工具	100+技能	0（仅推理）	~20	~5	33
提供商	5	NVIDIA优先	3	2	16
渠道	12	0（使用OpenClaw）	3	0	11
沙箱	无	Landlock + seccomp	基础	无	6种运行时
可在10美元硬件上运行	否	否（需GPU）	否	是	是

安全性

AI代理会执行代码。大多数框架都默认认为不会出问题。

OpenClaw生态系统曾遭遇CVE-2026-25253漏洞（CVSS评分8.8——跨站WebSocket劫持导致远程代码执行）、ClawHavoc事件（341个恶意技能、超过9000次被入侵的安装），以及4.2万个暴露实例因认证绕过而遭攻击。ZeptoClaw正是基于这样的威胁模型构建的。

层	功能
6种沙箱运行时	Docker、Apple Container、Landlock、Firejail、Bubblewrap或原生——按需选择
提示注入检测	Aho-Corasick多模式匹配器（17种模式）+4条正则表达式规则
密钥泄露扫描器	22条正则表达式模式可在API密钥、令牌和凭据到达LLM之前将其捕获
策略引擎	7条规则阻止系统文件访问、加密密钥提取、SQL注入、编码后漏洞利用
输入验证器	100KB限制、空字节检测、空白比例分析、重复检测
Shell黑名单	正则表达式模式阻止反向Shell、rm -rf、权限提升
SSRF预防	DNS固定、私有IP屏蔽、IPv6过渡保护、协议验证
链式警报	检测危险的工具调用序列（写入→执行、内存→执行）
工具审批门	执行危险工具前需明确确认

每一层功能均默认启用，无需记住任何标志位、也无需额外配置即可使用。

安装

# 单行命令（macOS / Linux）
curl -fsSL https://raw.githubusercontent.com/qhkm/zeptoclaw/main/install.sh | sh

# Homebrew
brew install qhkm/tap/zeptoclaw

# Docker
docker pull ghcr.io/qhkm/zeptoclaw:latest

# 从源码构建
cargo install zeptoclaw --git https://github.com/qhkm/zeptoclaw

卸载

# 删除ZeptoClaw状态（~/.zeptoclaw）
zeptoclaw uninstall --yes

# 同时删除直接安装的二进制文件，位于~/.local/bin或/usr/local/bin
zeptoclaw uninstall --remove-binary --yes

# 使用包管理器安装的仍需通过相应包管理器卸载
brew uninstall qhkm/tap/zeptoclaw
cargo uninstall zeptoclaw

快速入门

# 交互式设置（引导您完成API密钥、渠道、工作空间的配置）
zeptoclaw onboard

# 与您的代理对话
zeptoclaw agent -m "你好，帮我设置一下工作空间"

# 流式逐token返回响应
zeptoclaw agent --stream -m "解释异步Rust"

# 使用内置模板
zeptoclaw agent --template researcher -m "搜索Rust代理框架"

# 批量处理提示
zeptoclaw batch --input prompts.txt --output results.jsonl

# 作为Telegram/Slack/Discord/Webhook网关启动
zeptoclaw gateway

# 每次请求都采用完全容器隔离
zeptoclaw gateway --containerized

从OpenClaw迁移

已经在运行OpenClaw？ZeptoClaw只需一条命令即可导入您的配置与技能。

# 自动检测OpenClaw安装路径（~/.openclaw、~/.clawdbot、~/.moldbot）
zeptoclaw migrate

# 手动指定路径
zeptoclaw migrate --from /path/to/openclaw

# 预览将被迁移的内容（不写入任何文件）
zeptoclaw migrate --dry-run

# 非交互式（跳过确认提示）
zeptoclaw migrate --yes

迁移命令会：

• 转换提供商API密钥、模型设置及渠道配置
• 将技能复制到~/.zeptoclaw/skills/
• 在覆盖原有ZeptoClaw配置前备份现有配置
• 验证迁移后的配置并报告任何问题
• 列出无法自动迁移的功能

支持JSON和JSON5格式的配置文件（包括注释、尾随逗号、未加引号的键）。

部署

任意 VPS

curl -fsSL https://zeptoclaw.com/setup.sh | bash

安装二进制文件并输出后续步骤。运行 zeptoclaw onboard 来配置提供商和通道。

提供商

ZeptoClaw 支持 16 家 LLM 提供商。所有兼容 OpenAI 的端点开箱即用。

提供商	配置键	设置
Anthropic	anthropic	api_key
OpenAI	openai	api_key
OpenRouter	openrouter	api_key
Google Gemini	gemini	api_key
Groq	groq	api_key
DeepSeek	deepseek	api_key
xAI (Grok)	xai	api_key
NVIDIA NIM	nvidia	api_key
Azure OpenAI	azure	api_key + api_base
AWS Bedrock	bedrock	api_key
Kimi (Moonshot)	kimi	api_key
Zhipu (GLM)	zhipu	api_key
Qianfan (Baidu)	qianfan	api_key
Novita AI	novita	api_key
Ollama	ollama	api_key（任意值）
VLLM	vllm	api_key（任意值）

在 ~/.zeptoclaw/config.json 中配置，或通过环境变量：

{
  "providers": {
    "openrouter": { "api_key": "sk-or-..." },
    "ollama": { "api_key": "ollama" }
  },
  "agents": { "defaults": { "model": "anthropic/claude-sonnet-4" } }
}

export ZEPTOCLAW_PROVIDERS_GROQ_API_KEY=gsk_...

任何提供商的基础 URL 都可以通过 api_base 覆盖，以用于代理或自托管端点。有关详细信息，请参阅 提供商文档。

功能

核心

功能	作用
多提供商 LLM	16 家提供商支持 SSE 流式传输、带退避的重试与预算上限、自动故障转移
33 种工具+插件	Shell、文件系统、grep、find、网络、git、stripe、PDF、转录、Android ADB 等
工具组合	通过自然语言描述创建新工具——可组合的 {{param}} 模板
代理集群	委派给子代理，支持并行扇出、聚合以及成本感知路由
库封装	可嵌入为一个 crate——ZeptoAgent::builder().provider(p).tool(t).build() 用于 Tauri/GUI 应用
批量模式	通过模板支持从文本/JSONL 文件中处理数百个提示
代理模式	观察者、助手、自主——基于类别的工具访问控制

通道与集成

功能	作用
11 通道网关	Telegram、Slack、Discord、WhatsApp Web + 云 API、Lark、电子邮件、Webhook、串口、ACP——统一的消息总线
人格系统	通过 /persona 命令实现每聊天的人格切换，并持久化长期记忆
插件系统	JSON 清单插件会自动从 ~/.zeptoclaw/plugins/ 中发现
钩子	before_tool、after_tool、on_error，支持日志、阻止和通知操作
定时任务与心跳	定期调度任务、主动签到、后台启动
内存与历史	工作区内存、长期键值存储、对话历史

安全与运维

功能	作用
6 种沙盒运行时	Docker、Apple Container、Landlock、Firejail、Bubblewrap 或原生
网关启动保护	在发生 N 次崩溃后优雅降级——防止崩溃循环
通道监控器	自动重启失效通道，设置冷却时间和最大重启次数
工具审批门	基于策略的准入控制——危险工具需确认方可使用
SSRF 防护	DNS 固定、私有 IP 阻止、IPv6 过渡保护、方案验证
Shell 阻止列表	正则表达式模式阻止反向 shell、rm -rf、权限提升
令牌预算与成本	每会话预算强制执行，针对 8 种模型进行成本估算
丰富的健康端点	/health 包含版本、运行时间、RSS、使用指标、组件检查
遥测	Prometheus + JSON 指标导出、结构化日志、按租户追踪
自我更新	zeptoclaw update 从 GitHub 下载最新版本
循环保护	SHA256 工具调用重复检测，配合熔断机制停止
上下文修剪	普通/紧急/关键压缩等级（70%/90%/95%），用于上下文窗口管理
会话修复	自动修复孤立工具结果、空/重复消息以及交替问题
配置热加载	网关每 30 秒轮询配置修改时间，并实时应用提供商、通道和安全更新
轻量版	HAND.toml 代理配置文件，附带预设（研究员、程序员、监控员）及 hand CLI
多租户	一台 VPS 上承载数百个租户——隔离的工作空间，每个约 6MB RAM

完整文档 — zeptoclaw.com/docs 涵盖配置、环境变量、CLI 参考、部署指南等内容。

灵感来源

ZeptoClaw 的灵感来自开源 AI 代理生态中的多个项目——OpenClaw、NemoClaw、NanoClaw 和 PicoClaw——它们各自以不同方式解决同一问题。NemoClaw 的声明式策略模型和经摘要验证的供应链影响了我们的安全理念。而 ZeptoClaw 的贡献在于 Rust 的内存安全、异步性能以及容器隔离技术，适用于生产环境下的多租户部署——所有这些都浓缩在仅 6MB 的二进制文件中，能够在 Docker 容器无法运行的地方运行。

使用方法

# CLI 代理（一次性或流式）
zeptoclaw agent -m "总结这个仓库"
zeptoclaw agent --stream -m "解释 async Rust"
zeptoclaw agent --template coder -m "为 main.rs 添加错误处理"

# 多通道网关
zeptoclaw gateway                    # Telegram、Slack、Discord 等
zeptoclaw gateway --containerized    # 每请求独立隔离容器

# 内存、密钥、个人资料
zeptoclaw memory set project:name "ZeptoClaw" --category project
zeptoclaw secrets encrypt
zeptoclaw hand activate researcher

# 批处理、诊断、自我更新
zeptoclaw batch --input prompts.txt --output results.jsonl  
zeptoclaw doctor                     # 诊断配置/提供商问题  
zeptoclaw update                     # 自我更新至最新版本  

```bash
# 开发
cargo build

# 运行所有测试（共计约3,900个）
cargo nextest run --lib

# 格式化与代码检查（每次提交前必做）
cargo clippy -- -D warnings  
cargo fmt -- --check

请参阅 CLAUDE.md 获取完整的架构说明，AGENTS.md 获取编码指南，以及 docs/ 获取基准测试、多租户部署和性能优化指南。

Zepto 堆栈

ZeptoClaw 是 Zepto 堆栈的一部分——一个用于在生产环境中运行 AI 代理的模块化系统。

ZeptoPM        — 编排、监控、重试、任务生命周期  
    │  
    │  create(spec) + spawn(worker, args, env)  
    ▼  
ZeptoCapsule   — 封装创建、进程隔离、资源限制  
    │  
    │  fork/namespace/microVM + 标准输入输出传输  
    ▼  
ZeptoClaw      — LLM 调用、工具使用、产物生成  
    │  
    └── 通过标准输入/输出进行 JSON 行式 IPC，回传至 ZeptoPM  

层级	仓库	角色
ZeptoPM	qhkm/zeptopm	进程管理器 — 配置驱动的守护进程、HTTP API、流水线、编排
ZeptoCapsule	qhkm/zeptocapsule	沙箱 — 进程/命名空间/Firecracker 隔离、资源限制、回退链
ZeptoRT	qhkm/zeptort	持久化运行时 — 日志化效果、快照恢复、OTP 式监督
ZeptoClaw	qhkm/zeptoclaw	代理框架 — 33 种工具、16 种提供商、11 种渠道、容器隔离

贡献

我们欢迎贡献！请阅读 CONTRIBUTING.md 了解：

• 如何从上游仓库设置您的分支和复刻
• 问题优先的工作流（先开 issue 再编码）
• Pull Request 流程与质量门控
• 添加新工具、渠道和提供商的指南

许可证

Apache 2.0 — 详见 LICENSE

免责声明

ZeptoClaw 是一个纯开源软件项目。它不涉及任何代币、加密货币、区块链组件或任何形式的金融工具。本项目与任何代币或金融产品均无关联。

---

ZeptoClaw — 因为你的 AI 助手不应该比你的文本编辑器占用更多内存。

由 Aisar Labs 构建

ZeptoClaw 快速上手指南

环境准备

系统要求：

• macOS 或 Linux 系统
• 支持 x86_64 架构（ARM64 也基本兼容）
• 推荐内存：至少 2GB RAM

前置依赖：

• 安装 curl 和 sh 命令行工具
• 如果使用 Homebrew，需先安装 Homebrew
• 如果使用 Docker，需安装 Docker 引擎

📌 提示：国内用户可使用镜像源加速下载，如需要请参考后续安装步骤中的说明。

---

安装步骤

方法一：一键安装（推荐）

curl -fsSL https://raw.githubusercontent.com/qhkm/zeptoclaw/main/install.sh | sh

⚠️ 注意：首次运行时可能会提示确认安装，按提示操作即可。

方法二：Homebrew 安装（macOS 用户）

brew install qhkm/tap/zeptoclaw

📦 国内用户可尝试使用 Homebrew 镜像 加速安装。

方法三：Docker 安装

docker pull ghcr.io/qhkm/zeptoclaw:latest

方法四：从源码编译安装（需 Rust 环境）

cargo install zeptoclaw --git https://github.com/qhkm/zeptoclaw

---

基本使用

启动交互式配置（首次使用推荐）

zeptoclaw onboard

该命令将引导你完成 API 密钥、通道和工作区的设置。

与 AI 助理对话

zeptoclaw agent -m "Hello, set up my workspace"

流式输出响应（逐字显示结果）

zeptoclaw agent --stream -m "Explain async Rust"

使用内置模板（例如研究员模式）

zeptoclaw agent --template researcher -m "Search for Rust agent frameworks"

批量处理多个提示

zeptoclaw batch --input prompts.txt --output results.jsonl

启动网关服务（支持 Telegram/Slack/Discord/Webhook）

zeptoclaw gateway

启用容器隔离模式（更安全）

zeptoclaw gateway --containerized

---

小结

ZeptoClaw 是一个轻量级、高性能、安全可靠的个人 AI 助理工具，适合开发者快速集成到自己的工作流中。通过简单的命令即可完成安装和使用，支持多种 LLM 提供商和丰富的功能模块，是构建智能助手的理想选择。