ZeroClaw là trợ lý AI mã nguồn mở viết bằng Rust, chạy trên máy của bạn dưới dạng một file chương trình duy nhất. Bạn cấu hình nó nói chuyện với một mô hình AI (Claude, GPT, Gemini, mô hình chạy trên máy…), nối với Telegram, Discord, email hay dòng lệnh, và cho nó dùng công cụ như shell, trình duyệt, HTTP, thậm chí phần cứng như Raspberry Pi.
Bài này là hướng dẫn từ A–Z cho người mới: ZeroClaw là gì, khác OpenClaw thế nào, chi phí, cách cài trên macOS, Linux, Windows, thiết lập lần đầu bằng quickstart, ba mức quyền tự chủ, nối Telegram, các file cấu hình, skills, MCP, lệnh hay dùng, bảo mật và lỗi thường gặp. Thông tin đối chiếu với kho mã chính thức và tài liệu đi kèm ngày 7/11/2026, bản phát hành mới nhất lúc đó là v0.8.7 (27/10/2026). Dự án đổi rất nhanh; khi lệnh trong bài khác với máy bạn, hãy tin tài liệu chính thức.
ZeroClaw là gì?
Theo tài liệu dự án, ZeroClaw là một agent runtime: một file chương trình bạn cấu hình rồi cho chạy. Nó gồm ba phần:
Nhà cung cấp mô hình (provider): Anthropic, OpenAI, Ollama và khoảng 20 nhà cung cấp khác, cộng mọi dịch vụ tương thích chuẩn OpenAI. Có thể cấu hình mô hình dự phòng để tác tử vẫn chạy khi một nhà cung cấp gặp sự cố.
Kênh (channel): hơn 30 kênh như Telegram, Discord, Slack, Matrix, Signal, WhatsApp, email, webhook, giọng nói và dòng lệnh. Một tác tử trả lời được trên nhiều kênh cùng lúc.
Công cụ (tool): shell, trình duyệt, HTTP, tìm kiếm web, đọc ghi file, phần cứng, và máy chủ MCP bạn tự thêm.
Câu khẩu hiệu của dự án là "bạn sở hữu tác tử, sở hữu dữ liệu, sở hữu cái máy nó chạy". ZeroClaw không có bản chạy trên mây, không có hệ thống tài khoản, không thu phí. Nó cũng không phải framework để viết ứng dụng: bạn cấu hình và nối kênh, không lập trình trên nó.
Dự án dùng giấy phép kép MIT hoặc Apache 2.0, do cộng đồng phát triển. README chính thức ghi người tạo ban đầu là tài khoản GitHub theonlyhennygod, trưởng dự án là JordanTheJet.

