ZeroClaw 是一个以 Rust 为优先开发语言的自主代理运行时。它从消息平台接收消息，经由 LLM 路由，执行工具调用，持久化内存，并返回响应。它还可以控制硬件外设并作为长期运行的守护进程。
用户消息 (Telegram/Discord/Slack/...)
│
▼
┌─────────┐ ┌────────────┐
│ 渠道(Channel) │────▶│ 代理(Agent) │ (src/agent/)
└─────────┘ │ 循环(Loop) │
│ │◀──── 内存加载器（加载相关上下文）
│ │◀──── 系统提示词构建器
│ │◀──── 查询分类器（模型路由）
└─────┬──────┘
│
▼
┌───────────┐
│ 提供商(Provider) │ (LLM: Anthropic, OpenAI, Gemini, 等)
└─────┬─────┘
│
是否为工具调用？
┌────┴────┐
▼ ▼
┌────────┐ 文本响应
│ 工具(Tools) │ │
└────┬───┘ │
│ │
▼ ▼
将结果反馈 通过渠道发送
给 LLM 返回响应
zeroclaw/
├── src/ # Rust 源代码（运行时核心）
├── crates/robot-kit/ # 硬件机器人套件的独立 crate
├── tests/ # 集成/端到端测试
├── benches/ # 基准测试（代理循环）
├── docs/contributing/extension-examples.md # 扩展示例（自定义提供商/渠道/工具/内存）
├── firmware/ # Arduino、ESP32、Nucleo 开发板的嵌入式固件
├── web/ # Web UI（Vite + TypeScript）
├── python/ # Python SDK / 工具桥接
├── dev/ # 本地开发工具（Docker、CI 脚本、沙箱）
├── scripts/ # CI 脚本、发布自动化、引导脚本
├── docs/ # 文档系统（多语言、运行时参考）
├── .github/ # CI 工作流、PR 模板、自动化
├── playground/ # （空，实验性临时空间）
├── Cargo.toml # 工作区清单
├── Dockerfile # 容器构建文件
├── docker-compose.yml # 服务编排
├── flake.nix # Nix 开发环境
└── install.sh # 一键安装脚本
| 文件 |
行数 |
角色 |
main.rs |
1,977 |
CLI 入口点。Clap 解析器，命令分发。所有 zeroclaw <子命令> 路由都在此处。 |
lib.rs |
436 |
模块声明、可见性（pub 与 pub(crate)）、库和二进制文件之间共享的 CLI 命令枚举（ServiceCommands、ChannelCommands、SkillCommands 等）。 |
| 模块 |
关键文件 |
角色 |
agent/ |
agent.rs、loop_.rs (5.6k)、dispatcher.rs、prompt.rs、classifier.rs、memory_loader.rs |
大脑。 AgentBuilder 组合提供商+工具+内存+观察者。loop_.rs 运行多轮工具调用循环。分发器处理原生与 XML 工具调用解析。分类器将查询路由到不同模型。 |
config/ |
schema.rs (7.6k)、mod.rs、traits.rs |
所有配置结构体。 每个子系统的配置都位于 schema.rs 中 —— 提供商、渠道、内存、安全、网关、工具、硬件、调度等。从 TOML 文件加载。 |
runtime/ |
native.rs、docker.rs、wasm.rs、traits.rs |
平台适配器。 RuntimeAdapter 特征抽象了 shell 访问、文件系统、存储路径、内存预算。原生模式 = 直接访问操作系统。Docker 模式 = 容器隔离。WASM 模式 = 实验性支持。 |
| 模块 |
关键文件 |
角色 |
providers/ |
traits.rs、mod.rs (2.9k)、reliable.rs、router.rs + 11 个提供商文件 |
LLM 集成。 Provider 特征：chat()、chat_with_system()、capabilities()、convert_tools()。mod.rs 中的工厂函数根据名称创建提供商实例。ReliableProvider 为任意提供商包装了重试/回退链。RoutedProvider 根据分类器提示进行路由。 |
提供商：anthropic、openai、openai_codex、openrouter、gemini、ollama、compatible（OpenAI 兼容）、copilot、bedrock、telnyx、glm
| 模块 |
关键文件 |
角色 |
channels/ |
traits.rs、mod.rs (6.6k) + 22 个渠道文件 |
输入/输出传输层。 Channel 特征：send()、listen()、health_check()、start_typing()、草稿更新。mod.rs 中的工厂函数将配置与渠道实例关联，管理每个发送者的对话历史（最多 50 条消息）。 |
渠道：telegram (4.6k)、discord、slack、whatsapp、whatsapp_web、matrix、signal、email_channel、qq、dingtalk、lark、imessage、irc、nostr、mattermost、nextcloud_talk、wati、mqtt、linq、clawdtalk、cli
| 模块 |
关键文件 |
角色 |
tools/ |
traits.rs、mod.rs (635) + 38 个工具文件 |
代理可执行的操作。 Tool 特征：name()、description()、parameters_schema()、execute()。两个注册表：default_tools()（6 个基础工具）和 all_tools_with_runtime()（完整集合，配置门控）。 |
工具类别：
- 文件/Shell:
shell、file_read、file_write、file_edit、glob_search、content_search
- 内存:
memory_store、memory_recall、memory_forget
- Web:
browser、browser_open、web_fetch、web_search_tool、http_request
- 调度:
cron_add、cron_list、cron_remove、cron_update、cron_run、cron_runs、schedule
- 委托:
delegate（子代理生成）、composio（OAuth 集成）
- 硬件:
hardware_board_info、hardware_memory_map、hardware_memory_read
- SOP:
sop_execute、sop_advance、sop_approve、sop_list、sop_status
- 实用工具:
git_operations、image_info、pdf_read、screenshot、pushover、model_routing_config、proxy_config、cli_discovery、schema
| 模块 |
关键文件 |
角色 |
memory/ |
traits.rs、backend.rs、mod.rs + 8 个后端文件 |
持久化知识。 Memory 特征：store()、recall()、get()、list()、forget()、count()。类别：核心、日常、对话、自定义。 |
后端：sqlite、markdown、lucid（混合 SQLite + 向量嵌入）、qdrant（向量数据库）、postgres、none
支持模块：embeddings.rs（向量嵌入生成）、vector.rs（向量操作）、chunker.rs（文本拆分）、hygiene.rs（清理）、snapshot.rs（备份）、response_cache.rs（缓存）、cli.rs（CLI 命令）
| 模块 |
关键文件 |
角色 |
security/ |
policy.rs (2.3k)、secrets.rs、pairing.rs、prompt_guard.rs、leak_detector.rs、audit.rs、otp.rs、estop.rs、domain_matcher.rs + 4 个沙箱文件 |
策略引擎与执行。 SecurityPolicy：自主级别（只读/监督/完全）、工作区限制、命令白名单、禁止路径、速率限制、成本上限。 |
沙箱：bubblewrap.rs、firejail.rs、landlock.rs、docker.rs、detect.rs（自动检测最佳可用沙箱）
| 模块 |
关键文件 |
角色 |
gateway/ |
mod.rs (2.8k)、api.rs (1.4k)、sse.rs、ws.rs、static_files.rs |
Axum HTTP 服务器。 Webhook 接收器（WhatsApp、WATI、Linq、Nextcloud Talk）、REST API、SSE 流、WebSocket 支持。速率限制、幂等键、64KB 主体限制、30 秒超时。 |
| 模块 |
关键文件 |
角色 |
peripherals/ |
traits.rs、mod.rs、serial.rs、rpi.rs、arduino_flash.rs、uno_q_bridge.rs、uno_q_setup.rs、nucleo_flash.rs、capabilities_tool.rs |
硬件开发板抽象。 Peripheral 特征：connect()、disconnect()、health_check()、tools()。每个外设将其能力暴露为代理可以调用的工具。 |
hardware/ |
discover.rs、introspect.rs、registry.rs、mod.rs |
USB 发现与开发板识别。 扫描 VID/PID，匹配已知开发板，内省连接的设备。 |
| 模块 |
关键文件 |
角色 |
observability/ |
traits.rs、mod.rs、log.rs、prometheus.rs、otel.rs、verbose.rs、noop.rs、multi.rs、runtime_trace.rs |
指标与追踪。 Observer 特征：log_event()。复合观察者（multi.rs）将事件扇出到多个后端。 |
| 模块 |
关键文件 |
角色 |
skills/ |
mod.rs (1.5k)、audit.rs |
用户/社区创作的能力。 从 ~/.zeroclaw/workspace/skills/<name>/SKILL.md 加载。CLI 命令：列表、安装、审计、移除。可选从开放技能仓库同步社区内容。 |
skillforge/ |
scout.rs、evaluate.rs、integrate.rs、mod.rs |
技能发现与评估。 搜寻技能，评估质量/适用性，集成到运行时。 |
| 模块 |
关键文件 |
角色 |
sop/ |
engine.rs (1.6k)、metrics.rs (1.5k)、types.rs、dispatch.rs、condition.rs、gates.rs、audit.rs、mod.rs |
工作流引擎。 定义包含条件、门控（审批检查点）和指标的多步骤流程。代理可以执行、推进和审计 SOP 运行。 |
| 模块 |
关键文件 |
角色 |
cron/ |
scheduler.rs、schedule.rs、store.rs、types.rs、mod.rs |
任务调度器。 Cron 表达式、一次性定时器、固定间隔。持久化存储。 |
heartbeat/ |
engine.rs、mod.rs |
存活监控。 对渠道/网关的定期健康检查。 |
daemon/ |
mod.rs |
长期运行守护进程。 同时启动网关 + 渠道 + 心跳 + 调度器。 |
service/ |
mod.rs (1.3k) |
操作系统服务管理。 通过 systemd 或 launchd 安装/启动/停止/重启。 |
hooks/ |
mod.rs、runner.rs、traits.rs、builtin/ |
生命周期钩子。 在事件发生时运行用户脚本（工具执行前/后、消息接收等）。 |
| 模块 |
关键文件 |
角色 |
onboard/ |
wizard.rs (7.2k)、mod.rs |
首次运行设置向导。 交互式或快速模式引导：提供商、API 密钥、渠道、内存后端。 |
auth/ |
profiles.rs、anthropic_token.rs、gemini_oauth.rs、openai_oauth.rs、oauth_common.rs |
认证配置文件与 OAuth 流程。 按提供商管理凭证。 |
approval/ |
mod.rs |
审批工作流。 对风险操作进行人工审批门控。 |
doctor/ |
mod.rs (1.3k) |
诊断工具。 检查守护进程健康状态、调度器新鲜度、渠道连通性。 |
health/ |
mod.rs |
健康检查端点。 |
cost/ |
tracker.rs、types.rs、mod.rs |
成本追踪。 按会话和按日成本核算。 |
tunnel/ |
cloudflare.rs、ngrok.rs、tailscale.rs、custom.rs、none.rs、mod.rs |
隧道适配器。 通过 Cloudflare、ngrok、Tailscale 或自定义隧道暴露网关。 |
rag/ |
mod.rs |
检索增强生成（Retrieval-Augmented Generation）。 PDF 提取、分块支持。 |
integrations/ |
registry.rs、mod.rs |
集成注册表。 第三方集成目录。 |
identity.rs |
(1.5k) |
代理身份。 代理实例的名称、描述、角色设定。 |
multimodal.rs |
— |
多模态支持。 图像/视觉处理配置。 |
migration.rs |
— |
数据迁移。 从 OpenClaw 工作区导入。 |
util.rs |
— |
共享工具函数。 |
| 目录 |
角色 |
crates/robot-kit/ |
硬件机器人套件功能的独立 Rust crate |
tests/ |
集成和端到端测试（代理循环、配置持久化、渠道路由、提供商解析、Webhook 安全） |
benches/ |
性能基准测试（agent_benchmarks.rs） |
docs/contributing/extension-examples.md |
自定义提供商、渠道、工具和内存后端的扩展示例 |
firmware/ |
嵌入式固件：arduino/、esp32/、esp32-ui/、nucleo/、uno-q-bridge/ |
web/ |
Web UI 前端（Vite + TypeScript） |
python/ |
Python SDK / 工具桥接，包含自身测试 |
dev/ |
本地开发：Docker Compose、CI 脚本（ci.sh）、配置模板、沙箱配置 |
scripts/ |
CI 辅助工具、发布自动化、引导脚本、贡献者层级计算 |
docs/ |
文档系统：多语言（en/zh-CN/ja/ru/fr/vi）、运行时参考、运维操作手册、安全提案 |
.github/ |
CI 工作流、PR 模板、Issue 模板、自动化 |
main.rs ──▶ agent/ ──▶ providers/ (LLM 调用)
│──▶ tools/ (能力执行)
│──▶ memory/ (上下文持久化)
│──▶ observability/ (事件日志)
│──▶ security/ (策略执行)
│──▶ config/ (所有配置结构体)
│──▶ runtime/ (平台抽象)
│
main.rs ──▶ channels/ ──▶ agent/ (消息路由)
main.rs ──▶ gateway/ ──▶ agent/ (HTTP/WS 路由)
main.rs ──▶ daemon/ ──▶ gateway/ + channels/ + cron/ + heartbeat/
具体模块向内依赖于特征/配置。
特征从不导入具体实现。
zeroclaw
├── onboard [--interactive] [--force] # 首次运行设置
├── agent [-m "msg"] [-p provider] # 启动代理循环
├── daemon [-p port] # 完整运行时（网关+渠道+cron+心跳）
├── gateway [-p port] # 仅 HTTP API 服务器
├── channel {list|start|doctor|add|remove|bind-telegram}
├── skill {list|install|audit|remove}
├── memory {list|get|stats|clear}
├── cron {list|add|add-at|add-every|once|remove|update|pause|resume}
├── peripheral {list|add|flash|flash-nucleo|setup-uno-q}
├── hardware {discover|introspect|info}
├── service {install|start|stop|restart|status|uninstall}
├── doctor # 诊断工具
├── status # 系统概览
├── estop [--level] [status|resume] # 紧急停止
├── migrate openclaw # 数据迁移
├── pair # 设备配对
├── auth-profiles # 凭证管理
├── version / completions # 元命令
└── config {show|edit|validate|reset}