4abd1b4471
Add full Vietnamese (Tiếng Việt) translation of README.md and update language selector links across existing README files. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
48 KiB
ZeroClaw 🦀
Không tốn thêm tài nguyên. Không đánh đổi. 100% Rust. 100% Đa nền tảng.
⚡️ Chạy trên phần cứng $10 với RAM dưới 5MB — ít hơn 99% bộ nhớ so với OpenClaw, rẻ hơn 98% so với Mac mini!
Được xây dựng bởi sinh viên và thành viên của các cộng đồng Harvard, MIT và Sundai.Club.
🌐 Ngôn ngữ: English · 简体中文 · 日本語 · Русский · Tiếng Việt
Bắt đầu | Cài đặt một lần bấm | Trung tâm tài liệu | Mục lục tài liệu
Truy cập nhanh: Tài liệu tham khảo · Vận hành · Khắc phục sự cố · Bảo mật · Phần cứng · Đóng góp
Hạ tầng trợ lý AI tự chủ — nhanh, nhỏ gọn
Triển khai ở đâu cũng được. Thay thế gì cũng được.
Kiến trúc trait-driven · mặc định bảo mật · provider/channel/tool hoán đổi tự do · mọi thứ đều dễ mở rộng
📢 Thông báo
Bảng này dành cho các thông báo quan trọng (thay đổi không tương thích, cảnh báo bảo mật, lịch bảo trì, vấn đề chặn release).
| Ngày (UTC) | Mức độ | Thông báo | Hành động |
|---|---|---|---|
| 2026-02-19 | Nghiêm trọng | Chúng tôi không có liên kết với openagen/zeroclaw hoặc zeroclaw.org. Tên miền zeroclaw.org hiện đang trỏ đến fork openagen/zeroclaw, và tên miền/repository đó đang mạo danh website/dự án chính thức của chúng tôi. |
Không tin tưởng thông tin, binary, gây quỹ, hay thông báo từ các nguồn đó. Chỉ sử dụng repository này và các tài khoản mạng xã hội đã được xác minh của chúng tôi. |
| 2026-02-19 | Quan trọng | Chúng tôi chưa ra mắt website chính thức, và chúng tôi đang ghi nhận các nỗ lực mạo danh. Không tham gia bất kỳ hoạt động đầu tư hoặc gây quỹ nào tuyên bố mang tên ZeroClaw. | Sử dụng repository này làm nguồn thông tin duy nhất đáng tin cậy. Theo dõi X (@zeroclawlabs), Reddit (r/zeroclawlabs), Telegram (@zeroclawlabs), Telegram CN (@zeroclawlabs_cn), Telegram RU (@zeroclawlabs_ru), và Xiaohongshu để nhận cập nhật chính thức. |
| 2026-02-19 | Quan trọng | Anthropic đã cập nhật điều khoản Xác thực và Sử dụng Thông tin xác thực vào ngày 2026-02-19. Xác thực OAuth (Free, Pro, Max) được dành riêng cho Claude Code và Claude.ai; việc sử dụng OAuth token từ Claude Free/Pro/Max trong bất kỳ sản phẩm, công cụ hay dịch vụ nào khác (bao gồm Agent SDK) đều không được phép và có thể vi phạm Điều khoản Dịch vụ cho Người tiêu dùng. | Vui lòng tạm thời tránh tích hợp Claude Code OAuth để ngăn ngừa khả năng mất mát. Điều khoản gốc: Authentication and Credential Use. |
✨ Tính năng
- 🏎️ Mặc định tinh gọn: Các tác vụ CLI và kiểm tra trạng thái chỉ tốn vài MB bộ nhớ trên bản release.
- 💰 Triển khai rẻ: Chạy tốt trên board giá rẻ và instance cloud nhỏ, không cần runtime nặng.
- ⚡ Khởi động lạnh nhanh: Một binary Rust duy nhất — lệnh và daemon khởi động gần như tức thì.
- 🌍 Chạy ở đâu cũng được: Một binary chạy trên ARM, x86 và RISC-V — provider/channel/tool hoán đổi tự do.
Vì sao các team chọn ZeroClaw
- Mặc định tinh gọn: binary Rust nhỏ, khởi động nhanh, tốn ít bộ nhớ.
- Bảo mật từ gốc: xác thực ghép cặp, sandbox nghiêm ngặt, allowlist rõ ràng, giới hạn workspace.
- Hoán đổi tự do: mọi hệ thống cốt lõi đều là trait (provider, channel, tool, memory, tunnel).
- Không khoá vendor: hỗ trợ provider tương thích OpenAI + endpoint tùy chỉnh dễ dàng mở rộng.
So sánh hiệu suất (ZeroClaw vs OpenClaw, có thể tái tạo)
Đo nhanh trên máy cục bộ (macOS arm64, tháng 2/2026), quy đổi cho phần cứng edge 0.8GHz.
| OpenClaw | NanoBot | PicoClaw | ZeroClaw 🦀 | |
|---|---|---|---|---|
| Ngôn ngữ | TypeScript | Python | Go | Rust |
| RAM | > 1GB | > 100MB | < 10MB | < 5MB |
| Khởi động (lõi 0.8GHz) | > 500s | > 30s | < 1s | < 10ms |
| Kích thước binary | ~28MB (dist) | N/A (Scripts) | ~8MB | 3.4 MB |
| Chi phí | Mac Mini $599 | Linux SBC ~$50 | Linux Board $10 | Phần cứng bất kỳ $10 |
Ghi chú: Kết quả ZeroClaw được đo trên release build sử dụng
/usr/bin/time -l. OpenClaw yêu cầu runtime Node.js (thường thêm ~390MB bộ nhớ overhead), còn NanoBot yêu cầu runtime Python. PicoClaw và ZeroClaw là các static binary. Số RAM ở trên là bộ nhớ runtime; yêu cầu biên dịch lúc build-time sẽ cao hơn.
Tự đo trên máy bạn
Kết quả benchmark thay đổi theo code và toolchain, nên hãy tự đo bản build hiện tại:
cargo build --release
ls -lh target/release/zeroclaw
/usr/bin/time -l target/release/zeroclaw --help
/usr/bin/time -l target/release/zeroclaw status
Ví dụ mẫu (macOS arm64, đo ngày 18 tháng 2 năm 2026):
- Kích thước binary release:
8.8M zeroclaw --help: khoảng0.02s, bộ nhớ đỉnh ~3.9MBzeroclaw status: khoảng0.01s, bộ nhớ đỉnh ~4.1MB
Yêu cầu hệ thống
Windows
Bắt buộc
-
Visual Studio Build Tools (cung cấp MSVC linker và Windows SDK):
winget install Microsoft.VisualStudio.2022.BuildToolsTrong quá trình cài đặt (hoặc qua Visual Studio Installer), chọn workload "Desktop development with C++".
-
Rust toolchain:
winget install Rustlang.RustupSau khi cài đặt, mở terminal mới và chạy
rustup default stableđể đảm bảo toolchain stable đang hoạt động. -
Xác minh cả hai đang hoạt động:
rustc --version cargo --version
Tùy chọn
- Docker Desktop — chỉ cần thiết nếu dùng Docker sandboxed runtime (
runtime.kind = "docker"). Cài đặt quawinget install Docker.DockerDesktop.
Linux / macOS
Bắt buộc
-
Công cụ build cơ bản:
- Linux (Debian/Ubuntu):
sudo apt install build-essential pkg-config - Linux (Fedora/RHEL):
sudo dnf group install development-tools && sudo dnf install pkg-config - macOS: Cài đặt Xcode Command Line Tools:
xcode-select --install
- Linux (Debian/Ubuntu):
-
Rust toolchain:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | shXem rustup.rs để biết thêm chi tiết.
-
Xác minh cả hai đang hoạt động:
rustc --version cargo --version
Cài bằng một lệnh
Hoặc bỏ qua các bước trên, cài hết mọi thứ (system deps, Rust, ZeroClaw) chỉ bằng một lệnh:
curl -LsSf https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/scripts/install.sh | bash
Yêu cầu tài nguyên biên dịch
Việc build từ source đòi hỏi nhiều tài nguyên hơn so với chạy binary kết quả:
| Tài nguyên | Tối thiểu | Khuyến nghị |
|---|---|---|
| RAM + swap | 2 GB | 4 GB+ |
| Dung lượng đĩa trống | 6 GB | 10 GB+ |
Nếu cấu hình máy thấp hơn mức tối thiểu, dùng binary có sẵn:
./bootstrap.sh --prefer-prebuilt
Chỉ cài từ binary, không quay lại build từ source:
./bootstrap.sh --prebuilt-only
Tùy chọn
- Docker — chỉ cần thiết nếu dùng Docker sandboxed runtime (
runtime.kind = "docker"). Cài đặt qua package manager hoặc docker.com.
Lưu ý: Lệnh
cargo build --releasemặc định dùngcodegen-units=1để giảm áp lực biên dịch đỉnh. Để build nhanh hơn trên máy mạnh, dùngcargo build --profile release-fast.
Bắt đầu nhanh
Homebrew (macOS/Linuxbrew)
brew install zeroclaw
Bootstrap một lần bấm
# Khuyến nghị: clone rồi chạy script bootstrap cục bộ
git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
./bootstrap.sh
# Tùy chọn: cài đặt system dependencies + Rust trên máy mới
./bootstrap.sh --install-system-deps --install-rust
# Tùy chọn: ưu tiên binary dựng sẵn (khuyến nghị cho máy ít RAM/ít dung lượng đĩa)
./bootstrap.sh --prefer-prebuilt
# Tùy chọn: cài đặt chỉ từ binary (không fallback sang build source)
./bootstrap.sh --prebuilt-only
# Tùy chọn: chạy onboarding trong cùng luồng
./bootstrap.sh --onboard --api-key "sk-..." --provider openrouter [--model "openrouter/auto"]
# Tùy chọn: chạy bootstrap + onboarding hoàn toàn trong Docker
./bootstrap.sh --docker
Cài từ xa bằng một lệnh (nên xem trước nếu môi trường nhạy cảm về bảo mật):
curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/scripts/bootstrap.sh | bash
Chi tiết: docs/one-click-bootstrap.md (chế độ toolchain có thể yêu cầu sudo cho các gói hệ thống).
Binary có sẵn
Release asset được phát hành cho:
- Linux:
x86_64,aarch64,armv7 - macOS:
x86_64,aarch64 - Windows:
x86_64
Tải asset mới nhất tại: https://github.com/zeroclaw-labs/zeroclaw/releases/latest
Ví dụ (ARM64 Linux):
curl -fsSLO https://github.com/zeroclaw-labs/zeroclaw/releases/latest/download/zeroclaw-aarch64-unknown-linux-gnu.tar.gz
tar xzf zeroclaw-aarch64-unknown-linux-gnu.tar.gz
install -m 0755 zeroclaw "$HOME/.cargo/bin/zeroclaw"
git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
cargo build --release --locked
cargo install --path . --force --locked
# Đảm bảo ~/.cargo/bin có trong PATH của bạn
export PATH="$HOME/.cargo/bin:$PATH"
# Cài nhanh (không cần tương tác, có thể chỉ định model)
zeroclaw onboard --api-key sk-... --provider openrouter [--model "openrouter/auto"]
# Hoặc dùng trình hướng dẫn tương tác
zeroclaw onboard --interactive
# Hoặc chỉ sửa nhanh channel/allowlist
zeroclaw onboard --channels-only
# Chat
zeroclaw agent -m "Hello, ZeroClaw!"
# Chế độ tương tác
zeroclaw agent
# Khởi động gateway (webhook server)
zeroclaw gateway # mặc định: 127.0.0.1:3000
zeroclaw gateway --port 0 # cổng ngẫu nhiên (tăng cường bảo mật)
# Khởi động runtime tự trị đầy đủ
zeroclaw daemon
# Kiểm tra trạng thái
zeroclaw status
zeroclaw auth status
# Chạy chẩn đoán hệ thống
zeroclaw doctor
# Kiểm tra sức khỏe channel
zeroclaw channel doctor
# Gắn định danh Telegram vào allowlist
zeroclaw channel bind-telegram 123456789
# Lấy thông tin cài đặt tích hợp
zeroclaw integrations info Telegram
# Lưu ý: Channel (Telegram, Discord, Slack) yêu cầu daemon đang chạy
# zeroclaw daemon
# Quản lý dịch vụ nền
zeroclaw service install
zeroclaw service status
zeroclaw service restart
# Chuyển dữ liệu từ OpenClaw (chạy thử trước)
zeroclaw migrate openclaw --dry-run
zeroclaw migrate openclaw
Chạy trực tiếp khi phát triển (không cần cài toàn cục): thêm
cargo run --release --trước lệnh (ví dụ:cargo run --release -- status).
Xác thực theo gói đăng ký (OpenAI Codex / Claude Code)
ZeroClaw hỗ trợ profile xác thực theo gói đăng ký (đa tài khoản, mã hóa khi lưu).
- File lưu trữ:
~/.zeroclaw/auth-profiles.json - Khóa mã hóa:
~/.zeroclaw/.secret_key - Định dạng profile id:
<provider>:<profile_name>(ví dụ:openai-codex:work)
OpenAI Codex OAuth (đăng ký ChatGPT):
# Khuyến nghị trên server/headless
zeroclaw auth login --provider openai-codex --device-code
# Luồng Browser/callback với fallback paste
zeroclaw auth login --provider openai-codex --profile default
zeroclaw auth paste-redirect --provider openai-codex --profile default
# Kiểm tra / làm mới / chuyển profile
zeroclaw auth status
zeroclaw auth refresh --provider openai-codex --profile default
zeroclaw auth use --provider openai-codex --profile work
Claude Code / Anthropic setup-token:
# Dán token đăng ký/setup (chế độ Authorization header)
zeroclaw auth paste-token --provider anthropic --profile default --auth-kind authorization
# Lệnh alias
zeroclaw auth setup-token --provider anthropic --profile default
Chạy agent với xác thực đăng ký:
zeroclaw agent --provider openai-codex -m "hello"
zeroclaw agent --provider openai-codex --auth-profile openai-codex:work -m "hello"
# Anthropic hỗ trợ cả API key và biến môi trường auth token:
# ANTHROPIC_AUTH_TOKEN, ANTHROPIC_OAUTH_TOKEN, ANTHROPIC_API_KEY
zeroclaw agent --provider anthropic -m "hello"
Kiến trúc
Mọi hệ thống con đều là trait — chỉ cần đổi cấu hình, không cần sửa code.
| Hệ thống con | Trait | Đi kèm sẵn | Mở rộng |
|---|---|---|---|
| Mô hình AI | Provider |
Danh mục provider qua zeroclaw providers (hiện có 28 built-in + alias, cộng endpoint tùy chỉnh) |
custom:https://your-api.com (tương thích OpenAI) hoặc anthropic-custom:https://your-api.com |
| Channel | Channel |
CLI, Telegram, Discord, Slack, Mattermost, iMessage, Matrix, Signal, WhatsApp, Email, IRC, Lark, DingTalk, QQ, Webhook | Bất kỳ messaging API nào |
| Memory | Memory |
SQLite hybrid search, PostgreSQL backend (storage provider có thể cấu hình), Lucid bridge, Markdown files, backend none tường minh, snapshot/hydrate, response cache tùy chọn |
Bất kỳ persistence backend nào |
| Tool | Tool |
shell/file/memory, cron/schedule, git, pushover, browser, http_request, screenshot/image_info, composio (opt-in), delegate, hardware tools | Bất kỳ khả năng nào |
| Observability | Observer |
Noop, Log, Multi | Prometheus, OTel |
| Runtime | RuntimeAdapter |
Native, Docker (sandboxed) | Có thể thêm runtime bổ sung qua adapter; các kind không được hỗ trợ sẽ fail nhanh |
| Bảo mật | SecurityPolicy |
Ghép cặp gateway, sandbox, allowlist, giới hạn tốc độ, phân vùng filesystem, secret mã hóa | — |
| Định danh | IdentityConfig |
OpenClaw (markdown), AIEOS v1.1 (JSON) | Bất kỳ định dạng định danh nào |
| Tunnel | Tunnel |
None, Cloudflare, Tailscale, ngrok, Custom | Bất kỳ tunnel binary nào |
| Heartbeat | Engine | Tác vụ định kỳ HEARTBEAT.md | — |
| Skill | Loader | TOML manifest + hướng dẫn SKILL.md | Community skill pack |
| Tích hợp | Registry | 70+ tích hợp trong 9 danh mục | Plugin system |
Hỗ trợ runtime (hiện tại)
- ✅ Được hỗ trợ hiện nay:
runtime.kind = "native"hoặcruntime.kind = "docker" - 🚧 Đã lên kế hoạch, chưa triển khai: WASM / edge runtime
Khi cấu hình runtime.kind không được hỗ trợ, ZeroClaw sẽ thoát với thông báo lỗi rõ ràng thay vì âm thầm fallback về native.
Hệ thống Memory (Search Engine toàn diện)
Tự phát triển hoàn toàn, không phụ thuộc bên ngoài — không Pinecone, không Elasticsearch, không LangChain:
| Lớp | Triển khai |
|---|---|
| Vector DB | Embeddings lưu dưới dạng BLOB trong SQLite, tìm kiếm cosine similarity |
| Keyword Search | Bảng ảo FTS5 với BM25 scoring |
| Hybrid Merge | Hàm merge có trọng số tùy chỉnh (vector.rs) |
| Embeddings | Trait EmbeddingProvider — OpenAI, URL tùy chỉnh, hoặc noop |
| Chunking | Bộ chia đoạn markdown theo dòng, giữ nguyên heading |
| Caching | Bảng SQLite embedding_cache với LRU eviction |
| Safe Reindex | Rebuild FTS5 + re-embed các vector bị thiếu theo cách nguyên tử |
Agent tự động ghi nhớ, lưu trữ và quản lý memory qua các tool.
[memory]
backend = "sqlite" # "sqlite", "lucid", "postgres", "markdown", "none"
auto_save = true
embedding_provider = "none" # "none", "openai", "custom:https://..."
vector_weight = 0.7
keyword_weight = 0.3
# backend = "none" sử dụng no-op memory backend tường minh (không có persistence)
# Tùy chọn: ghi đè storage-provider cho remote memory backend.
# Khi provider = "postgres", ZeroClaw dùng PostgreSQL để lưu memory.
# Khóa db_url cũng chấp nhận alias `dbURL` để tương thích ngược.
#
# [storage.provider.config]
# provider = "postgres"
# db_url = "postgres://user:password@host:5432/zeroclaw"
# schema = "public"
# table = "memories"
# connect_timeout_secs = 15
# Tùy chọn cho backend = "sqlite": số giây tối đa chờ khi mở DB (ví dụ: file bị khóa). Bỏ qua hoặc để trống để không có timeout.
# sqlite_open_timeout_secs = 30
# Tùy chọn cho backend = "lucid"
# ZEROCLAW_LUCID_CMD=/usr/local/bin/lucid # mặc định: lucid
# ZEROCLAW_LUCID_BUDGET=200 # mặc định: 200
# ZEROCLAW_LUCID_LOCAL_HIT_THRESHOLD=3 # số lần hit cục bộ để bỏ qua external recall
# ZEROCLAW_LUCID_RECALL_TIMEOUT_MS=120 # giới hạn thời gian cho lucid context recall
# ZEROCLAW_LUCID_STORE_TIMEOUT_MS=800 # timeout đồng bộ async cho lucid store
# ZEROCLAW_LUCID_FAILURE_COOLDOWN_MS=15000 # thời gian nghỉ sau lỗi lucid, tránh thử lại liên tục
Bảo mật
ZeroClaw thực thi bảo mật ở mọi lớp — không chỉ sandbox. Đáp ứng tất cả các hạng mục trong danh sách kiểm tra bảo mật của cộng đồng.
Danh sách kiểm tra bảo mật
| # | Hạng mục | Trạng thái | Cách thực hiện |
|---|---|---|---|
| 1 | Gateway không công khai ra ngoài | ✅ | Bind vào 127.0.0.1 theo mặc định. Từ chối 0.0.0.0 nếu không có tunnel hoặc allow_public_bind = true tường minh. |
| 2 | Yêu cầu ghép cặp | ✅ | Mã một lần 6 chữ số khi khởi động. Trao đổi qua POST /pair để lấy bearer token. Mọi yêu cầu /webhook đều cần Authorization: Bearer <token>. |
| 3 | Phân vùng filesystem (không phải /) | ✅ | workspace_only = true theo mặc định. Chặn 14 thư mục hệ thống + 4 dotfile nhạy cảm. Chặn null byte injection. Phát hiện symlink escape qua canonicalization + kiểm tra resolved-path trong các tool đọc/ghi file. |
| 4 | Chỉ truy cập qua tunnel | ✅ | Gateway từ chối bind công khai khi không có tunnel đang hoạt động. Hỗ trợ Tailscale, Cloudflare, ngrok, hoặc tunnel tùy chỉnh. |
Tự chạy nmap:
nmap -p 1-65535 <your-host>— ZeroClaw chỉ bind vào localhost, nên không có gì bị lộ ra ngoài trừ khi bạn cấu hình tunnel tường minh.
Allowlist channel (từ chối theo mặc định)
Chính sách kiểm soát người gửi đã được thống nhất:
- Allowlist rỗng = từ chối tất cả tin nhắn đến
"*"= cho phép tất cả (phải opt-in tường minh)- Nếu khác = allowlist khớp chính xác
Mặc định an toàn, hạn chế tối đa rủi ro lộ thông tin.
Tài liệu tham khảo đầy đủ về cấu hình channel: docs/channels-reference.md.
Cài đặt được khuyến nghị (bảo mật + nhanh):
- Telegram: thêm
@usernamecủa bạn (không có@) và/hoặc Telegram user ID số vào allowlist. - Discord: thêm Discord user ID của bạn vào allowlist.
- Slack: thêm Slack member ID của bạn (thường bắt đầu bằng
U) vào allowlist. - Mattermost: dùng API v4 tiêu chuẩn. Allowlist dùng Mattermost user ID.
- Chỉ dùng
"*"cho kiểm thử mở tạm thời.
Luồng phê duyệt của operator qua Telegram:
- Để
[channels_config.telegram].allowed_users = []để từ chối theo mặc định khi khởi động. - Người dùng không được phép sẽ nhận được gợi ý kèm lệnh operator có thể copy:
zeroclaw channel bind-telegram <IDENTITY>. - Operator chạy lệnh đó tại máy cục bộ, sau đó người dùng thử gửi tin nhắn lại.
Nếu cần phê duyệt thủ công một lần, chạy:
zeroclaw channel bind-telegram 123456789
Nếu bạn không chắc định danh nào cần dùng:
- Khởi động channel và gửi một tin nhắn đến bot của bạn.
- Đọc log cảnh báo để thấy định danh người gửi chính xác.
- Thêm giá trị đó vào allowlist và chạy lại channel-only setup.
Nếu bạn thấy cảnh báo ủy quyền trong log (ví dụ: ignoring message from unauthorized user),
chạy lại channel setup:
zeroclaw onboard --channels-only
Phản hồi media Telegram
Telegram định tuyến phản hồi theo chat ID nguồn (thay vì username),
tránh lỗi Bad Request: chat not found.
Với các phản hồi không phải văn bản, ZeroClaw có thể gửi file đính kèm Telegram khi assistant bao gồm các marker:
[IMAGE:<path-or-url>][DOCUMENT:<path-or-url>][VIDEO:<path-or-url>][AUDIO:<path-or-url>][VOICE:<path-or-url>]
Path có thể là file cục bộ (ví dụ /tmp/screenshot.png) hoặc URL HTTPS.
Cài đặt WhatsApp
ZeroClaw hỗ trợ hai backend WhatsApp:
- Chế độ WhatsApp Web (QR / pair code, không cần Meta Business API)
- Chế độ WhatsApp Business Cloud API (luồng webhook chính thức của Meta)
Chế độ WhatsApp Web (khuyến nghị cho dùng cá nhân/self-hosted)
-
Build với hỗ trợ WhatsApp Web:
cargo build --features whatsapp-web -
Cấu hình ZeroClaw:
[channels_config.whatsapp] session_path = "~/.zeroclaw/state/whatsapp-web/session.db" pair_phone = "15551234567" # tùy chọn; bỏ qua để dùng luồng QR pair_code = "" # tùy chọn mã pair tùy chỉnh allowed_numbers = ["+1234567890"] # định dạng E.164, hoặc ["*"] cho tất cả -
Khởi động channel/daemon và liên kết thiết bị:
- Chạy
zeroclaw channel start(hoặczeroclaw daemon). - Làm theo hướng dẫn ghép cặp trên terminal (QR hoặc pair code).
- Trên WhatsApp điện thoại: Cài đặt → Thiết bị đã liên kết.
- Chạy
-
Kiểm tra: Gửi tin nhắn từ số được phép và xác nhận agent trả lời.
Chế độ WhatsApp Business Cloud API
WhatsApp dùng Cloud API của Meta với webhook (push-based, không phải polling):
-
Tạo Meta Business App:
- Truy cập developers.facebook.com
- Tạo app mới → Chọn loại "Business"
- Thêm sản phẩm "WhatsApp"
-
Lấy thông tin xác thực:
- Access Token: Từ WhatsApp → API Setup → Generate token (hoặc tạo System User cho token vĩnh viễn)
- Phone Number ID: Từ WhatsApp → API Setup → Phone number ID
- Verify Token: Bạn tự định nghĩa (bất kỳ chuỗi ngẫu nhiên nào) — Meta sẽ gửi lại trong quá trình xác minh webhook
-
Cấu hình ZeroClaw:
[channels_config.whatsapp] access_token = "EAABx..." phone_number_id = "123456789012345" verify_token = "my-secret-verify-token" allowed_numbers = ["+1234567890"] # định dạng E.164, hoặc ["*"] cho tất cả -
Khởi động gateway với tunnel:
zeroclaw gateway --port 3000WhatsApp yêu cầu HTTPS, vì vậy hãy dùng tunnel (ngrok, Cloudflare, Tailscale Funnel).
-
Cấu hình Meta webhook:
- Trong Meta Developer Console → WhatsApp → Configuration → Webhook
- Callback URL:
https://your-tunnel-url/whatsapp - Verify Token: Giống với
verify_tokentrong config của bạn - Đăng ký nhận trường
messages
-
Kiểm tra: Gửi tin nhắn đến số WhatsApp Business của bạn — ZeroClaw sẽ phản hồi qua LLM.
Cấu hình
Config: ~/.zeroclaw/config.toml (được tạo bởi onboard)
Khi zeroclaw channel start đang chạy, các thay đổi với default_provider,
default_model, default_temperature, api_key, api_url, và reliability.*
sẽ được áp dụng nóng vào lần có tin nhắn channel đến tiếp theo.
api_key = "sk-..."
default_provider = "openrouter"
default_model = "anthropic/claude-sonnet-4-6"
default_temperature = 0.7
# Endpoint tùy chỉnh tương thích OpenAI
# default_provider = "custom:https://your-api.com"
# Endpoint tùy chỉnh tương thích Anthropic
# default_provider = "anthropic-custom:https://your-api.com"
[memory]
backend = "sqlite" # "sqlite", "lucid", "postgres", "markdown", "none"
auto_save = true
embedding_provider = "none" # "none", "openai", "custom:https://..."
vector_weight = 0.7
keyword_weight = 0.3
# backend = "none" vô hiệu hóa persistent memory qua no-op backend
# Tùy chọn ghi đè storage-provider từ xa (ví dụ PostgreSQL)
# [storage.provider.config]
# provider = "postgres"
# db_url = "postgres://user:password@host:5432/zeroclaw"
# schema = "public"
# table = "memories"
# connect_timeout_secs = 15
[gateway]
port = 3000 # mặc định
host = "127.0.0.1" # mặc định
require_pairing = true # yêu cầu pairing code khi kết nối lần đầu
allow_public_bind = false # từ chối 0.0.0.0 nếu không có tunnel
[autonomy]
level = "supervised" # "readonly", "supervised", "full" (mặc định: supervised)
workspace_only = true # mặc định: true — phân vùng vào workspace
allowed_commands = ["git", "npm", "cargo", "ls", "cat", "grep"]
forbidden_paths = ["/etc", "/root", "/proc", "/sys", "~/.ssh", "~/.gnupg", "~/.aws"]
[runtime]
kind = "native" # "native" hoặc "docker"
[runtime.docker]
image = "alpine:3.20" # container image cho thực thi shell
network = "none" # chế độ docker network ("none", "bridge", v.v.)
memory_limit_mb = 512 # giới hạn bộ nhớ tùy chọn tính bằng MB
cpu_limit = 1.0 # giới hạn CPU tùy chọn
read_only_rootfs = true # mount root filesystem ở chế độ read-only
mount_workspace = true # mount workspace vào /workspace
allowed_workspace_roots = [] # allowlist tùy chọn để xác thực workspace mount
[heartbeat]
enabled = false
interval_minutes = 30
[tunnel]
provider = "none" # "none", "cloudflare", "tailscale", "ngrok", "custom"
[secrets]
encrypt = true # API key được mã hóa bằng file key cục bộ
[browser]
enabled = false # opt-in browser_open + browser tool
allowed_domains = ["docs.rs"] # bắt buộc khi browser được bật
backend = "agent_browser" # "agent_browser" (mặc định), "rust_native", "computer_use", "auto"
native_headless = true # áp dụng khi backend dùng rust-native
native_webdriver_url = "http://127.0.0.1:9515" # WebDriver endpoint (chromedriver/selenium)
# native_chrome_path = "/usr/bin/chromium" # tùy chọn chỉ định rõ browser binary cho driver
[browser.computer_use]
endpoint = "http://127.0.0.1:8787/v1/actions" # HTTP endpoint của computer-use sidecar
timeout_ms = 15000 # timeout mỗi action
allow_remote_endpoint = false # mặc định bảo mật: chỉ endpoint private/localhost
window_allowlist = [] # gợi ý allowlist tên cửa sổ/process tùy chọn
# api_key = "..." # bearer token tùy chọn cho sidecar
# max_coordinate_x = 3840 # guardrail tọa độ tùy chọn
# max_coordinate_y = 2160 # guardrail tọa độ tùy chọn
# Flag build Rust-native backend:
# cargo build --release --features browser-native
# Đảm bảo WebDriver server đang chạy, ví dụ: chromedriver --port=9515
# Hợp đồng computer-use sidecar (MVP)
# POST browser.computer_use.endpoint
# Request: {
# "action": "mouse_click",
# "params": {"x": 640, "y": 360, "button": "left"},
# "policy": {"allowed_domains": [...], "window_allowlist": [...], "max_coordinate_x": 3840, "max_coordinate_y": 2160},
# "metadata": {"session_name": "...", "source": "zeroclaw.browser", "version": "..."}
# }
# Response: {"success": true, "data": {...}} hoặc {"success": false, "error": "..."}
[composio]
enabled = false # opt-in: hơn 1000 OAuth app qua composio.dev
# api_key = "cmp_..." # tùy chọn: được lưu mã hóa khi [secrets].encrypt = true
entity_id = "default" # user_id mặc định cho Composio tool call
# Gợi ý runtime: nếu execute yêu cầu connected_account_id, chạy composio với
# action='list_accounts' và app='gmail' (hoặc toolkit của bạn) để lấy account ID.
[identity]
format = "openclaw" # "openclaw" (mặc định, markdown files) hoặc "aieos" (JSON)
# aieos_path = "identity.json" # đường dẫn đến file AIEOS JSON (tương đối với workspace hoặc tuyệt đối)
# aieos_inline = '{"identity":{"names":{"first":"Nova"}}}' # inline AIEOS JSON
Ollama cục bộ và endpoint từ xa
ZeroClaw dùng một khóa provider (ollama) cho cả triển khai Ollama cục bộ và từ xa:
- Ollama cục bộ: để
api_urltrống, chạyollama serve, và dùng các model nhưllama3.2. - Endpoint Ollama từ xa (bao gồm Ollama Cloud): đặt
api_urlthành endpoint từ xa và đặtapi_key(hoặcOLLAMA_API_KEY) khi cần. - Tùy chọn suffix
:cloud: ID model nhưqwen3:cloudđược chuẩn hóa thànhqwen3trước khi gửi request.
Ví dụ cấu hình từ xa:
default_provider = "ollama"
default_model = "qwen3:cloud"
api_url = "https://ollama.com"
api_key = "ollama_api_key_here"
Endpoint provider tùy chỉnh
Cấu hình chi tiết cho endpoint tùy chỉnh tương thích OpenAI và Anthropic, xem docs/custom-providers.md.
Gói Python đi kèm (zeroclaw-tools)
Với các LLM provider có tool calling native không ổn định (ví dụ: GLM-5/Zhipu), ZeroClaw đi kèm gói Python dùng LangGraph để gọi tool nhằm đảm bảo tính nhất quán:
pip install zeroclaw-tools
from zeroclaw_tools import create_agent, shell, file_read
from langchain_core.messages import HumanMessage
# Hoạt động với mọi provider tương thích OpenAI
agent = create_agent(
tools=[shell, file_read],
model="glm-5",
api_key="your-key",
base_url="https://api.z.ai/api/coding/paas/v4"
)
result = await agent.ainvoke({
"messages": [HumanMessage(content="List files in /tmp")]
})
print(result["messages"][-1].content)
Lý do nên dùng:
- Tool calling nhất quán trên mọi provider (kể cả những provider hỗ trợ native kém)
- Vòng lặp tool tự động — tiếp tục gọi tool cho đến khi hoàn thành tác vụ
- Dễ mở rộng — thêm tool tùy chỉnh với decorator
@tool - Tích hợp Discord bot đi kèm (Telegram đang lên kế hoạch)
Xem python/README.md để có tài liệu đầy đủ.
Hệ thống định danh (Hỗ trợ AIEOS)
ZeroClaw hỗ trợ persona AI không phụ thuộc nền tảng qua hai định dạng:
OpenClaw (Mặc định)
Các file markdown truyền thống trong workspace của bạn:
IDENTITY.md— Agent là aiSOUL.md— Tính cách và giá trị cốt lõiUSER.md— Agent đang hỗ trợ aiAGENTS.md— Hướng dẫn hành vi
AIEOS (AI Entity Object Specification)
AIEOS là framework chuẩn hóa cho định danh AI di động. ZeroClaw hỗ trợ payload AIEOS v1.1 JSON, cho phép bạn:
- Import định danh từ hệ sinh thái AIEOS
- Export định danh sang các hệ thống tương thích AIEOS khác
- Duy trì tính toàn vẹn hành vi trên các mô hình AI khác nhau
Bật AIEOS
[identity]
format = "aieos"
aieos_path = "identity.json" # tương đối với workspace hoặc đường dẫn tuyệt đối
Hoặc JSON inline:
[identity]
format = "aieos"
aieos_inline = '''
{
"identity": {
"names": { "first": "Nova", "nickname": "N" },
"bio": { "gender": "Non-binary", "age_biological": 3 },
"origin": { "nationality": "Digital", "birthplace": { "city": "Cloud" } }
},
"psychology": {
"neural_matrix": { "creativity": 0.9, "logic": 0.8 },
"traits": {
"mbti": "ENTP",
"ocean": { "openness": 0.8, "conscientiousness": 0.6 }
},
"moral_compass": {
"alignment": "Chaotic Good",
"core_values": ["Curiosity", "Autonomy"]
}
},
"linguistics": {
"text_style": {
"formality_level": 0.2,
"style_descriptors": ["curious", "energetic"]
},
"idiolect": {
"catchphrases": ["Let's test this"],
"forbidden_words": ["never"]
}
},
"motivations": {
"core_drive": "Push boundaries and explore possibilities",
"goals": {
"short_term": ["Prototype quickly"],
"long_term": ["Build reliable systems"]
}
},
"capabilities": {
"skills": [{ "name": "Rust engineering" }, { "name": "Prompt design" }],
"tools": ["shell", "file_read"]
}
}
'''
ZeroClaw chấp nhận cả payload AIEOS đầy đủ lẫn dạng rút gọn, rồi chuẩn hóa về một định dạng system prompt thống nhất.
Các phần trong Schema AIEOS
| Phần | Mô tả |
|---|---|
identity |
Tên, tiểu sử, xuất xứ, nơi cư trú |
psychology |
Neural matrix (trọng số nhận thức), MBTI, OCEAN, la bàn đạo đức |
linguistics |
Phong cách văn bản, mức độ trang trọng, câu cửa miệng, từ bị cấm |
motivations |
Động lực cốt lõi, mục tiêu ngắn/dài hạn, nỗi sợ hãi |
capabilities |
Kỹ năng và tool mà agent có thể truy cập |
physicality |
Mô tả hình ảnh cho việc tạo ảnh |
history |
Câu chuyện xuất xứ, học vấn, nghề nghiệp |
interests |
Sở thích, điều yêu thích, lối sống |
Xem aieos.org để có schema đầy đủ và ví dụ trực tiếp.
Gateway API
| Endpoint | Phương thức | Xác thực | Mô tả |
|---|---|---|---|
/health |
GET | Không | Kiểm tra sức khỏe (luôn công khai, không lộ bí mật) |
/pair |
POST | Header X-Pairing-Code |
Đổi mã một lần lấy bearer token |
/webhook |
POST | Authorization: Bearer <token> |
Gửi tin nhắn: {"message": "your prompt"}; tùy chọn X-Idempotency-Key |
/whatsapp |
GET | Query params | Xác minh webhook Meta (hub.mode, hub.verify_token, hub.challenge) |
/whatsapp |
POST | Chữ ký Meta (X-Hub-Signature-256) khi app secret được cấu hình |
Webhook tin nhắn đến WhatsApp |
Lệnh
| Lệnh | Mô tả |
|---|---|
onboard |
Cài đặt nhanh (mặc định) |
agent |
Chế độ chat tương tác hoặc một tin nhắn |
gateway |
Khởi động webhook server (mặc định: 127.0.0.1:3000) |
daemon |
Khởi động runtime tự trị chạy lâu dài |
service |
Quản lý dịch vụ nền cấp người dùng |
doctor |
Chẩn đoán trạng thái hoạt động daemon/scheduler/channel |
status |
Hiển thị trạng thái hệ thống đầy đủ |
cron |
Quản lý tác vụ lên lịch (list/add/add-at/add-every/once/remove/update/pause/resume) |
models |
Làm mới danh mục model của provider (models refresh) |
providers |
Liệt kê provider và alias được hỗ trợ |
channel |
Liệt kê/khởi động/chẩn đoán channel và gắn định danh Telegram |
integrations |
Kiểm tra thông tin cài đặt tích hợp |
skills |
Liệt kê/cài đặt/gỡ bỏ skill |
migrate |
Import dữ liệu từ runtime khác (migrate openclaw) |
hardware |
Lệnh khám phá/kiểm tra/thông tin USB |
peripheral |
Quản lý và flash thiết bị ngoại vi phần cứng |
Để có hướng dẫn lệnh theo tác vụ, xem docs/commands-reference.md.
Opt-In Open-Skills
Đồng bộ open-skills của cộng đồng bị tắt theo mặc định. Bật tường minh trong config.toml:
[skills]
open_skills_enabled = true
# open_skills_dir = "/path/to/open-skills" # tùy chọn
Bạn cũng có thể ghi đè lúc runtime với ZEROCLAW_OPEN_SKILLS_ENABLED và ZEROCLAW_OPEN_SKILLS_DIR.
Phát triển
cargo build # Build phát triển
cargo build --release # Build release (codegen-units=1, hoạt động trên mọi thiết bị kể cả Raspberry Pi)
cargo build --profile release-fast # Build nhanh hơn (codegen-units=8, yêu cầu RAM 16GB+)
cargo test # Chạy toàn bộ test suite
cargo clippy --locked --all-targets -- -D clippy::correctness
cargo fmt # Định dạng code
# Chạy benchmark SQLite vs Markdown
cargo test --test memory_comparison -- --nocapture
Hook pre-push
Một git hook chạy cargo fmt --check, cargo clippy -- -D warnings, và cargo test trước mỗi lần push. Bật một lần:
git config core.hooksPath .githooks
Khắc phục sự cố build (lỗi OpenSSL trên Linux)
Nếu bạn gặp lỗi build openssl-sys, đồng bộ dependencies và rebuild với lockfile của repository:
git pull
cargo build --release --locked
cargo install --path . --force --locked
ZeroClaw được cấu hình để dùng rustls cho các dependencies HTTP/TLS; --locked giữ cho dependency graph nhất quán trên các môi trường mới.
Để bỏ qua hook khi cần push nhanh trong quá trình phát triển:
git push --no-verify
Cộng tác & Tài liệu
Bắt đầu từ trung tâm tài liệu để có bản đồ theo tác vụ:
- Trung tâm tài liệu:
docs/README.md - Mục lục tài liệu thống nhất:
docs/SUMMARY.md - Tài liệu tham khảo lệnh:
docs/commands-reference.md - Tài liệu tham khảo cấu hình:
docs/config-reference.md - Tài liệu tham khảo provider:
docs/providers-reference.md - Tài liệu tham khảo channel:
docs/channels-reference.md - Sổ tay vận hành:
docs/operations-runbook.md - Khắc phục sự cố:
docs/troubleshooting.md - Kiểm kê/phân loại tài liệu:
docs/docs-inventory.md - Tổng hợp phân loại PR/Issue (tính đến 18/2/2026):
docs/project-triage-snapshot-2026-02-18.md
Tài liệu tham khảo cộng tác cốt lõi:
- Trung tâm tài liệu: docs/README.md
- Template tài liệu: docs/doc-template.md
- Danh sách kiểm tra thay đổi tài liệu: docs/README.md#4-documentation-change-checklist
- Tài liệu tham khảo cấu hình channel: docs/channels-reference.md
- Vận hành phòng mã hóa Matrix: docs/matrix-e2ee-guide.md
- Hướng dẫn đóng góp: CONTRIBUTING.md
- Chính sách quy trình PR: docs/pr-workflow.md
- Sổ tay người review (phân loại + review sâu): docs/reviewer-playbook.md
- Bản đồ sở hữu và phân loại CI: docs/ci-map.md
- Chính sách tiết lộ bảo mật: SECURITY.md
Cho triển khai và vận hành runtime:
- Hướng dẫn triển khai mạng: docs/network-deployment.md
- Sổ tay proxy agent: docs/proxy-agent-playbook.md
Ủng hộ ZeroClaw
Nếu ZeroClaw giúp ích cho công việc của bạn và bạn muốn hỗ trợ phát triển liên tục, bạn có thể quyên góp tại đây:
🙏 Lời cảm ơn đặc biệt
Chân thành cảm ơn các cộng đồng và tổ chức đã truyền cảm hứng và thúc đẩy công việc mã nguồn mở này:
- Harvard University — vì đã nuôi dưỡng sự tò mò trí tuệ và không ngừng mở rộng ranh giới của những điều có thể.
- MIT — vì đã đề cao tri thức mở, mã nguồn mở, và niềm tin rằng công nghệ phải có thể tiếp cận với tất cả mọi người.
- Sundai Club — vì cộng đồng, năng lượng, và động lực không mệt mỏi để xây dựng những thứ có ý nghĩa.
- Thế giới & Xa hơn 🌍✨ — gửi đến mọi người đóng góp, người dám mơ và người dám làm đang biến mã nguồn mở thành sức mạnh tích cực. Tất cả là dành cho các bạn.
Chúng tôi xây dựng công khai vì ý tưởng hay đến từ khắp nơi. Nếu bạn đang đọc đến đây, bạn đã là một phần của chúng tôi. Chào mừng. 🦀❤️
⚠️ Repository Chính thức & Cảnh báo Mạo danh
Đây là repository ZeroClaw chính thức duy nhất:
Bất kỳ repository, tổ chức, tên miền hay gói nào khác tuyên bố là "ZeroClaw" hoặc ngụ ý liên kết với ZeroClaw Labs đều là không được ủy quyền và không liên kết với dự án này. Các fork không được ủy quyền đã biết sẽ được liệt kê trong TRADEMARK.md.
Nếu bạn phát hiện hành vi mạo danh hoặc lạm dụng nhãn hiệu, vui lòng mở một issue.
Giấy phép
ZeroClaw được cấp phép kép để tối đa hóa tính mở và bảo vệ người đóng góp:
| Giấy phép | Trường hợp sử dụng |
|---|---|
| MIT | Mã nguồn mở, nghiên cứu, học thuật, sử dụng cá nhân |
| Apache 2.0 | Bảo hộ bằng sáng chế, triển khai tổ chức, thương mại |
Bạn có thể chọn một trong hai giấy phép. Người đóng góp tự động cấp quyền theo cả hai — xem CLA.md để biết thỏa thuận đóng góp đầy đủ.
Nhãn hiệu
Tên ZeroClaw và logo là nhãn hiệu của ZeroClaw Labs. Giấy phép này không cấp phép sử dụng chúng để ngụ ý chứng thực hoặc liên kết. Xem TRADEMARK.md để biết các sử dụng được phép và bị cấm.
Bảo vệ người đóng góp
- Bạn giữ bản quyền đối với đóng góp của mình
- Cấp bằng sáng chế (Apache 2.0) bảo vệ bạn khỏi các khiếu nại bằng sáng chế từ người đóng góp khác
- Đóng góp của bạn được ghi nhận vĩnh viễn trong lịch sử commit và NOTICE
- Không có quyền nhãn hiệu nào được chuyển giao khi đóng góp
Đóng góp
Xem CONTRIBUTING.md và CLA.md. Triển khai một trait, gửi PR:
- Hướng dẫn quy trình CI: docs/ci-map.md
Providermới →src/providers/Channelmới →src/channels/Observermới →src/observability/Toolmới →src/tools/Memorymới →src/memory/Tunnelmới →src/tunnel/Skillmới →~/.zeroclaw/workspace/skills/<name>/
ZeroClaw — Không tốn thêm tài nguyên. Không đánh đổi. Triển khai ở đâu cũng được. Thay thế gì cũng được. 🦀
Lịch sử Star