ZeroClaw khác OpenClaw thế nào?
Hai dự án cùng ý tưởng: một trợ lý AI tự chạy trên máy bạn, nhắn qua ứng dụng chat. Khác biệt nằm ở cách làm và ưu tiên:
| ZeroClaw | OpenClaw | |
|---|---|---|
| Viết bằng | Rust, một file chương trình duy nhất | Node.js, cần Node 24 hoặc 26 |
| Mặc định về quyền | Việc rủi ro vừa phải hỏi bạn duyệt, việc rủi ro cao bị chặn | Thiết lập nhanh cho toàn quyền; bảo vệ chủ yếu ở lớp ghép đôi và danh sách cho phép |
| File cấu hình | Một file TOML: ~/.zeroclaw/config.toml | File JSON5: ~/.openclaw/openclaw.json |
| Zalo | Chưa có kênh Zalo trong danh sách chính thức | Có kênh Zalo chính thức và plugin Zalo ClawBot |
| Phần cứng | Hỗ trợ GPIO, I2C, SPI, USB trên Raspberry Pi, STM32, Arduino, ESP32 | Điều khiển thiết bị qua các "node" như máy Mac, điện thoại |
| Hệ sinh thái | Nhỏ hơn, thiên về kỹ thuật | Lớn hơn, có kho ClawHub, ứng dụng desktop |
Chọn nhanh: người mới, cần Zalo hoặc muốn nhiều hướng dẫn cộng đồng thì chọn OpenClaw. Người quen dòng lệnh, muốn chương trình gọn, kiểm soát quyền chặt ngay từ đầu, chạy trên máy cấu hình thấp hoặc điều khiển phần cứng thì cân nhắc ZeroClaw.
ZeroClaw có miễn phí không? Chi phí thực tế
Phần mềm miễn phí. Tiền bạn trả nằm ở:
Mô hình AI: khóa API trả theo mức dùng, hoặc dùng gói thuê bao bạn đã có. Tài liệu hướng dẫn cách dùng gói ChatGPT/Codex (đăng nhập, không cần khóa API) và gói Claude Max (lấy token bằng lệnh
claude setup-tokencủa Claude Code). Muốn không tốn tiền mô hình thì chạy mô hình trên máy qua Ollama, đổi lại chất lượng thấp hơn và cần máy mạnh.Máy chạy: máy tính đang dùng, một Raspberry Pi hay máy cũ ở nhà, hoặc VPS nếu cần chạy 24/7.
Điểm hay của ZeroClaw: nó ghi lại mọi lần gọi mô hình vào sổ chi phí, tính theo từng tác tử, và cho đặt ngân sách theo ngày và theo tháng trong mục [cost] của file cấu hình. Bảng giá từng mô hình do bạn khai, nên hãy cập nhật theo trang giá của nhà cung cấp.
Cần máy thế nào?
Hệ điều hành: Linux (mọi bản phân phối), macOS (Intel và Apple Silicon), Windows 10/11, FreeBSD, NixOS; có bản Docker và bản cho Android.
Cài bản dựng sẵn: không cần cài Rust. Đây là cách nên dùng.
Tự biên dịch từ mã nguồn: cần Rust (cài bằng
rustup); trên Windows cần thêm Visual Studio Build Tools. Biên dịch tốn RAM, máy yếu có thể bị tràn bộ nhớ (xem mục lỗi).Tính năng thêm: công cụ trình duyệt tự tải Chromium khi dùng lần đầu; điều khiển GPIO cần chạy trên bo mạch như Raspberry Pi.
Chỉ tải ZeroClaw từ github.com/zeroclaw-labs/zeroclaw và trang zeroclaw.com. README chính thức nói rõ đây là kho duy nhất; mọi kho, tên miền hay gói khác tự nhận là ZeroClaw đều không thuộc dự án.
Cách cài đặt ZeroClaw
macOS và Linux: script chính thức
curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | shScript ưu tiên tải bản dựng sẵn phù hợp với máy, chỉ biên dịch từ mã nguồn khi không có bản phù hợp (và tự cài Rust nếu cần). Script chạy không hỏi gì, cập nhật đường dẫn trong file cấu hình shell, rồi nhắc bạn chạy zeroclaw quickstart. Đóng mở lại Terminal để đường dẫn mới có hiệu lực.
Muốn được hỏi từng lựa chọn (bản dựng sẵn hay tự biên dịch, chọn tính năng), tải mã nguồn về rồi chạy script có hướng dẫn:
git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
./install.shmacOS: Homebrew
brew install zeroclawLưu ý: cài bằng Homebrew thì dữ liệu nằm ở $HOMEBREW_PREFIX/var/zeroclaw/ thay vì ~/.zeroclaw/. Tài liệu khuyên thêm dòng export ZEROCLAW_WORKSPACE="$HOMEBREW_PREFIX/var/zeroclaw" vào file cấu hình shell để dòng lệnh và dịch vụ chạy nền dùng chung một chỗ.
Windows
Cách khuyên dùng là bản dựng sẵn qua PowerShell, không cần Rust: hướng dẫn Windows trong kho mã có sẵn một đoạn lệnh PowerShell tải bản mới nhất, giải nén vào %USERPROFILE%\.zeroclaw\bin, thêm vào PATH rồi tự chạy quickstart. Đoạn lệnh khá dài và được tạo tự động theo từng bản phát hành, nên hãy chép nguyên văn từ trang hướng dẫn Windows thay vì chép từ bài viết khác.
Nếu bạn dùng Scoop:
scoop bucket add zeroclaw https://github.com/zeroclaw-labs/scoop-zeroclaw
scoop install zeroclawNếu đã có WSL2, có thể làm theo hướng dẫn Linux; script cài chạy được trong WSL. File chạy chưa được ký số nên Windows SmartScreen có thể chặn khi mở bằng cách bấm đúp; chạy từ PowerShell thường không gặp.
Trang Releases của bản v0.8.7 còn có các gói cài .msi, .exe (Windows), .dmg (macOS), .deb và AppImage (Linux). Tài liệu hiện vẫn hướng dẫn chủ yếu theo các cách ở trên.
Kiểm tra cài đặt
zeroclaw --version
zeroclaw doctorBáo command not found thì đường dẫn chưa được nạp: mở lại Terminal, hoặc thêm ~/.cargo/bin vào PATH nếu bạn cài bằng Cargo.
Thiết lập lần đầu với quickstart
zeroclaw quickstartQuickstart hỏi lần lượt từng bước rồi ghi ra một file cấu hình chạy được. Bước có dấu bắt buộc phải xong mới tạo được tác tử:
| Bước | Bắt buộc | Bạn chọn gì |
|---|---|---|
| Model provider | Có | Nhà cung cấp (Anthropic, OpenAI, Ollama, OpenRouter…), khóa API hoặc cách đăng nhập, và mô hình |
| Risk profile | Có | Mức tự chủ và hộp cách ly: readonly, supervised (mặc định) hoặc full |
| Memory | Có | Nơi lưu trí nhớ: sqlite, markdown, postgres, qdrant, lucid hoặc none |
| Channels | Không | Telegram, Discord, Slack… (kênh dòng lệnh luôn có sẵn, thêm sau cũng được) |
| Peer groups | Không | Nhóm người được phép nhắn, dùng khi có nhiều tác tử |
| Agent | Có | Tên (alias) của tác tử, lời dặn hệ thống, file tính cách |
Với người mới, nên chọn SQLite cho bộ nhớ (không cần cài gì thêm) và giữ mức supervised. Quickstart cũng chạy được trong giao diện Terminal zerocode và trên bảng điều khiển web; cả ba cho ra cùng một cấu hình.
Quickstart không ghi đè cấu hình đã có. Muốn làm lại từ đầu, tài liệu hướng dẫn xóa thư mục ~/.zeroclaw rồi chạy lại; sao lưu thư mục này trước nếu đã có dữ liệu bạn muốn giữ.
Dùng gói ChatGPT hoặc Claude thay cho khóa API
# Đã đăng nhập Codex CLI trên máy:
zeroclaw auth login --model-provider openai-codex --import ~/.codex/auth.json
# Gói Claude Max: lấy token bằng Claude Code rồi dán vào bước Authentication
claude setup-tokenPhần dùng qua gói thuê bao bị trừ vào hạn mức của gói. Điều khoản dùng gói trong công cụ bên ngoài do nhà cung cấp quy định và có thể thay đổi, nên đọc trang hỗ trợ của họ trước khi dựa vào.
Phiên làm việc đầu tiên: từng bước
Trò chuyện trong Terminal:
zeroclaw agent -a <tên-tác-tử>, thay bằng tên bạn đặt ở bước Agent.Giao việc an toàn trước: "Đọc file bao-gia.csv trong workspace, tính tổng theo từng khách hàng, trả lời bằng tiếng Việt."
Xem cách nó xin phép: nhờ ghi một file mới. Ở mức supervised, nó sẽ hỏi bạn duyệt trước khi ghi.
Cho chạy nền:
zeroclaw service install zeroclaw service startLệnh này đăng ký ZeroClaw thành dịch vụ hệ thống: systemd trên Linux, LaunchAgent trên macOS, dịch vụ hoặc tác vụ theo lịch trên Windows.
Nối Telegram theo mục bên dưới để nhắn từ điện thoại.
Ba mức tự chủ: tác tử được làm gì
Đây là điểm mạnh nhất của ZeroClaw. Mỗi tác tử gắn với một risk profile, trong đó có mức tự chủ:
| Mức | Cách hoạt động | Khi nào dùng |
|---|---|---|
readonly | Chỉ xem: đọc file, tìm trong bộ nhớ, tìm web, gọi HTTP dạng GET. Không sửa gì | Bot hỏi đáp công khai, tác tử chỉ phân tích |
supervised (mặc định) | Việc rủi ro thấp chạy luôn; rủi ro vừa (ghi file trong workspace, lệnh shell được phép, gửi POST) phải hỏi bạn; rủi ro cao bị chặn | Hầu hết trường hợp |
full | Chạy mọi việc không hỏi, trừ công cụ bạn liệt kê trong always_ask; vẫn chặn các đường dẫn cấm và vẫn chịu hộp cách ly | Máy thử nghiệm, quy trình tự động đã kiểm kỹ |
Yêu cầu duyệt được gửi qua chính kênh bạn đang nhắn: Telegram hiện nút bấm, CLI hỏi ngay trong Terminal. Không trả lời trong 120 giây (mặc định) thì coi như từ chối.
Mặc định, tác tử chỉ được đụng vào thư mục workspace (~/.zeroclaw/workspace/), các thư mục nhạy cảm như /etc, ~/.ssh bị chặn, lệnh shell lạ bị chặn, và khóa bí mật trong biến môi trường không tự động chuyển cho lệnh shell. Hộp cách ly ở cấp hệ điều hành dùng Landlock, Bubblewrap, Seatbelt hoặc Docker tùy máy. Mỗi hành động còn có "biên nhận" mã hóa để kiểm tra lại về sau.
Chế độ YOLO tắt toàn bộ các lớp bảo vệ trên. Tài liệu chỉ khuyên dùng cho máy thử nghiệm hoặc máy ảo dùng xong bỏ, tuyệt đối không dùng trên laptop có email, mật khẩu, khóa SSH, hay trên VPS đang phục vụ khách. Tài liệu ví von: một tác tử YOLO nối với bot Telegram công khai chẳng khác gì cho cả Telegram quyền quản trị máy bạn.
Cần dừng khẩn cấp mọi thao tác đang chạy: zeroclaw estop.
Nối Telegram
Telegram dùng cơ chế hỏi tin liên tục (long polling), nên không cần mở cổng hay có địa chỉ công khai.
Tạo bot: nhắn @BotFather trong Telegram, gõ
/newbot, đặt tên, chép token. Giữ token như mật khẩu.Đưa token vào ZeroClaw bằng lời nhắc nhập ẩn (token được lưu mã hóa, không dán thẳng vào file cấu hình):
zeroclaw config set channels.telegram.home.bot_token zeroclaw config set channels.telegram.home.enabled trueỞ đây
homelà tên bạn tự đặt cho bot này.Gắn kênh vào tác tử: xem tên tác tử bằng
zeroclaw agents list, rồi chạyzeroclaw config set agents.<tên-tác-tử>.channelsvà thêmtelegram.homevào danh sách.Khởi động:
zeroclaw daemon(hoặczeroclaw service restartnếu đã cài chạy nền). Lần đầu, ZeroClaw in ra một mã ghép đôi dùng một lần.Ghép đôi: từ tài khoản Telegram của bạn, nhắn cho bot
/bind <mã>. ZeroClaw lưu ID của bạn vào danh sách được phép; người khác nhắn sẽ chỉ nhận thông báo từ chối.Kiểm tra:
zeroclaw channel doctorvàzeroclaw service logs --follow.
Đừng đặt external_peers = ["*"] cho bot riêng tư: lựa chọn này cho phép bất kỳ ai tìm thấy bot đều điều khiển được tác tử và mọi công cụ nó có quyền dùng.
File cấu hình và workspace
Toàn bộ cấu hình nằm trong một file TOML: ~/.zeroclaw/config.toml. Một cấu hình tối thiểu có bốn phần: nhà cung cấp mô hình, tác tử trỏ tới nhà cung cấp đó, mức rủi ro của tác tử, và số phiên bản cấu hình. Bạn có thể sửa bằng lệnh zeroclaw config set, bằng zerocode, hoặc trên bảng điều khiển web, thay vì sửa tay.
Trong workspace, tác tử đọc các file Markdown quen thuộc: AGENTS.md (quy tắc làm việc), SOUL.md (giọng điệu), USER.md (về bạn), IDENTITY.md, TOOLS.md, MEMORY.md. Lưu ý quan trọng từ tài liệu: mặc định mỗi file chỉ được nạp 6.000 ký tự đầu. Quy tắc viết ở cuối một file AGENTS.md dài có thể bị bỏ qua. Chạy zeroclaw doctor để biết file nào bị cắt, và đặt quy tắc quan trọng lên đầu.
Ví dụ AGENTS.md ngắn cho trợ lý văn phòng:
# Quy tắc
- Luôn trả lời bằng tiếng Việt, ngắn gọn.
- Không gửi email hay tin nhắn ra ngoài khi chưa được duyệt.
- Không xóa file; cần dọn thì chuyển vào thư mục _thung-rac.
- Số liệu phải ghi rõ lấy từ file nào.Khi kiểm tra cú pháp file TOML, có thể dùng công cụ chuyển đổi TOML; khóa API để trong biến môi trường hoặc lời nhắc nhập ẩn, rà file .env bằng công cụ kiểm tra file .env.
Skills, MCP và quy trình tự động (SOP)
Skills là bộ hướng dẫn tái sử dụng (file SKILL.md hoặc SKILL.toml), ví dụ checklist rà soát, quy trình triển khai, kịch bản chăm sóc khách. Skill để trong workspace của từng tác tử hoặc trong "bundle" dùng chung.
zeroclaw skills list
zeroclaw skills audit ./ten-skill
zeroclaw skills install ./ten-skill --bundle opsChạy skills audit trước khi cài skill lấy từ nguồn khác.
MCP cho phép nối tác tử với máy chủ MCP bên ngoài (cơ sở dữ liệu, Google Drive, công cụ nội bộ…) như một công cụ. Xem thêm bài Claude Code để hiểu MCP hoạt động thế nào.
SOP (Standard Operating Procedure) là quy trình tự chạy khi có sự kiện: theo lịch (cron), webhook, tin MQTT, thay đổi file, tín hiệu từ phần cứng. Mỗi bước có thể đặt cổng duyệt, và quy trình dừng giữa chừng có thể chạy tiếp.
Điều khiển phần cứng
ZeroClaw là một trong ít trợ lý AI hỗ trợ phần cứng: GPIO, I2C, SPI, USB trên Raspberry Pi, STM32, Arduino và ESP32. Trên Raspberry Pi, tài liệu hướng dẫn biên dịch kèm tính năng phần cứng bằng ./install.sh --source --features hardware, bật giao diện SPI/I2C và đưa người dùng chạy dịch vụ vào các nhóm gpio, spi, i2c. Mỗi loại bo mạch có trang hướng dẫn riêng trong mục Hardware của tài liệu.
Lệnh hay dùng

