🦀 ZeroClaw — 个人AI助手

零开销。零妥协。100% Rust。100% 通用。
⚡️ 可在仅需$10的硬件上运行，且内存占用低于5MB：这比OpenClaw少99%的内存，也比Mac mini便宜98%！

由哈佛、MIT以及Sundai.Club社区的学生和成员共同打造。

🌐 语言： 🇺🇸 英语 · 🇨🇳 简体中文 · 🇯🇵 日本語 · 🇰🇷 한국어 · 🇻🇳 Tiếng Việt · 🇵🇭 Tagalog · 🇪🇸 Español · 🇧🇷 Português · 🇮🇹 Italiano · 🇩🇪 Deutsch · 🇫🇷 Français · 🇸🇦 العربية · 🇮🇳 हिन्दी · 🇷🇺 Русский · 🇧🇩 বাংলা · 🇮🇱 עברית · 🇵🇱 Polski · 🇨🇿 Čeština · 🇳🇱 Nederlands · 🇹🇷 Türkçe · 🇺🇦 Українська · 🇮🇩 Bahasa Indonesia · 🇹🇭 ไทย · 🇵🇰 اردو · 🇷🇴 Română · 🇸🇪 Svenska · 🇬🇷 Ελληνικά · 🇭🇺 Magyar · 🇫🇮 Suomi · 🇩🇰 Dansk · 🇳🇴 Norsk

ZeroClaw是一款您可以在自己的设备上运行的个人AI助手。它会通过您常用的渠道（WhatsApp、Telegram、Slack、Discord、Signal、iMessage、Matrix、IRC、Email、Bluesky、Nostr、Mattermost、Nextcloud Talk、DingTalk、Lark、QQ、Reddit、LinkedIn、Twitter、MQTT、WeChat Work等）与您互动。它配备了一个用于实时控制的Web仪表盘，并可连接到硬件外设（ESP32、STM32、Arduino、树莓派）。网关只是控制平面——产品是助手本身。

如果您想要一个本地化、快速响应且始终在线的单用户个人助手，那么这就是它。

官网 · 文档 · 架构 · 快速入门 · 从OpenClaw迁移 · 故障排除 · Discord

推荐设置： 在终端中运行zeroclaw onboard。ZeroClaw Onboard会逐步引导您完成网关、工作空间、渠道和提供商的设置。这是推荐的设置流程，适用于macOS、Linux和Windows（通过WSL2）。如果是新安装，请从此处开始：快速入门

订阅认证（OAuth）

• OpenAI Codex（ChatGPT订阅）
• Gemini（Google OAuth）
• Anthropic（API密钥或认证令牌）

模型说明：虽然支持多种提供商和模型，但为了获得最佳体验，建议使用您可用的最强大、最新一代模型。请参阅入门指南。

模型配置 + CLI：提供商参考 认证凭据轮换（OAuth vs API密钥）+ 故障转移：模型故障转移

安装（推荐）

运行时：Rust稳定工具链。单个二进制文件，无运行时依赖。

Homebrew（macOS/Linuxbrew）

brew install zeroclaw

一键启动

git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
./install.sh

安装完成后，zeroclaw onboard会自动运行，以配置您的工作空间和提供商。

快速入门（简要版）

完整的初学者指南（认证、配对、渠道）：快速入门

# 安装 + 启动
./install.sh

# 启动网关（webhook服务器 + Web仪表盘）
zeroclaw gateway                # 默认：127.0.0.1:42617
zeroclaw gateway --port 0       # 随机端口（安全性增强）

# 与助手对话
zeroclaw agent -m "你好，ZeroClaw！"

# 交互模式
zeroclaw agent

# 启动完全自主运行（网关 + 渠道 + 定时任务 + 手动操作）
zeroclaw daemon

# 检查状态
zeroclaw status

# 运行诊断
zeroclaw doctor

升级后，请运行zeroclaw doctor。

从源码编译（开发）

git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw

cargo build --release --locked
cargo install --path . --force --locked

zeroclaw onboard

