Crates

工作区被划分为多个层级。边缘 crate 负责与外部世界交互；核心 crate 负责协调；支持 crate 提供工具函数。每个 crate 都有自己的 rustdoc，参见 API (rustdoc)。

层：核心

`zeroclaw-runtime`

zerocode 的代理循环、安全策略实施、SOP 引擎、cron 调度器、SubAgent 生命周期及 RPC 层。依赖于所有其他 core 和 edge crate。

值得注意的子模块：

agent/：主要的请求/响应循环、流式传输、工具调用编排
security/：策略类型、沙箱检测、OTP、紧急停止
sop/：标准操作流程引擎（参见 SOP → 概述）
subagent/：SubAgent 的创建与生命周期管理（参见委派与 SubAgent）
cron/、daemon/、heartbeat/：调度和长时间运行的进程管理
skills/：技能编译和执行
service/：systemd / launchctl / Windows Service 集成
rpc/：zerocode 的 RPC 层

`zeroclaw-config`

TOML 模式及其验证。处理：

自主性级别枚举（ReadOnly / Supervised / Full）
加密密钥存储（本地密钥文件）
工作区解析（环境变量、Homebrew 路径、XDG、容器检测）
模式版本控制与迁移

所有面向用户的配置键均在参考 → 配置中记录，该文档由本 crate 生成。

`zeroclaw-api`

内核 ABI。定义核心公共 trait，包括：

ModelProvider：具备流式传输能力标志的 LLM 客户端接口
Channel：入站/出站消息收发界面
Tool：智能体可调用的能力
Memory：对话的存储与检索
Observer：类型化的指标/可观测性接收器

运行时仅依赖于这些特性，而不依赖于具体的实现。这就是为什么添加 provider/channel/tool 只需实现一个特性，而无需修补核心。

层：边缘

`zeroclaw-providers`

所有 LLM 客户端实现以及路由和重试封装器。完整列表请参阅模型提供方 → 概述。

结构：

traits.rs：从 zeroclaw-api 重新导出，外加 provider 内部辅助工具
anthropic.rs、openai.rs、ollama.rs 等：每个原生提供方对应一个文件
compatible.rs：由 20 多家提供商（Groq、Mistral、xAI、Venice 等）复用的单一 OpenAI 兼容实现
router.rs：基于提示的逐次调用模型路由选择
reliable.rs：重试 / 退避 / 冷却以及有序的模型提供商回退包装器
streaming.rs：SSE 解析、token 估算、工具调用增量

`zeroclaw-channels`

30+ 消息集成。请参阅 Channels → 概览获取目录。

所有通道均实现来自 zeroclaw-api 的 Channel trait。每个通道都受 feature 门控，最小化构建仅包含你编译时纳入的通道。

orchestrator/ 子模块负责处理消息流式传输、草稿更新、多消息拆分以及 ACP 服务器。

`zeroclaw-gateway`

HTTP/WebSocket 网关。通过以下方式暴露运行时：

REST API（会话、内存、状态、定时任务管理）
用于流式响应的 WebSocket
Web 仪表板（静态资源 + 身份验证）
Webhook 端点（来自推送的通道）

默认情况下需要配对；[gateway.allow_public_bind = true] 允许绑定到 0.0.0.0。

`zeroclaw-tools`

代理调用的可调用工具。不要与 CLI zeroclaw 子命令混淆。

包括：browser、http_request、web_search、shell、file_read、file_write、硬件探测（hardware_board_info、hardware_memory_read）等。参见 Tools → Overview。

每个工具都通过工厂注册，并通过本地化的 Fluent 字符串向模型描述。

图层：支持

`zeroclaw-memory`

对话记忆与检索。SQLite 是默认后端；PostgreSQL 可通过 --features memory-postgres 启用，适用于需要共享并发写入存储的多实例部署。可选：

嵌入后端（OpenAI、Ollama、本地）
在存储的对话上进行向量检索（在 PostgreSQL 上使用 pgvector）
记忆巩固（摘要、事实提取）

`zeroclaw-tool-call-parser`

模型侧的工具调用语法解析。处理不同提供商之间的差异：

OpenAI 风格的 tool_calls JSON
Anthropic 风格的 <tool_use> 块
Qwen/Ollama 的函数调用格式
原生工具调用流式增量

`zeroclaw-plugins`

沙箱化 WASM 插件宿主：在进程内通过 WASI 加载组件模型插件（tool、channel、memory、skill bundles），并对每次调用设置 fuel 和内存限制。参见开发 → 插件协议。

`zeroclaw-hardware`

硬件抽象层：GPIO、I2C、SPI、USB。按平台启用。参见 Hardware → Overview。

zeroclaw-log

工作区内每个日志事件的唯一发射入口。负责管理磁盘上的 JSONL schema（LogEvent）、别名绑定的归因注册表（ATTRIBUTION_FIELDS + COMPOSITE_PREFIXES）、用于捕获每次 tracing::* 调用的 tracing-subscriber Layer、record! 和 scope! 宏、滚动裁剪写入器、/api/logs 背后的分页游标读取器，以及面向 Prometheus / OTel 消费者的类型化 Observer 桥接。参见 architecture/logging.md。

`zeroclaw-spawn`

tokio::spawn 的官方封装。提供 spawn! 宏，它会为每个后台任务注入调用方当前的归属 span，使得在生成的 future 内部发出的 record! 能够继承父级的 agent_alias / channel / session_key。调用处应使用 spawn! 而非直接使用 tokio::spawn。

`zeroclaw-infra`

进程级支持：去抖器、看门狗、SQLite 会话后端。不是跟踪/指标层，那是 zeroclaw-log。有关 config、sessions、memory、logs、costs、cron 和 gateway 元数据之间的状态所有权与持久性边界，请参见运行时状态与持久化。

`zeroclaw-macros`

为配置模式、工具注册和通道注册派生宏。减少工作区中的样板代码。

`zerocode`

终端 UI，作为独立应用构建于 apps/zerocode/ 下。它是独立的工作区成员，不依赖任何 zeroclaw-* crate（其独立的 i18n 目录详见文档与翻译 → zerocode 字符串）。

功能标志

微内核路线图（RFC #5574）定义了一个功能标志分类体系。对用户而言，其实际影响是：

default：合理的核心构建
ci-all：全部启用，用于 CI
channel-<name>：按渠道选择启用（例如 channel-matrix、channel-discord）
hardware：启用硬件子系统
gateway、acp-bridge、whatsapp-web：可选启用的功能组

提供程序不受功能门控；它们全部会被编译进来。通道选择是每次构建的主要可调项。请查阅顶层 Cargo.toml 的 [features] 表以获取完整列表。