Tài liệu tham chiếu lệnh của ZeroClaw được tạo tự động từ mã nguồn mỗi lần build, nên luôn khớp với bản bạn đang chạy. Gõ zeroclaw --help hoặc zeroclaw <lệnh> --help để xem đầy đủ.
Bảng điều khiển web
Bản phát hành chuẩn có cổng gateway và bảng điều khiển web để chat, xem bộ nhớ, sửa cấu hình, quản lý lịch và xem công cụ. Gateway mặc định chỉ nghe trên máy (127.0.0.1, cổng 42617) và yêu cầu ghép đôi. Kiểm tra gateway còn sống: curl -sv http://localhost:42617/health. Đừng mở cổng này ra Internet; cần dùng từ xa thì đi qua SSH hoặc mạng riêng.
Cập nhật và gỡ cài đặt
Cập nhật: zeroclaw update, cài bằng Homebrew thì brew update && brew upgrade zeroclaw. Sau đó khởi động lại dịch vụ bằng zeroclaw service restart.
Gỡ cài đặt:
zeroclaw service stop
zeroclaw service uninstall
./install.sh --uninstall # nếu cài bằng script, chạy trong thư mục mã nguồn
brew uninstall zeroclaw # nếu cài bằng HomebrewDữ liệu và cấu hình ở ~/.zeroclaw không tự xóa; sao lưu hoặc xóa tay tùy nhu cầu.
Lỗi thường gặp
| Hiện tượng | Nguyên nhân | Cách xử lý |
|---|---|---|
zeroclaw: command not found | PATH chưa cập nhật | Mở lại Terminal; cài bằng Cargo thì thêm ~/.cargo/bin vào PATH |
| Biên dịch bị treo, hết RAM | Máy yếu (Raspberry Pi, VPS nhỏ) | Dùng bản dựng sẵn ./install.sh --prebuilt, hoặc CARGO_BUILD_JOBS=1, thêm swap |
| Quickstart không chạy lại được | Đã có cấu hình, quickstart không ghi đè | Sao lưu rồi xóa ~/.zeroclaw, chạy lại |
| Cài bằng Homebrew, CLI không thấy cấu hình | Dữ liệu nằm ở $HOMEBREW_PREFIX/var/zeroclaw | Đặt biến ZEROCLAW_WORKSPACE như mục cài đặt |
Telegram báo terminated by other getUpdates request | Hai tiến trình cùng dùng một token bot | Tắt bớt, chỉ giữ một zeroclaw daemon |
| Tác tử bỏ qua quy tắc cuối AGENTS.md | File bị cắt ở 6.000 ký tự | Rút gọn file, đưa quy tắc chính lên đầu; kiểm tra bằng zeroclaw doctor |
| Không mở được gateway | Daemon chưa chạy hoặc đổi cổng | curl -sv http://localhost:42617/health, xem mục [gateway] trong cấu hình |
| Daemon chạy rồi tự tắt | Lỗi cấu hình | zeroclaw doctor, zeroclaw service logs --follow |
Lưu ý an toàn
Giữ mức supervised cho tác tử nối với kênh chat; chỉ dùng full hay YOLO trên máy thử nghiệm.
Tác tử phục vụ người ngoài nên là một tác tử riêng ở mức readonly, tách khỏi tác tử cá nhân của bạn.
Đặt ngân sách trong mục
[cost]và giới hạn chi tiêu trong tài khoản API.Cập nhật thường xuyên và chỉ tải từ kho chính thức.
Nội dung web, email có thể chứa lệnh cài cắm (prompt injection): đừng để tác tử tự đọc nội dung lạ rồi tự hành động với quyền cao.
Học ZeroClaw ở đâu
Nguồn chính thức: kho mã trên GitHub (README, mục Quick start và Philosophy) và trang tài liệu docs.zeroclaw.com. Kênh trao đổi trực tiếp với nhóm phát triển là Discord của dự án, liên kết có trong README.
Muốn so sánh với các công cụ khác: OpenClaw cho trợ lý cá nhân có Zalo, Paperclip AI để điều phối nhiều tác tử, Claude Code và Cursor để viết code. Nếu bạn muốn dùng AI để tự làm sản phẩm, bắt đầu với hướng dẫn tự học vibe code từ A–Z, và đọc checklist rủi ro khi vibe code trước khi cho tác tử AI chạm vào dữ liệu thật.
Muốn học có người kèm? Tấn Phát Digital có khóa học vibe code cho người mới, học online qua Zoom hoặc Google Meet trong 3 ngày, học phí 10 triệu đồng. Hết khóa, mỗi học viên có một website giới thiệu nhiều trang chạy trên tên miền riêng, có form liên hệ, đã đưa lên Google, và biết cách tự sửa nội dung, tự thêm tính năng bằng AI. Liên hệ Tấn Phát Digital để hỏi lịch khai giảng.