开发回退方案（无需全局安装）： 在命令前加上cargo run --release --（例如：cargo run --release -- status）。

从OpenClaw迁移

ZeroClaw可以导入您的OpenClaw工作空间、记忆和配置：

# 预览将要迁移的内容（安全、只读）
zeroclaw migrate openclaw --dry-run

# 执行迁移
zeroclaw migrate openclaw

这会将您的内存条目、工作区文件和配置从 ~/.openclaw/ 迁移到 ~/.zeroclaw/。配置文件会自动从 JSON 转换为 TOML 格式。

安全默认设置（DM 访问）

ZeroClaw 会连接到真实的通信界面。请将传入的私信视为不受信任的输入。

完整安全指南：SECURITY.md

所有频道的默认行为：

• DM 配对（默认）：未知发件人会收到一个简短的配对码，机器人不会处理他们的消息。
• 批准方式：zeroclaw pairing approve <channel> <code>（然后该发件人会被加入本地白名单）。
• 公开的传入 DM 需要在 config.toml 中明确启用。
• 运行 zeroclaw doctor 可以发现有风险或配置错误的 DM 策略。

自主级别：

沙箱层： 工作区隔离、路径遍历拦截、命令白名单、禁止访问路径（/etc、/root、~/.ssh）、速率限制（每小时最大操作数、每日费用上限）。

📢 公告

请在此公告板上查看重要通知（重大变更、安全公告、维护窗口以及发布阻塞事项）。

亮点

• 默认精益运行时 — 常用 CLI 和状态工作流在发布版本中仅占用几 MB 内存。
• 经济高效的部署 — 专为 10 美元的开发板和小型云实例设计，无重量级运行时依赖。
• 快速冷启动 — 单二进制 Rust 运行时使命令和守护进程启动几乎瞬间完成。
• 可移植架构 — 一个二进制文件适用于 ARM、x86 和 RISC-V 架构，并支持插拔式提供商、通道和工具。
• 本地优先网关 — 统一控制平面，用于会话、通道、工具、定时任务、标准操作流程和事件管理。
• 多通道收件箱 — WhatsApp、Telegram、Slack、Discord、Signal、iMessage、Matrix、IRC、Email、Bluesky、Nostr、Mattermost、Nextcloud Talk、DingTalk、Lark、QQ、Reddit、LinkedIn、Twitter、MQTT、企业微信、WebSocket 等。
• 多智能体编排（Hands） — 按计划运行并随时间不断学习进化的自主智能体群。
• 标准操作流程 (SOPs) — 基于 MQTT、Webhook、Cron 定时任务及外部触发器的事件驱动工作流自动化。
• Web 控制台 — 使用 React 19 + Vite 构建的 Web UI，提供实时聊天、内存浏览器、配置编辑器、Cron 任务管理器和工具检查器。
• 硬件外设 — 通过 Peripheral 特性接口支持 ESP32、STM32 Nucleo、Arduino 和 Raspberry Pi GPIO。
• 一流工具集 — 包括 Shell、文件 I/O、浏览器、Git、Web 请求/搜索、MCP、Jira、Notion、Google Workspace 等 70 多种工具。
• 生命周期钩子 — 在每个阶段拦截并修改 LLM 调用、工具执行和消息。
• 技能平台 — 提供捆绑式、社区贡献及工作空间专属技能，并进行安全审计。
• 隧道支持 — Cloudflare、Tailscale、ngrok、OpenVPN 以及自定义远程访问隧道。

为什么团队选择 ZeroClaw

• 默认精益：Rust 编写的轻量级二进制文件，启动迅速，内存占用低。
• 设计安全：配对机制、严格沙盒隔离、显式白名单、工作空间范围限制。
• 完全可插拔：核心系统采用特性（Providers、Channels、Tools、Memory、Tunnels）实现模块化。
• 无厂商锁定：兼容 OpenAI 的提供商支持 + 可插拔的自定义端点。

基准测试快照（ZeroClaw vs OpenClaw，可复现）

