ZeroClaw: Hướng Dẫn Tự Xây Dựng AI Agent Đa Nền Tảng, Bảo Mật Tối Ưu

Mục lục

Khám Phá ZeroClaw: Nền Tảng AI Agent Bạn Có Thể Sở Hữu Hoàn Toàn

Trong kỷ nguyên bùng nổ của trí tuệ nhân tạo, nhu cầu về các AI agent tự động hóa, linh hoạt và đặc biệt là tự quản lý (self-hosted) đang trở nên cấp thiết hơn bao giờ hết. ZeroClaw ra đời với sứ mệnh cung cấp một khuôn mẫu toàn diện, từ A đến Z, cho việc kiến tạo các hệ thống AI agent của riêng bạn. Bài viết này sẽ đi sâu vào cách ZeroClaw được thiết kế và vận hành, đóng vai trò như một bản thiết kế chi tiết để bạn có thể xây dựng một runtime AI agent đa kênh, đa nhà cung cấp, hoạt động hoàn toàn trên máy chủ của mình.

Chúng ta sẽ cùng khám phá triết lý cốt lõi, kiến trúc tinh vi, các lớp trừu tượng quan trọng, mô hình bảo mật đa tầng, vòng lặp hoạt động của agent, công cụ quản lý quy trình (SOP engine), lớp bộ nhớ, các vấn đề vận hành, và kỷ luật xây dựng/quản trị đã tạo nên một ZeroClaw vững chắc.

Kho lưu trữ mã nguồn của ZeroClaw được viết bằng Rust, tuân thủ giấy phép kép MIT OR Apache-2.0 và sử dụng Rust 2024 edition: https://github.com/zeroclaw-labs/zeroclaw.

ZeroClaw Là Gì? Định Nghĩa Tóm Lược Về Một Nền Tảng AI Đột Phá

ZeroClaw đơn giản là một binary Rust duy nhất mà bạn cấu hình và chạy. Nó có khả năng kết nối với khoảng 20 nhà cung cấp mô hình ngôn ngữ lớn (LLM) như Anthropic, OpenAI, Ollama, Gemini, Bedrock, OpenRouter và bất kỳ endpoint tương thích OpenAI nào khác. Đồng thời, ZeroClaw có thể tiếp cận thế giới qua hơn 30 kênh nhắn tin khác nhau (Discord, Telegram, Matrix, email, thoại, webhooks, CLI) và thực hiện các hành động thông qua các công cụ (shell, trình duyệt, HTTP, GPIO phần cứng, máy chủ MCP tùy chỉnh). Toàn bộ hệ thống chạy trên máy của người dùng, sử dụng khóa của họ và trong không gian làm việc của họ. Không có SaaS, không có telemetry, không có máy chủ cấp phép.

Khẩu hiệu cốt lõi – “Bạn sở hữu agent. Bạn sở hữu dữ liệu. Bạn sở hữu cỗ máy nó chạy trên.” – là kim chỉ nam cho mọi quyết định thiết kế của ZeroClaw, đảm bảo quyền kiểm soát tối đa cho người dùng.

Triết Lý Thiết Kế Cốt Lõi Của ZeroClaw: Bốn Nguyên Tắc Bất Di Bất Dịch

Trước khi viết bất kỳ dòng mã nào, điều quan trọng là phải thấm nhuần bốn nguyên tắc thiết kế ưu tiên này. Chúng định hình toàn bộ triết lý của dự án và là nền tảng cho sự thành công của một AI agent tự quản lý:

  1. Bạn là chủ sở hữu. Triết lý ưu tiên cục bộ (local-first). Binary trên máy của bạn, khóa trong cấu hình của bạn, lịch sử trong cơ sở dữ liệu của bạn. Rút dây nguồn, nó dừng lại sạch sẽ. Không phụ thuộc vào dịch vụ đám mây bên thứ ba, đảm bảo quyền riêng tư và kiểm soát hoàn toàn.
  2. Bảo mật là trên hết, với các lối thoát an toàn. Mức độ tự chủ mặc định là Supervised (yêu cầu rủi ro trung bình được xử lý, rủi ro cao bị chặn). Sandbox, chính sách lệnh, ranh giới không gian làm việc và biên lai công cụ mã hóa đều được bật theo mặc định. Một cài đặt sẵn tên là YOLO (You Only Live Once), được đặt tên rõ ràng, cho phép người dùng phát triển tùy chọn bỏ qua các hạn chế này một cách có ý thức.
  3. Tối giản – về kích thước binary, số lượng phụ thuộc và bề mặt tấn công. Kiến trúc microkernel với các cờ tính năng (feature flags) để người dùng chỉ phải cài đặt những gì họ sử dụng. Mô tả công cụ ngắn gọn, được bản địa hóa; không có các lời nhắc cá nhân ẩn, giữ cho hệ thống tinh gọn và hiệu quả.
  4. Không phụ thuộc vào nhà cung cấp. “Bộ não” của AI agent có thể cắm và chạy được (pluggable). Việc chuyển đổi nhà cung cấp LLM chỉ là một thay đổi cấu hình một dòng. Chuỗi dự phòng (fallback chains) giúp hệ thống hoạt động ổn định khi một nhà cung cấp gặp sự cố hoặc ngừng hoạt động.

🚫 Nếu thiết kế của bạn xung đột với một trong những nguyên tắc này, thiết kế đó sẽ bị loại bỏ. Hãy ghi chúng vào đầu tài liệu PHILOSOPHY.md của bạn trước bất kỳ điều gì khác để luôn giữ vững định hướng.

Kiến Trúc Tổng Thể Của ZeroClaw: Một Bức Tranh Toàn Cảnh Về Hệ Thống AI Microkernel

Với kiến trúc hướng trait (trait-driven), phân lớp (layered) và hình dạng microkernel, ZeroClaw được tổ chức rõ ràng để tối đa hóa tính mô đun và khả năng mở rộng:


┌──────────────────────────────────────────────────────────────┐
│            channels       gateway        ACP                 │
│          (30+ adapters)   (REST/WS)    (JSON-RPC)            │
│                        ↓                                     │
│                   ZeroClaw runtime                           │
│         ┌──────────┬──────────┬──────────┐                   │
│         │  agent   │ security │   SOP    │                   │
│         │   loop   │  policy  │  engine  │                   │
│         └──────────┴──────────┴──────────┘                   │
│              ↓          ↓           ↓                        │
│          providers    tools      memory                      │
│         (Anthropic,  (shell,    (SQLite,                     │
│          OpenAI,     browser,    embeddings)                 │
│          Ollama,     HTTP,                                   │
│          ~20 more)   hardware)                               │
└──────────────────────────────────────────────────────────────┘

Kiến trúc này bao gồm ba lớp cấu trúc chính:

  1. Lớp Edge: Các crates như zeroclaw-channels, zeroclaw-providers, zeroclaw-gateway, zeroclaw-tools. Nhiệm vụ của lớp này là giao tiếp với thế giới bên ngoài (LLM, nền tảng chat, HTTP, hệ thống tệp, thiết bị).
  2. Lớp Core: Bao gồm zeroclaw-runtime, zeroclaw-config, zeroclaw-api. Đây là trái tim của hệ thống, xử lý vòng lặp agent, chính sách, schema và giao diện ABI của kernel.
  3. Lớp Support: Các crates như zeroclaw-memory, zeroclaw-infra, zeroclaw-macros, zeroclaw-tool-call-parser, zeroclaw-plugins, zeroclaw-hardware, zeroclaw-tui. Cung cấp các tiện ích dùng chung (tracing, macro derive, parsing, plugin, HAL phần cứng).

Quy tắc Kernel

Quy tắc quan trọng nhất là zeroclaw-runtime chỉ phụ thuộc vào crate trait zeroclaw-api, chứ không bao giờ phụ thuộc vào các crate nhà cung cấp/kênh/công cụ cụ thể. Mọi thứ được kết nối thông qua các hàm factory khi khởi động. Điều này có nghĩa là bạn có thể loại bỏ hỗ trợ Discord mà không cần biên dịch lại vòng lặp agent, mang lại sự linh hoạt và hiệu quả tối đa.

Năm Trait Cốt Lõi: Định Hình Toàn Bộ ABI Của ZeroClaw và Khả Năng Mở Rộng

Thư mục crates/zeroclaw-api/src/ định nghĩa toàn bộ bề mặt mở rộng của ZeroClaw. Mọi crate khác đều phụ thuộc vào crate này. Không có triển khai nào tồn tại ở đây, chỉ có các trait và kiểu dữ liệu dùng chung. Đây là yếu tố giúp kernel nhỏ gọn, dễ kiểm thử và cực kỳ linh hoạt.

4.1 Provider — Backend LLM Đa Dạng

Trait Provider định nghĩa giao diện để ZeroClaw tương tác với các mô hình ngôn ngữ lớn (LLM) từ nhiều nhà cung cấp khác nhau:


