架构概览

ZeroClaw 是一个分层的 Rust 工作区。最上层是代理运行时；其下是可插拔的提供者、通道、工具和内存；支持库负责配置、沙箱化和硬件处理。

高级形状

flowchart TB
    subgraph External["External world"]
        UI["CLI / chat platforms / gateway clients / ACP IDEs"]
        LLM["LLM providers<br/>Anthropic · OpenAI · Ollama · ..."]
        FS["Filesystem · shell · network"]
    end

    subgraph Edges["Edge crates: talk to the outside"]
        CH["zeroclaw-channels<br/>30+ messaging integrations"]
        GW["zeroclaw-gateway<br/>REST · WebSocket · dashboard"]
        PR["zeroclaw-providers<br/>LLM clients · retry · routing"]
        TL["zeroclaw-tools<br/>browser · HTTP · hardware"]
    end

    subgraph Core["Core"]
        RT["zeroclaw-runtime<br/>agent loop · security · SOP · cron · subagents"]
        MEM["zeroclaw-memory<br/>SQLite · embeddings · consolidation"]
        CFG["zeroclaw-config<br/>schema · autonomy · secrets"]
    end

    UI --> CH
    UI --> GW
    CH --> RT
    GW --> RT
    RT --> PR
    RT --> TL
    RT --> MEM
    RT --> CFG
    PR --> LLM
    TL --> FS

范围内的 crate

箱	角色
`zeroclaw-runtime`	Agent 循环、安全策略实施、SOP 引擎、cron 调度器、SubAgents、zerocode 的 RPC 层
`zeroclaw-config`	TOML 模式、密钥加密、自主级别、工作区解析
`zeroclaw-api`	公共特性：`ModelProvider`、`Channel`、`Tool`、`Memory`、`Observer`、`RuntimeAdapter` 和 `Peripheral`。内核 ABI
`zeroclaw-providers`	所有 LLM 客户端实现（Anthropic、OpenAI、Ollama 等），以及基于提示的路由、重试、冷却和跨配置文件回退
`zeroclaw-channels`	30+ 消息集成（Discord、Slack、Telegram、Matrix、电子邮件、语音、…）
`zeroclaw-gateway`	HTTP / WebSocket 网关、Web 仪表板、Webhook 入口
`zeroclaw-tools`	代理调用的可调用工具实现（browser、HTTP、硬件探测）
`zeroclaw-tool-call-parser`	模型侧的工具调用语法解析与规范化
`zeroclaw-memory`	对话记忆、嵌入、向量检索
`zeroclaw-plugins`	沙箱化 WASM 插件宿主（WIT 组件模型）
`zeroclaw-hardware`	硬件抽象层（GPIO、I2C、SPI、USB）
`zeroclaw-infra`	进程级支持：SQLite 会话后端、防抖器、停滞看门狗
zeroclaw-log	单一日志发射层：JSONL 模式、归因、`record!`/`scope!` 宏、`/api/logs` 读取器、`Observer` 桥接
`zeroclaw-spawn`	带属性传递的 `tokio::spawn` 封装（`spawn!` 宏）
`zeroclaw-macros`	为配置和工具注册派生宏
`zerocode`	终端用户界面

微内核路线图（RFC #5574）正在进一步拆分 zeroclaw-runtime：内核层将精简为仅保留 agent 循环和策略强制执行，其余所有内容都将移至 feature 标志之后。

请求生命周期（简短版）

sequenceDiagram
    participant U as User
    participant CH as Channel
    participant RT as Runtime
    participant SEC as Security
    participant PR as Provider
    participant TL as Tool

    U->>CH: message / DM / webhook
    CH->>RT: deliver_message(ctx)
    RT->>PR: chat(messages, tools)
    PR-->>RT: stream: text · tool_call
    RT->>SEC: validate(tool_call)
    SEC-->>RT: approved / blocked
    RT->>TL: invoke(args)
    TL-->>RT: result
    RT->>PR: chat(..., + tool_result)
    PR-->>RT: stream: text (final)
    RT-->>CH: reply (partial / final)
    CH-->>U: message

完整详情：请求生命周期。

核心特性

Trait 合约位于 zeroclaw-api；crates/zeroclaw-api/src/ 中的 trait 定义是内置 provider、channel、tool、memory backend 和 peripheral 的事实来源。对于应当位于核心二进制之外的能力，请先从插件指南开始。下面的要点指向最接近的相关文档。

ModelProvider：对 OpenAI 兼容端点使用 custom 或现有的提供方家族；在添加新的提供方家族、认证模型、能力声明或线协议时，实现此 trait。请参阅 Custom providers。
Channel：为新的消息平台实现。入站和出站是分开的钩子。参见 Channels overview。
Tool：为新的内置 agent 能力实现。请参见 Tools overview。
Memory：为保留 agent/session 作用域的 memory backend 实现。
Peripheral：用于硬件板和设备表面实现。参见 Hardware overview。

其他公开 trait，包括 Observer 和 RuntimeAdapter，都是更底层的约定。请在修改它们之前先查看架构图和RFC 流程。

新的实现应保持在 zeroclaw-api trait 合约之后，并通过该表面的所属工厂、注册表或功能开关接入。RFC #5574 继续缩减运行时实现依赖，因此除非设计需要，否则应避免添加新的具体运行时依赖。

接下来阅读

Crates：逐个 crate 深入解析
请求生命周期：流式传输、工具调用、审批
模型提供商 → 概述
安全 → 概述