本地机器快速基准测试（macOS arm64，2026 年 2 月），以 0.8GHz 边缘硬件为基准归一化。

注：ZeroClaw 的结果基于发布版本，使用 /usr/bin/time -l 测量。OpenClaw 需要 Node.js 运行时（通常额外消耗约 390MB 内存），而 NanoBot 则需要 Python 运行时。PicoClaw 和 ZeroClaw 是静态编译的二进制文件。上述 RAM 数值为运行时内存；构建时的编译需求更高。

可复现的本地测量方法

cargo build --release
ls -lh target/release/zeroclaw

/usr/bin/time -l target/release/zeroclaw --help
/usr/bin/time -l target/release/zeroclaw status

我们迄今为止构建的一切

核心平台

• HTTP/WS/SSE 控制平面网关，支持会话管理、在线状态、配置、定时任务、Webhook、Web 控制台和设备配对。
• CLI 接口：gateway、agent、onboard、doctor、status、service、migrate、auth、cron、channel、skills。
• 智能体编排循环，包括工具调度、提示构造、消息分类和记忆加载。
• 会话模型，内置安全策略执行、自主级别和审批门控机制。
• 弹性提供商封装层，支持故障转移、重试及跨 20 多个 LLM 后端的模型路由。

通道

通道：WhatsApp（原生）、Telegram、Slack、Discord、Signal、iMessage、Matrix、IRC、Email、Bluesky、DingTalk、Lark、Mattermost、Nextcloud Talk、Nostr、QQ、Reddit、LinkedIn、Twitter、MQTT、企业微信、WATI、Mochat、Linq、Notion、WebSocket、ClawdTalk。

功能开关：Matrix (channel-matrix)、Lark (channel-lark)、Nostr (channel-nostr)。

Web 控制台

由 Gateway 直接提供服务的 React 19 + Vite 6 + Tailwind CSS 4 Web 控制台：

• 仪表盘 — 系统概览、健康状态、运行时间、成本跟踪。
• 智能体聊天 — 与智能体的交互式聊天。
• 记忆 — 浏览和管理记忆条目。
• 配置 — 查看和编辑配置。
• Cron — 管理定时任务。
• 工具 — 浏览可用工具。
• 日志 — 查看智能体活动日志。
• 成本 — 记录 Token 使用情况和成本。
• 医生 — 系统健康诊断。
• 集成 — 集成状态与设置。
• 配对 — 设备配对管理。

固件目标

工具与自动化

• 核心工具：Shell、文件读写编辑、Git 操作、Glob 搜索、内容搜索。
• Web 工具：浏览器控制、网页抓取、网络搜索、截图、图片信息提取、PDF 阅读。
• 集成工具：Jira、Notion、Google Workspace、Microsoft 365、LinkedIn、Composio、Pushover、天气预报（wttr.in）。
• MCP：模型上下文协议工具封装 + 延迟工具集。
• 调度工具：Cron 添加/删除/更新/运行、定时任务工具。
• 记忆工具：回忆、存储、遗忘、知识获取、项目情报。
• 高级工具：代理间委托、智能体群、模型切换/路由、安全运维、云运维。
• 硬件工具：板卡信息、内存映射、内存读取（需功能开关）。

运行时与安全性

• 自主级别：只读、受监督（默认）、完全自主。
• 沙盒隔离：工作空间隔离、路径遍历阻断、命令白名单、禁止路径、Linux 的 Landlock 和 Bubblewrap。
• 速率限制：每小时最大操作次数、每日最大成本（可配置）。
• 审批门控：中高风险操作需交互式审批。
• 紧急停止：具备紧急关机能力。
• 自动化 CI 中包含 129+ 项安全测试。

运维 + 打包

• Web 仪表板直接由网关提供服务。
• 隧道支持：Cloudflare、Tailscale、ngrok、OpenVPN、自定义命令。
• Docker 运行时适配器，用于容器化执行。
• CI/CD：测试版（推送自动触发）→ 稳定版（手动调度）→ Docker、crates.io、Scoop、AUR、Homebrew、推特发布。
• 预编译二进制文件适用于 Linux（x86_64、aarch64、armv7）、macOS（x86_64、aarch64）、Windows（x86_64）。

