Data Flow Architecture — ZeroClaw
Data Flow Architecture — ZeroClaw
Tổng quan
ZeroClaw có 5 đường vào (ingress) và 1 vòng lặp trung tâm xử lý mọi thứ:
┌─────────────────── INGRESS ────────────────────────┐
│ │
│ CLI stdin ──────────┐ │
│ Telegram/Discord/.. │ Channel::listen(tx) │
│ WebSocket /ws/chat ─┤──→ mpsc ChannelMessage │
│ HTTP /api/chat ─────┤ │
│ ACP JSON-RPC stdio ─┘ │
│ │
└────────────────────────┬────────────────────────────┘
│
▼
┌──────────── HISTORY MANAGEMENT ─────────────────────┐
│ Per-sender in-memory: ConversationHistoryMap │
│ Key: {channel}_{reply_target}_{sender} │
│ Persistent: SQLite session store (JSONL append) │
│ Max: 50 turns/sender (configurable) │
└────────────────────────┬────────────────────────────┘
│ Vec<ChatMessage>
▼
┌──────── AGENT LOOP: run_tool_call_loop() ───────────┐
│ (loop_.rs:2259, max 10 iterations) │
│ │
│ 1. Context trim (proactive + fast_trim + prune) │
│ 2. LLM compression nếu > 50% context window │
│ 3. Build tool_specs (built-in + MCP + peripherals) │
│ 4. Vision routing nếu có image │
│ 5. ──→ provider.chat() / streaming ──→ LLM │
│ 6. Parse response: │
│ - Native tool_calls (JSON) │
│ - XML (<tool_call>, <invoke>) │
│ - GLM/MiniMax/Markdown fallback │
│ 7. Không có tool call → trả text, DONE │
│ 8. Có tool call: │
│ a. Hook before_tool_call │
│ b. ApprovalManager check │
│ c. Dedup signature check │
│ d. Execute (parallel hoặc sequential) │
│ e. Credential scrubbing on output │
│ f. Push results vào history → tiếp vòng lặp │
└───────┬──────────────────────────┬──────────────────┘
│ │
▼ ▼
┌── PROVIDERS ──┐ ┌──── TOOL EXECUTION ────────────┐
│ Anthropic │ │ SecurityPolicy check │
│ OpenAI │ │ Sandbox wrap (Seatbelt/Docker/ │
│ Gemini │ │ Firejail/Bubblewrap/Landlock) │
│ Ollama │ │ tool.execute(args).await │
│ Bedrock │ │ 80+ built-in tools: │
│ Azure │ │ Shell, FileR/W, Memory, │
│ OpenRouter │ │ Browser, HTTP, WebSearch, │
│ GLM/MiniMax │ │ Delegate, Swarm, Cron, │
│ ... │ │ MCP wrappers, GPIO, ... │
└───────────────┘ └────────────────────────────────┘
│
▼ final text
┌──────────────── RESPONSE DELIVERY ──────────────────┐
│ CLI: stdout (streaming print) │
│ Channel: typing indicator → draft → send() │
│ WebSocket: {"type":"chunk"} → {"type":"done"} │
│ ACP: JSON-RPC notifications │
│ │
│ Post-processing: │
│ strip_tool_call_tags() │
│ hooks.fire_outbound(response, channel) │
└─────────────────────────────────────────────────────┘
Các tầng chính
1. Ingress (5 paths)
┌─────────────────┬────────────────────────────┬────────────────────────────────────────────────────────────────────────┐
│ Path │ Entry point │ Cơ chế │
├─────────────────┼────────────────────────────┼────────────────────────────────────────────────────────────────────────┤
│ CLI interactive │ loop_::run() │ REPL stdin, session state JSON file │
├─────────────────┼────────────────────────────┼────────────────────────────────────────────────────────────────────────┤
│ Channel daemon │ channels::start_channels() │ 20+ platforms (Telegram, Discord, Slack...), mỗi cái listen(tx) → mpsc │
├─────────────────┼────────────────────────────┼────────────────────────────────────────────────────────────────────────┤
│ WebSocket │ gateway/ws.rs │ Axum WS tại /ws/chat, persistent Agent instance │
├─────────────────┼────────────────────────────┼────────────────────────────────────────────────────────────────────────┤
│ HTTP webhook │ gateway/mod.rs │ REST /api/chat, one-shot process_message() │
├─────────────────┼────────────────────────────┼────────────────────────────────────────────────────────────────────────┤
│ ACP │ channels/acp_server.rs │ JSON-RPC 2.0 over stdio cho IDE integration │
└─────────────────┴────────────────────────────┴────────────────────────────────────────────────────────────────────────┘
2. History & Context Management
- In-memory: HashMap<sender_key, Vec<ChatMessage>> — max 50 turns
- Persistent: SQLite session store, JSONL append-only, survives restart
- Trimming pipeline (3 tầng):
- proactive_trim_turns() — budget 400K chars (~100K tokens)
- fast_trim_tool_results() — cắt tool output cũ xuống 2000 chars
- history_pruner::prune_history() — deep cleanup configurable
- LLM compression (context_compressor.rs): khi > 50% context window, gửi summarization prompt đến model rẻ hơn, giữ nguyên identifiers (UUID,
paths, hashes)
- Emergency: overflow → drop 1/3 history cũ nhất
3. Agent Loop (run_tool_call_loop)
- Max 10 iterations (configurable)
- Mỗi iteration: trim → build specs → call LLM → parse → execute tools → loop
- Tool call parsing hỗ trợ nhiều format: native JSON, XML variants, GLM, MiniMax, markdown blocks
- Cost tracking per-loop với budget check
4. Tool Execution Pipeline
tool call → SecurityPolicy.check()
→ ApprovalManager.needs_approval()
→ Sandbox.wrap_command() (cho shell tools)
→ tool.execute(args).await
→ scrub_credentials(output)
→ ToolResult { content, is_error }
- Parallel execution khi approval manager không interactive và không có dependency
- Concurrency: 4 messages/channel, 8-64 in-flight tasks
5. Provider abstraction
Provider trait với chat(ChatRequest) → ChatResponse — supports streaming qua chat_stream(). Factory pattern chọn provider từ config.
Key files
┌─────────────────────┬───────────────────────────────────┬──────┐
│ Module │ File │ Line │
├─────────────────────┼───────────────────────────────────┼──────┤
│ Agent loop │ src/agent/loop_.rs │ 2259 │
├─────────────────────┼───────────────────────────────────┼──────┤
│ Tool trait │ src/tools/traits.rs │ — │
├─────────────────────┼───────────────────────────────────┼──────┤
│ Tool execution │ src/agent/tool_execution.rs │ — │
├─────────────────────┼───────────────────────────────────┼──────┤
│ Channel trait │ src/channels/traits.rs │ — │
├─────────────────────┼───────────────────────────────────┼──────┤
│ Channel dispatcher │ src/channels/mod.rs │ 5006 │
├─────────────────────┼───────────────────────────────────┼──────┤
│ Context compression │ src/agent/context_compressor.rs │ — │
├─────────────────────┼───────────────────────────────────┼──────┤
│ History pruning │ src/agent/history_pruner.rs │ — │
├─────────────────────┼───────────────────────────────────┼──────┤
│ Security/Sandbox │ src/security/mod.rs + seatbelt.rs │ — │
├─────────────────────┼───────────────────────────────────┼──────┤
│ Gateway WS │ src/gateway/ws.rs │ — │
├─────────────────────┼───────────────────────────────────┼──────┤
│ Session store │ src/channels/session_sqlite.rs │ — │
└─────────────────────┴───────────────────────────────────┴──────┘
All rights reserved