#[async_trait]
pub trait Provider: Send + Sync {
    fn name(&self) -> &str;
    async fn chat(&self, req: ChatRequest<'_>) -> Result<ChatResponse>;
    async fn stream(&self, req: ChatRequest<'_>) -> Result<BoxStream<'_, StreamEvent>>;
    fn supports_tool_calls(&self) -> bool;
    fn supports_streaming(&self) -> bool;
    // ... capability flags for thinking, multimodal, JSON mode, etc.
}

Các kiểu hỗ trợ chính bao gồm: ChatMessage, ToolCall, ToolResultMessage, ConversationMessage, ChatResponse, TokenUsage và StreamEvent (một luồng các sự kiện như TextDelta, Thinking, ToolCallDelta, Done). Điều này cho phép ZeroClaw tích hợp mượt mà với nhiều LLM, từ các mô hình trò chuyện thông thường đến các mô hình đa phương thức phức tạp.

4.2 Channel — Nền tảng Nhắn Tin Đa Kênh

Trait Channel cho phép ZeroClaw giao tiếp với các nền tảng nhắn tin khác nhau, mang lại khả năng tiếp cận người dùng trên mọi môi trường:


#[async_trait]
pub trait Channel: Send + Sync {
    fn name(&self) -> &str;
    async fn send(&self, msg: SendMessage) -> Result<()>;
    async fn poll(&self) -> Result<Vec<ChannelMessage>>;       // for pull-based
    async fn run(&self, tx: mpsc::Sender<ChannelMessage>) -> Result<()>;  // for push-based
    fn supports_draft_updates(&self) -> bool;
    async fn ask_approval(&self, req: ChannelApprovalRequest) -> Result<ChannelApprovalResponse>;
}

Quy trình phê duyệt được xử lý ở cấp độ kênh, thích ứng với giao diện người dùng cụ thể: Telegram sử dụng các nút bàn phím nội tuyến, Slack sử dụng Block Kit, Discord/Signal/WhatsApp nhúng một token ngắn vào lời nhắc và đợi phản hồi <token> approve|deny|always. Trait Channel là lớp trừu tượng giúp việc chuyển đổi này minh bạch đối với runtime, đảm bảo trải nghiệm người dùng liền mạch.

4.3 Tool — Khả năng Gọi Từ Agent

Trait Tool định nghĩa cách các agent có thể thực hiện các khả năng khác nhau, biến AI agent thành một công cụ mạnh mẽ có thể tương tác với thế giới thực:


#[async_trait]
pub trait Tool: Send + Sync {
    fn name(&self) -> &str;
    fn description(&self) -> &str;
    fn parameters_schema(&self) -> serde_json::Value;
    async fn execute(&self, args: serde_json::Value) -> Result<ToolResult>;
    fn spec(&self) -> ToolSpec { /* default impl */ }
}

ToolResult { success: bool, output: String, error: Option<String> } — đây là toàn bộ hợp đồng. Mọi thứ từ shell, web_fetch, pdf_read, git_operations, mcp_tool đến gpio_write đều được trừu tượng hóa thành một Tool, cho phép agent thực hiện các tác vụ phức tạp.

4.4 Memory — Lưu Trữ Hội Thoại và Thông Tin Bền Vững

Trait Memory quản lý việc lưu trữ, truy vấn và quản lý dữ liệu hội thoại và thông tin, đảm bảo tính bền vững và tuân thủ các quy định như GDPR:


#[async_trait]
pub trait Memory: Send + Sync {
    fn name(&self) -> &str;
    async fn store(&self, key: &str, content: &str, category: MemoryCategory, ...) -> Result<()>;
    async fn search(&self, query: &str, ...) -> Result<Vec<MemoryEntry>>;
    async fn export(&self, filter: ExportFilter) -> Result<Vec<MemoryEntry>>;  // GDPR data portability
    // ...
}

MemoryCategory có thể là Core | Daily | Conversation | Custom(String). Các mục nhập mang theo namespace, importance, superseded_by để hỗ trợ cách ly đa agent, truy xuất ưu tiên và giải quyết xung đột, tạo nên một hệ thống quản lý bộ nhớ linh hoạt và mạnh mẽ.

4.5 RuntimeAdapter và Peripheral — Môi trường Thực Thi và Phần Cứng Kết Nối

RuntimeAdapter cho phép bạn đưa agent đến một môi trường thực thi mới (native, Docker, Cloudflare Workers, nhúng). Nó khai báo các cờ khả năng (has_shell_access, has_filesystem_access, supports_long_running, memory_budget) cùng với một hook hành vi duy nhất build_shell_command. Vòng lặp agent sẽ truy vấn các cờ này và vô hiệu hóa các công cụ mà runtime không thể thực hiện, đảm bảo tính an toàn và tương thích.

Peripheral cho phép một bo mạch phần cứng (STM32 qua serial, RPi GPIO qua gpiod) phơi bày các khả năng của nó dưới dạng Tool. Nó có vòng đời kết nối → sử dụng → ngắt kết nối, với một probe health_check, mở ra khả năng tương tác của AI agent với thế giới vật lý.

Vòng Lặp Agent: Từ Tin Nhắn Người Dùng Đến Phản Hồi Của AI — Một Quy Trình Chi Tiết

File crates/zeroclaw-runtime/src/agent/loop_.rs chứa khoảng 7.500 dòng mã, minh chứng cho sự phức tạp của một vòng lặp agent có khả năng xử lý thông minh. Về mặt khái niệm, nó hoạt động như sau:

  1. Bộ điều hợp kênh nhận một sự kiện gốc từ nền tảng:
    • Giải mã thành định dạng chuẩn chung.
    • Loại bỏ trùng lặp (bỏ qua các lần thử lại/khởi động lại để tránh xử lý kép).
    • Kiểm tra cặp (người dùng được phép, cuộc trò chuyện được phép, danh sách IP cho phép để đảm bảo quyền truy cập).
  2. Runtime: deliver_message(envelope):
    • Tải lịch sử cuộc trò chuyện + các sự kiện bộ nhớ đã truy xuất để cung cấp ngữ cảnh.
    • Áp dụng bộ lọc công cụ (tích hợp sẵn luôn có; MCP bị giới hạn bởi tool_filter_groups để kiểm soát quyền sử dụng).
    • Tổng hợp lời nhắc hệ thống + lịch sử + thông số kỹ thuật công cụ để gửi đến LLM.
  3. Provider: chat(stream=true):
    • Truyền các đoạn TextDelta → chuyển tiếp đến kênh dưới dạng bản nháp cập nhật (nếu được hỗ trợ để cung cấp phản hồi tức thì).
    • Truyền các đoạn Thinking → không gửi lại cho mô hình, chỉ gửi đến giao diện người dùng để hiển thị trạng thái suy nghĩ của agent.
    • Truyền ToolCall khi mô hình quyết định sử dụng một công cụ.
  4. SecurityPolicy.validate_tool_call(name, args, risk):
    • Được phép → chạy công cụ.
    • Bị chặn → trả về ToolResult::Err cho mô hình, mô hình có thể phản ứng và điều chỉnh hành vi.
    • Yêu cầu phê duyệt → channel.ask_approval(prompt) để xin phép người dùng:
      • Telegram: sử dụng các nút bàn phím nội tuyến.
      • Slack: sử dụng Block Kit.
      • Discord/WhatsApp: phản hồi token.
      • CLI: lời nhắc nội tuyến.
      • ACP: gửi sự kiện session/update kind="approval_request".
  5. Tool.execute(args):
    • Chạy bên trong sandbox cấp độ hệ điều hành (Landlock / Bubblewrap / Seatbelt / Docker) để đảm bảo an toàn.
    • Tính toán biên lai = HMAC-SHA256(session_key, name||args||result||ts) để tạo nhật ký kiểm toán.
    • Nối token biên lai vào văn bản kết quả.
  6. Provider: chat(history + tool_result) → luồng TextDelta cuối cùng. Mô hình tiếp tục hội thoại với kết quả từ công cụ.
  7. Channel: send(final reply, threaded if applicable). Gửi phản hồi cuối cùng đến người dùng.
  8. Memory: lưu trữ cuộc trò chuyện + các lệnh gọi công cụ + biên lai. Cập nhật trạng thái bộ nhớ để duy trì ngữ cảnh và lịch sử.

Các Tính Chất Quan Trọng Cần Tham Khảo:

  • Streaming end-to-end: Không đệm toàn bộ phản hồi LLM. Các kênh hỗ trợ supports_draft_updates() sẽ nhận các chỉnh sửa tăng dần vào một tin nhắn đã gửi; các kênh khác sẽ gửi toàn bộ khi luồng kết thúc, tối ưu hóa trải nghiệm người dùng.
  • Lệnh gọi công cụ giữa luồng: Mô hình có thể phát ra một ToolCall trong khi vẫn đang tạo văn bản. Hệ thống sẽ tạm dừng luồng, xác thực, gọi công cụ, sau đó tiếp tục, cho phép tương tác linh hoạt.
  • Giới hạn lặp: ZeroClaw giới hạn số lần lặp công cụ cho mỗi tin nhắn người dùng ở DEFAULT_MAX_TOOL_ITERATIONS = 10 để ngăn chặn các vòng lặp mất kiểm soát và tiêu tốn tài nguyên không cần thiết. Luôn luôn phải có một giới hạn như vậy.
  • Ngân sách chi phí: Một ToolLoopCostTrackingContext được truyền qua (thông qua tokio::task_local!) để ngân sách cho mỗi phiên có thể kết thúc vòng lặp sớm, kiểm soát chi phí LLM.
  • Token hủy ở mọi nơi: tokio_util::sync::CancellationToken nằm trên SendMessage và được truyền qua quá trình thực thi công cụ để bạn có thể ngắt giữa chừng mà không để lại các tiến trình “zombie”, đảm bảo khả năng phản hồi.
  • Task-locals cho trạng thái dùng chung: TOOL_LOOP_THREAD_ID, TOOL_LOOP_SESSION_KEY, TOOL_CHOICE_OVERRIDE là các tokio::task_local! được đặt bởi vòng lặp agent, được đọc bởi các công cụ và nhà cung cấp mà không làm ô nhiễm các chữ ký hàm, giữ cho mã sạch và dễ quản lý.

Mô Hình Bảo Mật Sáu Lớp Của ZeroClaw: An Toàn Tuyệt Đối Cho AI Agent Của Bạn

Đây là phần quan trọng nhất cần được thực hiện đúng. ZeroClaw kết hợp sáu lớp độc lập, từ ngoài vào trong – mỗi lớp đều đủ mạnh để tự bảo vệ; cùng nhau, chúng tạo nên một hệ thống phòng thủ đa tầng (defense-in-depth) vững chắc, bảo vệ agent AI khỏi các mối đe dọa đa dạng.

6.1 Lớp 1: Ghép nối Kênh & Kiểm soát Truy cập

Lớp bảo mật đầu tiên được thực hiện ở bộ điều hợp kênh, trước khi runtime tiếp nhận sự kiện:


allowed_users, allowed_chats, IP allowlists cho webhooks, ghép nối thiết bị.

Các cơ chế này đảm bảo chỉ những người dùng, kênh và thiết bị được ủy quyền mới có thể tương tác với agent.

6.2 Lớp 2: Mức độ Tự chủ (Nút điều chỉnh thô)

Mức độ tự chủ của agent được cấu hình thông qua:


[autonomy]
level = "supervised"   # "read_only" | "supervised" | "full"
  • read_only — chỉ quan sát. Agent chỉ có thể thực hiện các hành động đọc như file_read, memory_search, http GET, web_search. Lý tưởng cho các agent hỏi đáp công khai.
  • supervised (mặc định) — các tác vụ rủi ro thấp được chạy tự động, các yêu cầu rủi ro trung bình cần phê duyệt, và các tác vụ rủi ro cao bị chặn. Yêu cầu phê duyệt hết thời gian sau 300s sẽ được coi là từ chối.
  • full — không có cổng phê duyệt, nhưng không gian làm việc, sandbox và chính sách lệnh vẫn được thực thi. Dành cho môi trường phát triển (dev/CI) hoặc các quy trình vận hành tiêu chuẩn (SOPs) đã được kiểm soát.

Ghi đè từng công cụ cung cấp kiểm soát chi tiết hơn:


[autonomy.auto_approve]   tools = ["browser_open", "http"]   # luôn chấp thuận
[autonomy.always_ask]     tools = ["file_write", "shell"]    # luôn hỏi
[autonomy.never_allow]    tools = ["browser_automation"]     # luôn chặn

Các ghi đè từng kênh cho phép tùy chỉnh chính sách tự chủ cho các nền tảng khác nhau, ví dụ, một kênh Bluesky công khai có thể chạy ở chế độ read_only trong khi một CLI riêng tư chạy ở chế độ supervised.

6.3 Lớp 3: Ranh giới Không gian làm việc & Quy tắc Đường dẫn

Giới hạn agent trong một không gian làm việc được xác định và ngăn chặn truy cập vào các đường dẫn nhạy cảm:


[autonomy]
workspace_only  = true
forbidden_paths = ["/etc", "/sys", "/boot", "~/.ssh", "~/.aws"]

forbidden_paths luôn chặn truy cập bất kể cài đặt workspace_only. Việc giải quyết symlink diễn ra trước khi thực thi chính sách, ngăn chặn các cuộc tấn công vượt qua ranh giới.

6.4 Lớp 4: Chính sách Lệnh Shell

Kiểm soát chặt chẽ các lệnh shell mà agent có thể thực thi:


[autonomy]
allowed_commands   = ["git", "cargo", "grep", "find", "ls", "cat"]
forbidden_commands = ["shutdown", "reboot", "mkfs"]

Một bộ xác thực khớp mẫu chạy trước khi lệnh đến shell — tìm kiếm các cờ nguy hiểm, pipeline, hình dạng đối số (rm -rf /, :(){ :|: & };:, v.v.). Các lệnh bị chặn sẽ được trả về dưới dạng lỗi công cụ để mô hình có thể phản ứng, tránh thực thi các lệnh nguy hiểm.

6.5 Lớp 5: Sandbox cấp độ Hệ điều hành (Cơ chế, không phải Chính sách)

ZeroClaw tự động phát hiện và áp dụng cơ chế sandbox cấp độ hệ điều hành để cô lập các tiến trình của agent. Đây là một cơ chế kỹ thuật chứ không phải chính sách người dùng:

Nền tảng Thứ tự ưu tiên
Linux Landlock (kernel 5.13+) → Bubblewrap → Firejail → Docker → none
macOS Seatbelt (native) → Docker → none
Windows AppContainer (thử nghiệm) → Docker → none

Sandbox giới hạn hệ thống tệp (không gian làm việc + /usr + /lib chỉ đọc + các mục bổ sung rõ ràng), mạng (tùy chọn danh sách cho phép tên miền), môi trường (chỉ shell_env_passthrough được truyền qua; các mẫu *_TOKEN/*_SECRET/*_PASSWORD không bao giờ được truyền), và giới hạn tiến trình (CPU/bộ nhớ/tiến trình con/thời gian thực thi), tạo ra một môi trường thực thi an toàn và bị cô lập.

6.6 Lớp 6: Biên lai Công cụ (Nhật ký kiểm toán mã hóa)

Đây là phần độc đáo và quan trọng nhất về mặt trách nhiệm giải trình. Mỗi lần gọi công cụ sẽ tạo ra một bản tóm tắt HMAC-SHA256:


receipt = HMAC-SHA256(ephemeral_session_key, tool_name || args || result || timestamp)
appended as: [receipt: zc-receipt-<timestamp>-<base64url-digest>]

Mô hình thấy các biên lai trong ngữ cảnh của nó nhưng không thể giả mạo chúng — nó không có khóa. Điều này giúp loại bỏ kẽ hở phủ nhận: mô hình không thể tuyên bố đã chạy một công cụ mà nó không chạy, và không thể tạo ra kết quả công cụ giả mạo. Các biên lai được liên kết (mỗi cái bao gồm hash của cái trước), do đó việc giả mạo sẽ làm mất hiệu lực của phần còn lại của nhật ký. Chi phí: <1 ms cho mỗi cuộc gọi, không có phụ thuộc bên ngoài mới.

Tham khảo bài báo: Basu, A. (2026). “Tool Receipts, Not Zero-Knowledge Proofs.” Quan điểm là bạn không cần chứng minh ZK (Zero-Knowledge) cho một agent nội tiến trình — một MAC đối xứng với khóa tạm thời cho mỗi phiên là đủ để đảm bảo tính toàn vẹn và trách nhiệm giải trình.

Các Cổng Bảo Mật Bổ Sung (Nên Tham Khảo):

  • Cổng OTP (Mật khẩu dùng một lần) — [security.otp] gated_actions = ["shell", "browser"] yêu cầu một mã TOTP trước mỗi hành động được liệt kê. Hữu ích cho quản trị từ xa, tăng cường lớp xác thực.
  • Dừng khẩn cấp — Lệnh zeroclaw estop dừng tất cả các công cụ đang chạy. Để tiếp tục, cần OTP nếu [security.estop] enabled = true, cung cấp cơ chế kiểm soát nhanh chóng trong trường hợp khẩn cấp.
  • Bảo vệ chống inject prompt — Quét đầu ra của mô hình để tìm các mẫu inject đã biết trước khi xác thực, ngăn chặn các cuộc tấn công qua prompt.
  • Bộ phát hiện rò rỉ — Quét các tin nhắn đi để tìm các token giống bí mật (API keys, private keys) và chặn chúng. Bộ phát hiện được cấu hình để cho phép các token zc-receipt-* đi qua, cân bằng giữa bảo mật và tính năng.
  • Bảo vệ ghép nối — Ghép nối thiết bị để xác thực kênh; ngăn chặn việc sử dụng thông tin đăng nhập bị đánh cắp trên một thiết bị mới, tăng cường bảo mật truy cập.

Câu Hỏi “Vậy Còn Các Lệnh Gọi Bị Chặn Thì Sao?”

Một lệnh gọi bị chặn không phải là im lặng. Bộ xác thực trả về một lỗi → runtime gói nó dưới dạng ToolResult::Err → mô hình thấy Error: Shell command blocked by policy: forbidden pattern 'rm -rf /' và có thể xin lỗi/thử lại/leo thang. Nếu một kênh giới hạn bộ công cụ (tools_allow = [...]), công cụ đó đơn giản là không được quảng cáo cho mô hình ngay từ đầu — nó không bao giờ thấy một công cụ mà nó không thể gọi, đảm bảo rằng agent chỉ tương tác với các công cụ an toàn và được phép.

Chiến Lược Nhà Cung Cấp: Hỗ Trợ Hơn 20 LLM Mà Không Gây Nổ Hệ Thống

Hãy xem xét crates/zeroclaw-providers/src/ để hiểu bí quyết ZeroClaw hỗ trợ đa dạng các mô hình ngôn ngữ lớn (LLM) một cách hiệu quả:


anthropic.rs         openai.rs         ollama.rs
gemini.rs            bedrock.rs        azure_openai.rs
copilot.rs           glm.rs            kilocli.rs
                  ↓
        compatible.rs  ← triển khai tương thích OpenAI duy nhất
                  ↓
   Groq, Mistral, xAI, DeepSeek, Together, Fireworks,
   Perplexity, Cohere, Moonshot, Venice, OpenRouter, ...

Một bộ điều hợp compatible.rs triển khai schema OpenAI Chat Completions và được tái sử dụng cho khoảng 20 nhà cung cấp — điều này có nghĩa là hầu hết các “nhà cung cấp mới” chỉ là một mục cấu hình, không phải một tệp mã mới. Chỉ các nhà cung cấp có giao thức thực sự khác biệt (như Anthropic Messages API, Gemini, Bedrock SigV4) mới cần tệp riêng.

Các wrapper trên các nhà cung cấp giúp tăng cường khả năng hoạt động:

  • router.rs — bộ định tuyến đa nhà cung cấp định tuyến theo gợi ý tác vụ (ví dụ: reasoning → DeepSeek-R1, chat → Sonnet, vision → Gemini), tối ưu hóa việc sử dụng LLM.
  • reliable.rs — wrapper chuỗi dự phòng (fallback chain). Các yếu tố kích hoạt chuyển đổi dự phòng: HTTP 5xx, giới hạn tốc độ, hết thời gian, lỗi xác thực schema, đảm bảo tính bền vững của dịch vụ.
  • schema.rs — trình làm sạch JSON-schema chuẩn hóa schema công cụ cho mỗi nhà cung cấp. Gemini từ chối minLength, pattern, $ref, additionalProperties; Anthropic không giải quyết $ref; OpenAI là linh hoạt nhất. Trình làm sạch có các chiến lược được đặt tên (Gemini, Anthropic, OpenAI, Conservative) và mang lại khả năng di động công cụ giữa các nhà cung cấp miễn phí.
  • Trình phân tích lệnh gọi công cụ (zeroclaw-tool-call-parser) — chuẩn hóa phía mô hình. JSON tool_calls kiểu OpenAI, các khối <tool_use> của Anthropic, XML của Qwen, định dạng gọi hàm của Ollama — tất cả đều được phân tích thành một định dạng ParsedToolCall duy nhất. Hỗ trợ mẫu trait dispatcher (XmlToolDispatcher, JsonToolDispatcher) loại bỏ các khối lý luận <think>...</think> trước khi phân tích.

Bảo Toàn Lý Luận

Một số nhà cung cấp (DeepSeek-R1, GLM-4.7, Kimi K2.5) từ chối lịch sử lệnh gọi công cụ mà bỏ qua trường reasoning_content. ZeroClaw lưu trữ nó dưới dạng pass-through không rõ ràng trên ChatResponse và ConversationMessage::AssistantToolCalls — bạn không giải mã nó, bạn chỉ round-trip nó, đảm bảo tính toàn vẹn của quá trình suy luận của mô hình.

Bộ Nhớ Của ZeroClaw: Bền Vững, Có Thể Truy Vấn, Tuân Thủ GDPR

Thư mục crates/zeroclaw-memory/ chứa các thành phần quản lý bộ nhớ, được thiết kế để cung cấp khả năng lưu trữ bền vững, truy vấn mạnh mẽ và tuân thủ các quy định về bảo vệ dữ liệu:

  • Backend mặc định: SQLite. Tệp đơn, nhúng, không cần vận hành, lý tưởng cho các triển khai cục bộ và nhỏ.
  • Tùy chọn: PostgreSQL đằng sau cờ tính năng --features memory-postgres cho các triển khai đa phiên bản cần ghi đồng thời chia sẻ (với pgvector cho tìm kiếm vector), phù hợp với các hệ thống lớn hơn.
  • Embeddings có thể cắm và chạy (OpenAI, Ollama local, v.v.), cho phép tìm kiếm ngữ nghĩa hiệu quả.
  • Thể loại (Categories): Core (thông tin/ưu tiên dài hạn), Daily (nhật ký phiên), Conversation (lịch sử thô), Custom(name) cho các nhóm dữ liệu do người dùng định nghĩa, giúp tổ chức bộ nhớ.
  • Hợp nhất bộ nhớ chạy theo lịch trình — tóm tắt các cuộc hội thoại dài, trích xuất sự kiện, đánh dấu các mục đã được thay thế, giữ cho bộ nhớ gọn gàng và hiệu quả.
  • Xuất dữ liệu theo GDPR Art. 20 được tích hợp vào trait thông qua ExportFilter. Namespace, phiên, thể loại, phạm vi thời gian — tất cả đều có thể lọc được, đảm bảo quyền riêng tư và khả năng di động dữ liệu.

Lớp bộ nhớ là nơi bạn triển khai cách ly theo namespace để các triển khai đa agent, đa người dùng không làm ô nhiễm lẫn nhau, tăng cường bảo mật và tính tổ chức.

SOP Engine: Tự Động Hóa Không Chỉ Đơn Thuần Là Chat

Các quy trình vận hành tiêu chuẩn (Standard Operating Procedures – SOP) là trái tim của khả năng tự động hóa nâng cao trong ZeroClaw, nằm trong crates/zeroclaw-runtime/src/sop/. Sự đóng góp của mô hình được nới lỏng nhưng có giới hạn, cho phép sự kết hợp giữa linh hoạt và kiểm soát:

  • Nguồn kích hoạt: cron, MQTT, webhook, sự kiện từ thiết bị ngoại vi, hoặc kích hoạt thủ công.
  • Chế độ thực thi:
    • Auto — chạy tất cả các bước tự động, không cần can thiệp con người.
    • Supervised (mặc định) — cần phê duyệt trước khi bắt đầu thực hiện SOP.
    • StepByStep — cần phê duyệt trước mỗi bước, cung cấp kiểm soát granular.
    • PriorityBased — SOP Critical/High sẽ chạy Auto, trong khi Normal/Low sẽ chạy Supervised, tối ưu hóa quy trình dựa trên mức độ quan trọng.
    • Deterministic — tuần tự, không có vòng lặp LLM (no LLM round-trips), đầu ra của bước trước được truyền làm đầu vào cho bước tiếp theo (với tùy chọn phê duyệt checkpoint). Đây là tính năng “sát thủ”: khi mô hình đã tìm ra một quy trình làm việc hiệu quả, bạn có thể phát lại nó một cách xác định và tiết kiệm 100% chi phí LLM.
  • Đồng thời: giới hạn đồng thời cho mỗi SOP + thời gian chờ (cooldown) để quản lý tải hệ thống.
  • Khả năng tiếp tục: các lần chạy SOP có độ bền; hệ thống có thể khởi động lại và tiếp tục từ nơi đã dừng, đảm bảo tính toàn vẹn của quy trình.

Nếu bạn xây dựng một hệ thống tương tự, hãy thiết kế kiểu SOP sao cho cùng một định nghĩa có thể chạy ở bất kỳ chế độ nào — đó là cách chế độ Deterministic “nâng cấp” các quy trình làm việc từ LLM-driven sang cơ khí, hiệu quả và đáng tin cậy.

Kênh: Một Bộ Điều Phối Mạnh Mẽ, Hơn 30 Bộ Điều Hợp Linh Hoạt

Thư mục crates/zeroclaw-channels/src/orchestrator/ là phần đáng đọc nhất, nơi bộ điều phối mạnh mẽ xử lý các thách thức của việc tích hợp đa kênh. Bản thân các bộ điều hợp (Discord, Telegram, Matrix, Slack, Signal, IRC, Bluesky, Nostr, WhatsApp, WeChat, Lark, DingTalk, LINE, IMessage, Email, Voice…) chủ yếu là phần kết nối nền tảng cơ học. Bộ điều phối xử lý các vấn đề dùng chung mà mọi kênh đều cần:

  • Loại bỏ trùng lặp đầu vào — ngăn chặn cùng một tin nhắn đến hai lần do thử lại, đảm bảo xử lý duy nhất.
  • Cập nhật bản nháp — hỗ trợ chỉnh sửa tin nhắn đã gửi duy nhất khi LLM đang stream, cải thiện trải nghiệm người dùng với phản hồi động.
  • Chia tin nhắn đa phần — chia các phản hồi dài thành nhiều tin nhắn tuần tự, phù hợp với giới hạn ký tự của từng kênh.
  • Luồng (Threading) — quản lý thread_ts (Slack) / ID luồng (Discord); interruption_scope_id (khác với thread_ts!) để nhóm hủy, duy trì cấu trúc hội thoại.
  • Đường ống xử lý phương tiện — các MediaAttachment trên ChannelMessage chảy vào quá trình chuyển ngữ (âm thanh) / thị giác (hình ảnh) / trích xuất (PDF) trước khi tin nhắn đến vòng lặp agent, mở rộng khả năng hiểu biết của AI.
  • Định tuyến phê duyệt — cung cấp trải nghiệm người dùng phù hợp với kênh (nút bấm so với trả lời token so với ACP RPC), giúp quy trình phê duyệt trực quan hơn.
  • Làm giàu liên kết — tự động lấy siêu dữ liệu OpenGraph cho các URL trong tin nhắn đến, cung cấp ngữ cảnh phong phú hơn.

Hãy xây dựng bộ điều phối trước, sau đó thêm các kênh. Đó là phần sẽ mang lại giá trị lớn cho mỗi bộ điều hợp mới, giúp hệ thống mở rộng một cách hiệu quả và bền vững.

Các Bề Mặt Vận Hành Của ZeroClaw: Quản Lý và Tương Tác Linh Hoạt

ZeroClaw phơi bày runtime thông qua năm bề mặt riêng biệt, với mức độ thân mật tăng dần, cung cấp các cách tiếp cận đa dạng cho người dùng và nhà phát triển:

  1. CLI (Giao diện dòng lệnh) (zeroclaw agent, zeroclaw onboard, zeroclaw service install, zeroclaw estop) — một cây lệnh dẫn xuất từ clap, với tài liệu tham khảo được tạo ra từ các derive thông qua cargo mdbook refs. Tài liệu không thể sai lệch so với binary, đảm bảo tính nhất quán.
  2. Cổng HTTP/WebSocket (zeroclaw-gateway) — cung cấp REST cho các phiên/bộ nhớ/trạng thái/cron, và WebSocket cho streaming. Mặc định liên kết với 127.0.0.1; liên kết công khai yêu cầu [gateway.allow_public_bind = true] rõ ràng. Ghép nối được yêu cầu theo mặc định, tăng cường bảo mật.
  3. Bảng điều khiển Web (Web dashboard) — cung cấp giao diện người dùng trực quan để chat, duyệt bộ nhớ, chỉnh sửa cấu hình, quản lý cron, kiểm tra công cụ, được phục vụ bởi gateway.
  4. ACP (Agent Client Protocol) — JSON-RPC 2.0 qua stdio, để tích hợp IDE/editor. Các sự kiện session/update với kind = "approval_request" là cách IDE hiển thị các phê duyệt, cho phép tích hợp sâu vào môi trường phát triển.
  5. Đăng ký dịch vụ — Lệnh zeroclaw service install ghi một tệp đơn vị cho systemd, launchctl hoặc Windows Service. Dịch vụ tự quản lý nhật ký, khởi động lại và (trên Linux) thương lượng sandbox, đơn giản hóa việc triển khai và quản lý.

Ngoài ra, cho việc phân phối rộng rãi:

  • Ứng dụng máy tính để bàn Tauri (apps/tauri/) — gói runtime + bảng điều khiển vào một shell native, mang lại trải nghiệm ứng dụng truyền thống.
  • Docker Compose (docker-compose.yml + nhiều Dockerfile.*) — cho phép triển khai dễ dàng trong môi trường container.
  • Kubernetes (deploy-k8s/) — hỗ trợ triển khai và quản lý trên các cụm Kubernetes.
  • Firmware (firmware/) — các stub cho các bo mạch ngoại vi STM32/RPi, mở rộng khả năng tương tác phần cứng.
  • install.sh — một script bootstrap duy nhất hỏi “prebuilt hay source?”, xử lý --minimal (chỉ kernel ~6.6 MB), lựa chọn cờ tính năng, và kết thúc với zeroclaw onboard, đơn giản hóa quá trình cài đặt.

Cấu Hình: Một Tệp TOML Duy Nhất, Mọi Khóa Đều Được Ghi Chú Chi Tiết

ZeroClaw sử dụng một tệp cấu hình duy nhất tại ~/.zeroclaw/config.toml, được thiết kế để dễ đọc và quản lý. Bố cục của tệp này rất rõ ràng:


[providers.models.default]
provider = "openrouter"
model    = "anthropic/claude-sonnet-4-6"
api_key  = "${OPENROUTER_API_KEY}"

[providers.fallback]
chain = ["default", "ollama-local"]

[autonomy]
level             = "supervised"
workspace_only    = true
allowed_commands  = ["git", "cargo", "grep"]
forbidden_paths   = ["/etc", "~/.ssh"]

[security.sandbox]
backend = "auto"          # landlock | bubblewrap | firejail | docker | seatbelt | noop
network = "allowed-domains"
allowed_domains = ["api.openai.com", "api.anthropic.com"]

[agent.tool_receipts]
enabled              = true
show_in_response     = false
inject_system_prompt = true

[channels.discord]
token            = "${DISCORD_TOKEN}"
allowed_users    = ["123456789"]
autonomy_level   = "supervised"   # ghi đè cho từng kênh

[gateway]
bind             = "127.0.0.1:8080"
allow_public_bind = false

[memory]
backend  = "sqlite"
path     = "${ZEROCLAW_HOME}/memory.db"
embedder = "ollama:nomic-embed-text"

Hai nguyên tắc cần sao chép nguyên văn để đảm bảo chất lượng và khả năng bảo trì:

  • Macro derive Configurable. crates/zeroclaw-macros/ cung cấp một derive tạo ra các mục schema từ định nghĩa struct. Tài liệu tham khảo cấu hình đầy đủ (docs/book/src/reference/config.md) được tạo ra từ schema trực tiếp. Tài liệu không thể sai lệch so với mã nguồn, đảm bảo luôn có thông tin chính xác.
  • Bí mật: không bao giờ nội tuyến, luôn là “${ENV_VAR}” interpolation, với một kho bí mật cục bộ được mã hóa (ChaCha20-Poly1305) cho những thứ bạn không muốn nằm trong môi trường. Điều này tăng cường bảo mật và giúp quản lý bí mật an toàn hơn.

Các Cấp Độ Ổn Định: Cách Một Dự Án Non Trẻ Xử Lý Các Thay Đổi Lớn Một Cách An Toàn

Để quản lý các thay đổi và duy trì niềm tin của người dùng, mỗi crate trong không gian làm việc của ZeroClaw mang một cấp độ ổn định (theo RFC #5574 — Microkernel transition). Các cấp độ này định rõ kỳ vọng về sự ổn định và cách các thay đổi đột phá (breaking changes) được xử lý:

Cấp độ Ý nghĩa
✅ Stable (Ổn định) Tuân thủ chính sách thay đổi lớn. Yêu cầu tăng phiên bản major nếu có thay đổi đột phá.
🔶 Beta Thay đổi lớn được phép trong phiên bản MINOR với ghi chú chi tiết trong changelog.
🔬 Experimental (Thử nghiệm) Không có bảo đảm ổn định. Các nhà phát triển có thể tự do lặp lại và thay đổi mà không cần tuân thủ nghiêm ngặt chính sách ổn định.

Các cấp độ được nâng cấp, không bao giờ hạ cấp, bằng quyết định có chủ ý của nhóm phát triển. Ảnh chụp nhanh hiện tại về các cấp độ ổn định của các crate chính:

Crate Cấp độ Mục tiêu ổn định
zeroclaw-api Experimental v1.0.0
zeroclaw-config Beta v0.8.0
zeroclaw-providers Beta —
zeroclaw-memory Beta —
zeroclaw-tool-call-parser Beta v0.8.0
zeroclaw-channels Experimental v1.0.0 (plugin migration)
zeroclaw-tools Experimental v1.0.0 (plugin migration)
zeroclaw-runtime Experimental —

Hãy sao chép ý tưởng này. Đây là cách bạn có thể phát hành sản phẩm công khai, thu hút người dùng, và vẫn có thể lặp lại phát triển một cách an toàn và có kiểm soát, quản lý kỳ vọng của cộng đồng.

Các Cấp Độ Rủi Ro: Quy Trình Đánh Giá Pull Request Hiệu Quả

Tài liệu đóng góp của ZeroClaw phân loại các thay đổi thành ba lớp rủi ro, giúp định hướng quy trình đánh giá Pull Request (PR) một cách có hệ thống và hiệu quả. Hãy sử dụng chúng cho danh sách kiểm tra đánh giá của bạn:

  • 🟢 Thấp: Bao gồm các thay đổi về tài liệu (docs), các tác vụ thông thường (chore) như cập nhật phụ thuộc nhỏ, hoặc chỉ thay đổi kiểm thử. Những PR này thường yêu cầu đánh giá nhanh chóng.
  • 🟡 Trung bình: Hầu hết các thay đổi hành vi trong crates/*/src/** mà không ảnh hưởng đến ranh giới kiến trúc hoặc có tác động bảo mật đáng kể. Các PR này cần được đánh giá kỹ lưỡng hơn.
  • 🔴 Cao: Bất kỳ thay đổi nào trong các khu vực nhạy cảm như runtime/security/ (liên quan đến bảo mật runtime), gateway/ (cổng truy cập), tools/ (công cụ thực thi), .github/workflows/ (quy trình CI/CD), hoặc các thay đổi ảnh hưởng đến ranh giới kiểm soát truy cập. Các PR này yêu cầu đánh giá nghiêm ngặt, thường với nhiều người đánh giá và phê duyệt chặt chẽ.

Khi không chắc chắn, hãy phân loại là rủi ro cao hơn. Việc kiểm soát bởi CI, người đánh giá bắt buộc và ngưỡng phê duyệt được gắn với cấp độ rủi ro, đảm bảo rằng các thay đổi quan trọng được xem xét cẩn thận nhất.

Quy Ước Mã Nguồn: Những Quy Tắc Không Rõ Ràng Bảo Vệ Chất Lượng và Tính Bền Vững

Được lấy từ AGENTS.md, đây là những quy tắc quan trọng mà ZeroClaw tuân thủ để bảo vệ chất lượng mã nguồn, tăng cường khả năng bảo trì và hợp tác. Hãy cân nhắc áp dụng chúng cho dự án của bạn:

  1. Mở rộng hướng trait. Khi thêm nhà cung cấp/kênh/công cụ mới, hãy triển khai một trait và đăng ký trong factory. Không bao giờ vá kernel trực tiếp, đảm bảo kiến trúc mô đun.
  2. Không cấu hình suy đoán. Không thêm khóa cấu hình mà không có trường hợp sử dụng cụ thể trong cùng một PR. Mọi cấu hình phải có mục đích rõ ràng và được sử dụng ngay lập tức.
  3. Bản địa hóa đầu ra hướng người dùng. Mọi tin nhắn CLI, mô tả công cụ, lời nhắc onboard đều sử dụng fl!() / chuỗi Fluent. Các chuỗi ký tự trần trong các đường dẫn hiển thị cho người dùng là lỗi CI, đảm bảo hỗ trợ đa ngôn ngữ ngay từ đầu.
  4. Tin nhắn log/panic bằng tiếng Anh. Các sự kiện tracing:: và panic giữ nguyên tiếng Anh với các trường error_key ổn định. Dịch thuật các thông báo này làm hỏng việc tổng hợp log và gây khó khăn trong việc debug.
  5. Không sử dụng unwrap() / expect() trong các đường dẫn sản xuất. Hãy truyền lỗi hoặc ghi lại bất biến khiến panic là không thể (kèm theo một comment giải thích), tăng cường tính mạnh mẽ của hệ thống.
  6. Không nén mã chết. Không #[allow(dead_code)] hoặc _var để làm im lặng trình biên dịch. Thay vào đó, hãy xóa mã, tích hợp nó vào hành vi, hoặc mở một vấn đề theo dõi. Chỉ dành tên có dấu gạch dưới cho các tham số trait/callback bắt buộc nhưng không được sử dụng.
  7. Một mối quan tâm cho mỗi PR. Các bản vá tính năng+refactor+infra hỗn hợp bị từ chối. Các PR xếp chồng khai báo Depends on #...; các bản thay thế khai báo Supersedes #..., giữ cho lịch sử commit sạch sẽ và dễ theo dõi.
  8. Conventional commits + nhãn kích thước (size: XS/S/M). Luôn là các PR nhỏ, giúp việc đánh giá nhanh hơn và giảm rủi ro.
  9. Quyền riêng tư. Không bao giờ commit dữ liệu cá nhân, danh tính thực hoặc bí mật sản xuất — ngay cả trong ví dụ hoặc fixture kiểm thử. Có một “bảng màu placeholder trung lập” trong docs/.../privacy.md để sử dụng.
  10. Đồng tác giả mã hóa AI được hoan nghênh nhưng có quy định theo RFC #5615 — tiết lộ trợ lý, con người đánh giá, con người ký commit, đảm bảo trách nhiệm giải trình và kiểm soát chất lượng.

Hệ Sinh Thái Công Cụ và Toolchain: Nền Tảng Kỹ Thuật Của ZeroClaw

Để xây dựng một hệ thống phức tạp và mạnh mẽ như ZeroClaw, việc lựa chọn toolchain và các công cụ hỗ trợ là vô cùng quan trọng. Dưới đây là danh sách cụ thể các công cụ mà ZeroClaw sử dụng, có thể là một tham khảo quý giá cho dự án của bạn:

Vấn đề Công cụ
Async runtime tokio
HTTP reqwest
WebSocket tokio-tungstenite
Serialization serde, serde_json, toml
TLS rustls
Crypto chacha20-poly1305 (secrets), ring/hmac+sha2 (receipts)
SQLite rusqlite
CLI parsing clap (derive)
Terminal UI ratatui, dialoguer
Logging/metrics tracing + (tùy chọn) Prometheus + OpenTelemetry
Localization fluent
Build profile LTO + single codegen unit for release; faster CI variant
Lint/format cargo fmt, cargo clippy -D warnings
Lockfile-on-CI cargo build --locked, cargo test --locked
Pre-PR runner just ci (bí danh cho fmt-check + lint + test)
Docs site mdbook với các plugin cargo mdbook refs/sync tùy chỉnh
Fuzzing cargo fuzz
Benchmarks criterion (trong benches/)
Cargo policy cargo-deny (deny.toml) — kiểm toán giấy phép, tư vấn, phụ thuộc bị cấm
Release automation release-plz (release-plz.toml)
Reproducible env flake.nix (Nix), .envrc (direnv), .actrc (act)
Editor integration .vscode/, .gemini/, .claude/skills/ cho các agent

Tạo Tài Liệu Tham Khảo Từ Mã Nguồn: Đảm Bảo Tính Nhất Quán Tuyệt Đối

Một mẫu đáng học hỏi và nên sao chép nguyên văn từ ZeroClaw là cách họ tạo tài liệu tham khảo trực tiếp từ mã nguồn. Điều này đảm bảo tài liệu luôn được cập nhật và phản ánh chính xác trạng thái hiện tại của code:

  • docs/book/src/reference/cli.md được tạo ra từ các derive clap (thông qua lệnh cargo mdbook refs). Bằng cách này, mọi thay đổi trong cấu trúc lệnh CLI sẽ tự động được phản ánh trong tài liệu.
  • docs/book/src/reference/config.md được tạo ra từ schema JSON được tạo bởi macro derive Configurable. Điều này đảm bảo rằng mọi khóa cấu hình và mô tả của chúng đều nhất quán giữa mã và tài liệu.
  • Trang rustdoc-as-website (api.md) được xây dựng lại từ cargo doc --no-deps, cung cấp tài liệu API toàn diện và chính xác.
  • Các bản dịch trong sách tài liệu được khởi tạo bằng AI (cargo mdbook sync gọi Anthropic khi ANTHROPIC_API_KEY được đặt), sau đó được con người đánh giá thông qua các tệp .po, tối ưu hóa quá trình dịch thuật và duy trì chất lượng.

Kết quả: không có trang tham khảo viết tay nào có thể mô tả một tính năng không tồn tại. Hãy tích hợp việc xây dựng tài liệu của bạn vào CI ngay từ ngày đầu tiên; nó sẽ đền đáp gấp mười lần bằng việc giảm thiểu lỗi tài liệu và công sức bảo trì.

Quản Trị: Cách Các Quyết Định Được Đưa Ra và Dự Án Được Định Hướng

Quản trị dự án ZeroClaw được cấu trúc rõ ràng để đảm bảo tính minh bạch, sự tham gia của cộng đồng và định hướng chiến lược. Dưới đây là các trụ cột chính:

  • Quy trình RFC (Request for Comments) cho các thay đổi cơ bản (xem docs/book/src/contributing/rfcs.md). Các RFC nền tảng đã được phê chuẩn (ví dụ: #5574 microkernel, #5576 docs, #5577 governance, #5579 CI, #5615 AI co-authorship, #5653 zero-compromise error handling) đọc như một hiến pháp, định hình các nguyên tắc cốt lõi của dự án.
  • Đa số hai phần ba cho các cuộc bỏ phiếu của nhóm cốt lõi (theo RFC #5577), đảm bảo rằng các quyết định quan trọng được đưa ra với sự đồng thuận rộng rãi.
  • Các tài liệu minh bạch công khai dưới docs/book/src/foundations/ là các tệp được bảo vệ — các kỹ năng agent biết không được di chuyển chúng, duy trì sự ổn định của các tài liệu nền tảng.
  • Chính sách thương hiệu được tách biệt rõ ràng: mã nguồn là MIT-hoặc-Apache; trong khi tên và logo là nhãn hiệu của ZeroClaw Labs. Đây là một mẫu hình phổ biến cho các dự án muốn mã nguồn mở mà không bị mạo danh tên, bảo vệ bản sắc thương hiệu.

Các Chống Mẫu Cần Tránh: Danh Sách Kiểm Tra Từ ZeroClaw Để Đảm Bảo Chất Lượng Dự Án

Trực tiếp từ AGENTS.md, đây là những sai lầm bạn không cần phải tự mình khám phá. Việc tránh những chống mẫu này sẽ giúp dự án của bạn duy trì chất lượng cao và khả năng bảo trì:

  • ❌ Thêm các phụ thuộc nặng nề chỉ vì tiện lợi nhỏ. Điều này làm tăng kích thước binary, thời gian biên dịch và bề mặt tấn công.
  • ❌ Ngầm làm suy yếu chính sách bảo mật hoặc các ràng buộc truy cập. Mọi thay đổi về bảo mật phải rõ ràng và có chủ đích.
  • ❌ Thêm cấu hình/cờ tính năng suy đoán “phòng hờ”. Chỉ thêm cấu hình khi có trường hợp sử dụng cụ thể và cần thiết.
  • ❌ Trộn lẫn các thay đổi định dạng lớn với các thay đổi chức năng. Giữ các loại thay đổi riêng biệt để dễ dàng đánh giá và debug.
  • ❌ Sửa đổi các module không liên quan “trong khi đang ở đây”. Tuân thủ nguyên tắc “một mối quan tâm cho mỗi PR”.
  • ❌ Bỏ qua các kiểm tra lỗi mà không có giải thích rõ ràng. Mọi sự bỏ qua phải được ghi lại và giải thích đầy đủ.
  • ❌ Giấu các tác dụng phụ làm thay đổi hành vi trong các commit refactor. Refactor phải không thay đổi hành vi bên ngoài.
  • ❌ Nén mã sản xuất không sử dụng bằng tiền tố _ hoặc #[allow(dead_code)]. Hãy xóa mã chết hoặc tích hợp nó vào logic.
  • ❌ Để lại unwrap() / expect() trong các đường dẫn sản xuất. Xử lý lỗi một cách rõ ràng và mạnh mẽ hơn.
  • ❌ Bao gồm thông tin cá nhân/nhận dạng trong dữ liệu kiểm thử, ví dụ hoặc commit. Luôn bảo vệ quyền riêng tư.
  • ❌ Gọi các kiểu nhà cung cấp/kênh/công cụ cụ thể từ kernel — hãy đi qua trait. Tuân thủ kiến trúc microkernel để duy trì tính mô đun và khả năng mở rộng.

Lộ Trình Thực Tế Để Xây Dựng Hệ Thống Giống ZeroClaw Của Riêng Bạn

Nếu bạn đang bắt đầu xây dựng một hệ thống AI agent từ đầu, hãy thực hiện theo lộ trình này. Đừng bỏ qua các bước; mỗi bước sẽ tiết lộ các ràng buộc và yêu cầu cho bước tiếp theo, giúp bạn xây dựng một cách có hệ thống và bền vững.

🌱 Giai đoạn 0 — Nền tảng (Tuần 0)

  1. Chọn một ngôn ngữ có khả năng async mạnh mẽ, FFI (Foreign Function Interface) và hệ thống trait/interface. (Rust là ngôn ngữ ZeroClaw sử dụng; Go cũng hoạt động tốt; TypeScript/Node có thể dùng cho phiên bản 0 ban đầu nhưng sẽ không đạt được mức kích thước binary/hiệu suất tương tự).
  2. Viết PHILOSOPHY.md của bạn — ba hoặc bốn quan điểm cốt lõi, được ưu tiên rõ ràng. Đây sẽ là kim chỉ nam cho mọi quyết định thiết kế.
  3. Thiết lập không gian làm việc: Sử dụng cargo workspace (hoặc monorepo tương đương), với một crate trait (*-api) và một crate runtime.
  4. Thiết lập CI (Continuous Integration) ngay từ commit #1: bao gồm format + lint + test + lockfile + kiểm toán giấy phép/tư vấn. Điều này đảm bảo chất lượng và tính nhất quán ngay từ đầu.

🔌 Giai đoạn 1 — Kernel ABI (Tuần 1)

  1. Định nghĩa các trait cốt lõi: Provider, Channel, Tool, Memory, RuntimeAdapter trong API crate. Hạn chế thêm các triển khai ở đây để giữ cho API crate tinh gọn và độc lập.
  2. Viết các kiểu dữ liệu cơ bản: ChatMessage, ToolCall, ToolResult, ChannelMessage, SendMessage, MemoryEntry, StreamEvent. Đừng ngại phát triển chúng theo thời gian — chúng là nền tảng của giao tiếp hệ thống.
  3. Tạo các triển khai noop (không hoạt động) cho mỗi trait để runtime có thể biên dịch end-to-end. Điều này cho phép bạn xây dựng và kiểm thử cấu trúc tổng thể sớm.

🍕 Giai đoạn 2 — Một lát cắt dọc (Tuần 2–3)

  1. Triển khai một nhà cung cấp đầu tiên: Bắt đầu với một nhà cung cấp tương thích OpenAI — đây là “ngôn ngữ chung” và bạn sẽ có thể hỗ trợ 20+ nhà cung cấp khác sau này miễn phí.
  2. Triển khai một kênh đầu tiên: Bắt đầu với CLI (giao diện dòng lệnh) — không yêu cầu xác thực, không webhook, phản hồi tức thì, lý tưởng cho việc phát triển và kiểm thử ban đầu.
  3. Triển khai một công cụ đầu tiên: Bắt đầu với echo đơn giản, sau đó là web_fetch để thử nghiệm tương tác với thế giới bên ngoài.
  4. Triển khai một backend bộ nhớ đầu tiên: SQLite, vì nó là tệp đơn, nhúng và dễ quản lý.
  5. Kết nối vòng lặp agent end-to-end: Từ nhận tin nhắn → tải lịch sử → gọi nhà cung cấp → stream phản hồi → gọi công cụ → thực thi công cụ → phản hồi lại → lưu trữ dữ liệu.
  6. Streaming là một thách thức lớn. Hãy thực hiện đúng ngay từ đầu để tránh các vấn đề phức tạp sau này.

🔒 Giai đoạn 3 — Mô hình bảo mật (Tuần 4)

  1. Triển khai các cấp độ tự chủ: ReadOnly/Supervised/Full và các ghi đè cho từng công cụ.
  2. Thêm kiểm tra ranh giới không gian làm việc và danh sách đường dẫn bị cấm.
  3. Thêm chính sách lệnh shell với danh sách cho phép/từ chối và bộ xác thực mẫu.
  4. Kết nối lời nhắc phê duyệt kênh — ngay cả khi đó chỉ là lời nhắc nội tuyến của CLI, lớp trừu tượng phải hoạt động cho các kênh tương lai.
  5. Triển khai biên lai công cụ với HMAC-SHA256 và khóa phiên tạm thời. Đây là một tính năng rẻ nhưng thay đổi đáng kể hồ sơ trách nhiệm giải trình của agent.

📦 Giai đoạn 4 — Sandbox (Tuần 5)

  1. Tự động phát hiện Landlock trên Linux, Seatbelt trên macOS, Docker làm phương án dự phòng phổ quát.
  2. Biến sandbox thành một tính năng chọn không tham gia (opt-out) (chứ không phải chọn tham gia – opt-in). Mặc định bật, noop cho chế độ YOLO, đảm bảo an toàn theo mặc định.

📈 Giai đoạn 5 — Mở rộng các cạnh (Tuần 6–10)

  1. Thêm nhà cung cấp thứ hai (nhà cung cấp tương thích OpenAI — xác nhận lại rằng trait của bạn là đúng).
  2. Thêm Anthropic (vì giao thức của nó thực sự khác — xác nhận lại tính linh hoạt của kiến trúc).
  3. Thêm trình làm sạch schema khi hỗ trợ Gemini đến (nó sẽ thất bại nếu không có trình làm sạch này).
  4. Thêm chuỗi dự phòng (fallback chain) + bộ định tuyến (router).
  5. Thêm các kênh theo thứ tự này: webhook → Discord → Telegram → Matrix → email → voice. Mỗi kênh sẽ thử thách bộ điều phối theo một cách khác nhau.

🚀 Giai đoạn 6 — Tư thế sản xuất (Tuần 10–14)

  1. Đăng ký dịch vụ (systemd / launchctl / Windows Service) để quản lý tiến trình.
  2. Cổng HTTP/WS + bảng điều khiển web. Mặc định liên kết localhost, yêu cầu liên kết công khai rõ ràng để tăng cường bảo mật.
  3. Quy trình ghép nối + WebAuthn cho bảng điều khiển.
  4. Cron + SOP engine. Xây dựng chế độ thực thi xác định sớm — nó sẽ đền đáp khi một quy trình làm việc chạy 1.000 lần, tiết kiệm chi phí LLM đáng kể.
  5. Khả năng quan sát: tracing, tùy chọn Prometheus, xuất OpenTelemetry.

🐌 Giai đoạn 7 — Phần đuôi dài (Long Tail)

  1. ACP (JSON-RPC qua stdio) để tích hợp IDE.
  2. Hỗ trợ phần cứng đằng sau một cờ tính năng.
  3. Hệ thống plugin (WASM là câu trả lời đúng nếu bạn muốn các công cụ của bên thứ ba).
  4. Ứng dụng máy tính để bàn Tauri.
  5. Bản dịch ngôn ngữ.
  6. Chia microkernel: tiếp tục nâng cấp các crate từ Experimental → Beta → Stable.

Những Điều Thường Dễ Bị Đánh Giá Thấp Khi Xây Dựng AI Agent

Hãy đọc kỹ danh sách này khi bạn đang chuẩn bị phát hành “v0.1” của mình. Đây là những thách thức thường bị đánh giá thấp nhưng lại cực kỳ quan trọng đối với sự thành công và ổn định của một hệ thống AI agent:

  • Streaming + lệnh gọi công cụ. Mô hình sẽ phát ra một lệnh gọi công cụ giữa luồng văn bản. Kênh có thể không hỗ trợ cập nhật bản nháp. Cả hai tình huống này đều phải được xử lý mượt mà.
  • Trải nghiệm người dùng phê duyệt trên mỗi kênh. Nút bấm trong Slack, token trong WhatsApp, RPC trong ACP. Lớp trừu tượng (Channel::ask_approval) phải có hình dạng của kênh, chứ không phải hình dạng của runtime, để đảm bảo trải nghiệm tự nhiên.
  • Giới hạn lặp. Một mô hình trong vòng lặp gọi công cụ có thể đốt $100 trong 30 giây. Hãy giới hạn số lần lặp và ngân sách cho mỗi phiên. Luôn luôn.
  • Sandbox trên macOS. Seatbelt hoạt động tốt nhưng một số binary liên kết Homebrew không hợp tác. Hãy có Docker làm phương án dự phòng được ghi lại.
  • Làm sạch schema trên mỗi nhà cung cấp. Gemini từ chối các từ khóa mà OpenAI chấp nhận. Thực hiện việc làm sạch một lần, tập trung để đảm bảo khả năng tương thích.
  • Lưu giữ nội dung lý luận (reasoning content) khi gửi đi và nhận về. Nếu bạn không bảo toàn reasoning_content một cách không rõ ràng, DeepSeek-R1 / GLM-4.7 sẽ từ chối các lệnh gọi công cụ tiếp theo của bạn.
  • Biên lai hoạt động cùng với bộ phát hiện rò rỉ. Đảm bảo bộ lọc bí mật của bạn cho phép các token biên lai đi qua.
  • Lan truyền hủy bỏ. Các token hủy bỏ phải đến được máy khách HTTP, tiến trình sandbox và lệnh gửi kênh. Luồn chúng qua tokio::task_local! sẽ sạch hơn là luồn qua mọi chữ ký hàm.
  • Cắt tỉa cuộc hội thoại. Lịch sử tăng không giới hạn. ZeroClaw có history_pruner.rs, context_compressor.rs, fast_trim_tool_results, emergency_history_trim. Lập kế hoạch cho điều này ngay từ ngày đầu tiên — ngân sách token là giới hạn thực sự.
  • Câu chuyện di chuyển. Phiên bản schema + di chuyển nằm trong crates/zeroclaw-config/. Khi người dùng có cấu hình, bạn không thể phá vỡ chúng một cách âm thầm.
  • Tài liệu được tạo. Nếu tài liệu được viết tay, chúng sẽ sai lệch. Tạo tài liệu tham khảo; nó sẽ đền đáp gấp mười lần.

Khung Sườn Tối Thiểu Khả Thi (Những Gì Bạn Nhất Định Phải Có)

Nếu bạn quyết định chỉ sao chép một điều từ ZeroClaw, hãy sao chép khung sườn thư mục và tổ chức dự án này. Đây là cấu trúc tối thiểu nhưng đầy đủ để bạn có thể bắt đầu xây dựng một hệ thống AI agent vững chắc:


your-agent/
├── crates/
│   ├── your-api/         # chỉ các trait — Provider, Channel, Tool, Memory
│   ├── your-runtime/     # vòng lặp agent + bảo mật + SOP
│   ├── your-config/      # TOML schema + bí mật
│   ├── your-providers/   # các triển khai đằng sau các cờ tính năng
│   ├── your-channels/    # các triển khai đằng sau các cờ tính năng
│   ├── your-tools/       # các triển khai đằng sau các cờ tính năng
│   └── your-memory/      # SQLite mặc định
├── docs/book/            # mdbook với các ref được tạo từ clap + schema
├── install.sh            # cài đặt một script với --minimal / --source / --prebuilt
├── Justfile              # fmt, lint, test, ci, docs, build
├── deny.toml             # kiểm toán giấy phép + tư vấn
├── flake.nix             # môi trường phát triển có thể tái tạo
├── AGENTS.md             # các quy tắc cho trợ lý mã hóa AI
├── CLAUDE.md             # hướng dẫn trợ lý cụ thể cho dự án
├── .env.example          # mọi nhà cung cấp được hỗ trợ được liệt kê (bị comment)
└── README.md             # triết lý → cài đặt → bắt đầu nhanh → kiến trúc

Mọi thứ khác là sự lặp lại và mở rộng trên hình dạng cơ bản này, cho phép bạn phát triển hệ thống của mình một cách có tổ chức và hiệu quả.

Tài Liệu Tham Khảo Quan Trọng (Nên Đọc Tiếp)

Để hiểu sâu hơn về ZeroClaw và các nguyên tắc thiết kế của nó, hãy tham khảo các nguồn dưới đây, được sắp xếp theo thứ tự “tín hiệu cao nhất trước tiên”:

  • Kho lưu trữ chính thức trên GitHub: https://github.com/zeroclaw-labs/zeroclaw
  • Tài liệu về triết lý dự án — docs/book/src/philosophy.md
  • Hướng dẫn cho các Agent — AGENTS.md (tại thư mục gốc của kho lưu trữ)
  • Tổng quan kiến trúc — docs/book/src/architecture/overview.md
  • Vòng đời yêu cầu — docs/book/src/architecture/request-lifecycle.md
  • Tổng quan về bảo mật — docs/book/src/security/overview.md
  • Biên lai công cụ — docs/book/src/security/tool-receipts.md (và bài báo được trích dẫn)
  • Các cấp độ tự chủ — docs/book/src/security/autonomy.md
  • Sandboxing — docs/book/src/security/sandboxing.md
  • Crate trait (API kernel) — crates/zeroclaw-api/src/{provider,channel,tool,memory_traits,runtime_traits,peripherals_traits,schema,agent}.rs
  • Vòng lặp agent — crates/zeroclaw-runtime/src/agent/loop_.rs
  • Bộ điều phối agent — crates/zeroclaw-runtime/src/agent/dispatcher.rs
  • Công cụ SOP (Standard Operating Procedures) — crates/zeroclaw-runtime/src/sop/{engine,types,condition,dispatch}.rs
  • Bộ điều hợp nhà cung cấp tương thích — crates/zeroclaw-providers/src/compatible.rs
  • Bộ định tuyến và dự phòng — crates/zeroclaw-providers/src/{router,reliable}.rs
  • Trình làm sạch schema — crates/zeroclaw-api/src/schema.rs
  • Các RFC nền tảng (trong trình theo dõi vấn đề trên GitHub): #5574 (microkernel), #5576 (docs), #5577 (governance), #5579 (CI), #5615 (AI co-authorship), #5653 (zero-compromise).

TL;DR — Bốn Câu Quan Trọng Nhất Để Nắm Bắt ZeroClaw

Để xây dựng một hệ thống AI agent tự quản lý mạnh mẽ như ZeroClaw, hãy bắt đầu bằng việc xây dựng một crate trait nhỏ định nghĩa Provider, Channel, Tool và Memory, và tuyệt đối không để runtime phụ thuộc vào bất cứ triển khai cụ thể nào khác. Luôn mặc định chế độ tự chủ Supervised với sandbox được bật, giới hạn không gian làm việc và các lệnh gọi công cụ có biên lai HMAC; chỉ cung cấp chế độ YOLO (You Only Live Once) một cách rõ ràng và có chủ đích cho mục đích phát triển. Chỉ cần phát hành một bộ điều hợp tương thích OpenAI, bạn đã có thể hỗ trợ hơn hai mươi nhà cung cấp LLM khác. Cuối cùng, hãy tạo mọi tài liệu tham khảo trực tiếp từ mã nguồn, quản lý mọi thay đổi lớn đằng sau một cấp độ ổn định cụ thể, và kiên quyết từ chối bất kỳ Pull Request nào trộn lẫn nhiều mối quan tâm khác nhau.

Nếu bạn thấy bài viết này hữu ích, hãy cho tôi biết bằng cách để lại 👍 hoặc bình luận! Hoặc nếu bạn nghĩ bài viết này có thể giúp ích cho ai đó, đừng ngần ngại chia sẻ nhé! Cảm ơn rất nhiều! 😃

Recent News Articles

Fresh job related news content posted each day.

Mục lục

→ Chỉ mục