配置

最小化的 ~/.zeroclaw/config.toml：

default_provider = "anthropic"
api_key = "sk-ant-..."

完整配置参考：docs/reference/api/config-reference.md。

通道配置

Telegram：

[channels.telegram]
bot_token = "123456:ABC-DEF..."

Discord：

[channels.discord]
token = "your-bot-token"

Slack：

[channels.slack]
bot_token = "xoxb-..."
app_token = "xapp-..."

WhatsApp：

[channels.whatsapp]
enabled = true

Matrix：

[channels.matrix]
homeserver_url = "https://matrix.org"
username = "@bot:matrix.org"
password = "..."

Signal：

[channels.signal]
phone_number = "+1234567890"

隧道配置

[tunnel]
kind = "cloudflare"  # 或 "tailscale"、"ngrok"、"openvpn"、"custom"、"none"

详情：通道参考 · 配置参考

当前运行时支持

• native（默认）— 直接进程执行，路径最快，适合可信环境。
• docker — 完全容器隔离，强制安全策略，需要 Docker。

设置 runtime.kind = "docker" 以实现严格的沙箱或网络隔离。

订阅认证（OpenAI Codex / Claude Code / Gemini）

ZeroClaw 支持订阅原生认证配置文件（多账号，静态加密）。

• 存储文件：~/.zeroclaw/auth-profiles.json
• 加密密钥：~/.zeroclaw/.secret_key
• 配置文件 ID 格式：<provider>:<profile_name>（例如：openai-codex:work）

# OpenAI Codex OAuth（ChatGPT 订阅）
zeroclaw auth login --provider openai-codex --device-code

# Gemini OAuth
zeroclaw auth login --provider gemini --profile default

# Anthropic setup-token
zeroclaw auth paste-token --provider anthropic --profile default --auth-kind authorization

# 检查 / 刷新 / 切换配置文件
zeroclaw auth status
zeroclaw auth refresh --provider openai-codex --profile default
zeroclaw auth use --provider openai-codex --profile work

# 使用订阅认证运行代理
zeroclaw agent --provider openai-codex -m "hello"
zeroclaw agent --provider anthropic -m "hello"

代理工作区 + 技能

工作区根目录：~/.zeroclaw/workspace/（可通过配置调整）。

注入的提示文件：

• IDENTITY.md — 代理个性与角色
• USER.md — 用户上下文与偏好
• MEMORY.md — 长期事实与经验教训
• AGENTS.md — 会话约定与初始化规则
• SOUL.md — 核心身份与运作原则

技能：~/.zeroclaw/workspace/skills/<skill>/SKILL.md 或 SKILL.toml。

# 列出已安装技能
zeroclaw skills list

# 从 Git 安装
zeroclaw skills install https://github.com/user/my-skill.git

# 安装前安全审计
zeroclaw skills audit https://github.com/user/my-skill.git

# 移除技能
zeroclaw skills remove my-skill

CLI 命令

# 工作区管理
zeroclaw onboard              # 引导式设置向导
zeroclaw status               # 显示守护进程/代理状态
zeroclaw doctor               # 运行系统诊断

# 网关 + 守护进程
zeroclaw gateway              # 启动网关服务器（127.0.0.1:42617）
zeroclaw daemon               # 启动完全自主运行时

# 代理
zeroclaw agent                # 交互式聊天模式
zeroclaw agent -m "message"   # 单消息模式

# 服务管理
zeroclaw service install      # 作为操作系统服务安装（launchd/systemd）
zeroclaw service start|stop|restart|status

# 通道
zeroclaw channel list         # 列出已配置的通道
zeroclaw channel doctor       # 检查通道健康状况
zeroclaw channel bind-telegram 123456789

# Cron + 调度
zeroclaw cron list            # 列出计划任务
zeroclaw cron add "*/5 * * * *" --prompt "检查系统健康"
zeroclaw cron remove <id>

# 内存
zeroclaw memory list          # 列出记忆条目
zeroclaw memory get <key>     # 获取某条记忆
zeroclaw memory stats         # 内存统计信息

# 认证配置文件
zeroclaw auth login --provider <name>
zeroclaw auth status
zeroclaw auth use --provider <name> --profile <profile>

# 硬件外设
zeroclaw hardware discover    # 扫描连接的设备
zeroclaw peripheral list      # 列出已连接的外设
zeroclaw peripheral flash     # 为设备刷写固件

# 迁移
zeroclaw migrate openclaw --dry-run
zeroclaw migrate openclaw

# Shell 补全
source <(zeroclaw completions bash)
zeroclaw completions zsh > ~/.zfunc/_zeroclaw

完整命令参考：docs/reference/cli/commands-reference.md

先决条件

curl -LsSf https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | bash

./install.sh                                          # 完整版（默认功能）
./install.sh --minimal                                # 仅内核版 (~6.6MB)
./install.sh --minimal --features agent-runtime,channel-discord  # 自定义
./install.sh --list-features                          # 查看所有可用功能

预编译二进制文件

发布资产适用于以下平台：

• Linux：x86_64、aarch64、armv7
• macOS：x86_64、aarch64
• Windows：x86_64

请从以下链接下载最新版本的资产： https://github.com/zeroclaw-labs/zeroclaw/releases/latest

文档

当您完成入门流程并希望深入了解时，请使用这些文档。

• 从 文档索引 开始，了解导航和内容分布。
• 阅读 架构概述，以全面了解系统模型。
• 当您需要每个配置项及示例时，请参考 配置参考。
• 按照 运维手册 正确运行 Gateway。
• 按照 ZeroClaw 入门 进行引导式设置。
• 使用 故障排除指南 调试常见问题。
• 在公开任何内容之前，请查阅 安全指南。

参考文档

• 文档中心：docs/README.md
• 统一文档目录：docs/SUMMARY.md
• 命令参考：docs/reference/cli/commands-reference.md
• 配置参考：docs/reference/api/config-reference.md
• 提供商参考：docs/reference/api/providers-reference.md
• 渠道参考：docs/reference/api/channels-reference.md
• 运维手册：docs/ops/operations-runbook.md
• 故障排除：docs/ops/troubleshooting.md

协作文档

• 贡献指南：CONTRIBUTING.md
• PR 流程政策：docs/contributing/pr-workflow.md
• CI 流程指南：docs/contributing/ci-map.md
• 审查员手册：docs/contributing/reviewer-playbook.md
• 安全披露政策：SECURITY.md
• 文档模板：docs/contributing/doc-template.md

部署 + 运维

• 网络部署指南：docs/ops/network-deployment.md
• 代理助手手册：docs/ops/proxy-agent-playbook.md
• 硬件指南：docs/hardware/README.md

冰蟹 🦀

ZeroClaw 是为顺滑的螃蟹 🦀 打造的，它是一款快速高效的 AI 助手。由 Argenis De La Rosa 和社区共同构建。

• zeroclawlabs.ai
• @zeroclawlabs

支持 ZeroClaw

🙏 特别致谢

衷心感谢那些激励并推动这项开源工作的社区和机构：

• 哈佛大学 — 激发了我们的求知欲，并不断突破可能性的边界。
• MIT — 致力于推广开放知识、开源文化，以及科技应惠及每个人的信念。
• Sundai Club — 感谢社区、活力以及不懈地打造有意义事物的动力。
• 世界及更远的地方 🌍✨ — 感谢每一位贡献者、梦想家和建设者，是你们让开源成为一股向善的力量。这一切都属于你们。

我们之所以选择开源，是因为最好的想法来自四面八方。如果您正在阅读这段文字，那么您就是其中的一员。欢迎加入。🦀❤️

贡献

刚接触 ZeroClaw？请查找标记为 good first issue 的问题 — 请参阅我们的 贡献指南 了解如何开始。欢迎提交 AI 或充满创意的 PR！🤖

请参阅 CONTRIBUTING.md 和 CLA.md。实现一个 trait，提交一个 PR：

• CI 流程指南：docs/contributing/ci-map.md
• 新的 Provider → src/providers/
• 新的 Channel → src/channels/
• 新的 Observer → src/observability/
• 新的 Tool → src/tools/
• 新的 Memory → src/memory/
• 新的 Tunnel → src/tunnel/
• 新的 Peripheral → src/peripherals/
• 新的 Skill → ~/.zeroclaw/workspace/skills/<name>/

⚠️ 官方仓库与冒充警告

这是唯一的官方 ZeroClaw 仓库：

https://github.com/zeroclaw-labs/zeroclaw

任何其他声称是“ZeroClaw”或暗示与 ZeroClaw Labs 有关联的仓库、组织、域名或软件包，均 未经授权且与本项目无关。已知的未经授权的分叉将在 TRADEMARK.md 中列出。

如果您遇到冒充或商标滥用的情况，请 提交一个问题。

许可证

ZeroClaw 采用双重许可证，以实现最大的开放性和对贡献者的保护：

您可以选择其中任意一种许可证。贡献者会自动授予两种许可证下的权利——完整贡献者协议请参阅 CLA.md。

商标

ZeroClaw 名称和标志是 ZeroClaw Labs 的注册商标。本许可证并不授予您使用这些商标以暗示认可或关联的权利。有关允许和禁止的使用方式，请参阅 TRADEMARK.md。

贡献者保护

• 您 保留对您贡献的版权
• 专利许可（Apache 2.0）可保护您免受其他贡献者的专利诉讼
• 您的贡献将 永久署名 在提交记录和 NOTICE 文件中
• 贡献并不会转移任何商标权

ZeroClaw — 零开销。零妥协。随处部署。任意替换。🦀

贡献者

此列表由 GitHub 贡献者图生成，并会自动更新。

星标历史

ZeroClaw 快速上手指南

ZeroClaw 是一款零开销、完全用 Rust 编写的个人 AI 助手。它支持在极低配置硬件（<5MB 内存）上运行，并能通过 WhatsApp、微信、钉钉、Telegram 等多种渠道与你交互。

环境准备

• 操作系统：macOS, Linux, 或 Windows (需通过 WSL2)。
• 运行时依赖：无（编译后为单一二进制文件）。
• 构建依赖（仅源码安装需要）：Rust Stable 工具链。
  • 安装 Rust: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

安装步骤

推荐以下两种安装方式，任选其一即可。

方式一：一键脚本安装（推荐）

此方法会自动克隆仓库并运行初始化向导。

git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
./install.sh

安装完成后，zeroclaw onboard 会自动运行，引导你配置工作空间和 AI 提供商。

方式二：Homebrew 安装 (macOS/Linux)

brew install zeroclaw

安装完成后，手动运行初始化向导：

zeroclaw onboard

方式三：源码编译 (开发模式)

如果你希望从最新源码构建：

git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw

cargo build --release --locked
cargo install --path . --force --locked

zeroclaw onboard

基本使用

安装并配置完成后，你可以使用以下命令启动服务或与助手交互。

1. 启动网关（Web 控制台）

启动 Webhook 服务器和网页仪表盘，默认监听 127.0.0.1:42617。

zeroclaw gateway

若需随机端口以增强安全性：

zeroclaw gateway --port 0

2. 与助手对话

发送单条消息测试：

zeroclaw agent -m "Hello, ZeroClaw!"

进入交互式对话模式：

zeroclaw agent

3. 启动全自动守护进程

同时运行网关、渠道监听、定时任务和执行模块（生产环境推荐）：

zeroclaw daemon

4. 状态检查与诊断

查看运行状态：

zeroclaw status

运行健康检查（升级后建议执行）：

zeroclaw doctor

安全提示：ZeroClaw 默认开启 DM 配对保护。陌生用户发送消息时会收到配对码，需管理员手动批准（zeroclaw pairing approve <channel> <code>）后方可交互，以防止未授权访问。