Hướng dẫn NanoClaw: Xây dựng agent nhẹ, ưu tiên cục bộ

Các agent AI tự động đang thay đổi cách con người làm việc với phần mềm. Thay vì chuyển qua lại giữa ứng dụng và công cụ, bạn chỉ cần đưa ra một lệnh văn bản đơn giản và để agent xử lý nhiệm vụ cho bạn. Điều đó có thể bao gồm đặt lời nhắc, hỗ trợ email, hỗ trợ quản lý dự án hoặc trợ giúp viết mã và soạn thảo.

Những công cụ như OpenClaw đã khiến ý tưởng này trở nên thực tế hơn nhiều. Chúng cho thấy điều gì khả thi khi một agent AI luôn sẵn sàng trên laptop hoặc điện thoại của bạn. Đồng thời, các hệ thống agent lớn hơn có thể mang lại cảm giác nặng nề, phức tạp và khó quản lý. Chúng có thể phát sinh lo ngại về bảo mật, yêu cầu thiết lập nhiều hơn và vượt quá nhu cầu của bạn cho một quy trình cục bộ cá nhân.

Đó là lúc NanoClaw xuất hiện. NanoClaw là lựa chọn thay thế nhẹ hơn, ưu tiên cục bộ và dễ chạy cũng như thử nghiệm trên máy của bạn. Sản phẩm cũng được thiết kế chú trọng bảo mật, sử dụng cách ly dựa trên Docker để giữ môi trường của bạn tách biệt và dữ liệu được bảo vệ.

Trong hướng dẫn này, bạn sẽ thiết lập NanoClaw trên Windows bằng WSL và chuẩn bị môi trường theo từng bước. Bạn sẽ cài đặt các công cụ hệ thống cần thiết, thiết lập Node.js, nhân bản kho NanoClaw, kết nối xác thực và chạy dự án cục bộ.

Để so sánh giữa hai công cụ agent, tôi khuyến nghị đọc bài NanoClaw vs OpenClaw của chúng tôi.

1. Thiết lập WSL và môi trường Linux của bạn

Trước khi bắt đầu, bạn cần một PC Windows 10/11 tương đối mới hỗ trợ WSL 2 và ảo hóa phần cứng, có đủ RAM (tối thiểu 4 GB, lý tưởng 8 GB trở lên) và dung lượng đĩa (khoảng 20–30 GB trống) để chạy Docker Desktop và môi trường Ubuntu WSL.

Bắt đầu bằng cách cài đặt WSL trên Windows. Mở PowerShell với quyền Quản trị viên và chạy:

wsl --install

Sau khi cài đặt xong, khởi động lại nếu cần, rồi kiểm tra thiết lập của bạn:

wsl --status

Bạn cần bản phân phối của mình chạy trên WSL 2. Điều này quan trọng vì Claude Code hỗ trợ WSL trên Windows, và Anthropic lưu ý rằng sandboxing hoạt động với WSL 2 trong khi WSL 1 không được hỗ trợ.

Khi WSL đã sẵn sàng, khởi chạy Ubuntu:

wsl

Bên trong Ubuntu, hãy cập nhật hệ thống và cài đặt các công cụ phát triển cơ bản:

sudo apt update && sudo apt upgrade -y
sudo apt install -y build-essential curl git wget

Điều này giúp bạn có một môi trường Linux sạch với các công cụ cốt lõi cần thiết cho các bước tiếp theo.

2. Cài đặt Node.js, Docker và Claude Code

Trước khi cài đặt NanoClaw, bạn cần chuẩn bị các công cụ mà nó phụ thuộc vào. 

Trong phần này, bạn sẽ cài đặt Node.js để dự án có thể chạy các công cụ JavaScript, đảm bảo Docker khả dụng bên trong WSL để NanoClaw sử dụng container cách ly, và cài đặt Claude Code, công cụ bạn sẽ dùng để chạy phần thiết lập có hướng dẫn của NanoClaw.

Cài đặt Node.js với NVM

Cách dễ nhất để cài Node.js trong WSL là dùng NVM, trình quản lý phiên bản Node. Nó giúp bạn quản lý các phiên bản Node sạch sẽ và linh hoạt mà không phụ thuộc vào trình quản lý gói của hệ thống.

Chạy các lệnh sau trong terminal Ubuntu của bạn:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
\. "$HOME/.nvm/nvm.sh"
nvm install 24
node -v
npm -v

Sau đó, bạn sẽ thấy đầu ra tương tự như:

v24.14.1
11.11.0

Node.js là cần thiết vì NanoClaw sử dụng quy trình thiết lập và phụ thuộc dựa trên JavaScript. Cài qua NVM hữu ích vì giúp môi trường của bạn dễ quản lý hơn về sau. Nếu cần chuyển phiên bản hoặc cài lại Node, bạn có thể làm mà không ảnh hưởng đến phần còn lại của thiết lập Linux.

Đảm bảo Docker hoạt động bên trong WSL

NanoClaw chạy an toàn và có kiểm soát hơn bằng cách sử dụng cách ly container dựa trên Docker. Nghĩa là Docker cần được cài trên Windows và kết nối đúng với môi trường WSL của bạn.

Trước tiên, tải Docker Desktop từ trang web Docker và cài đặt trên Windows. Sau đó mở Docker Desktop, vào Settings, đảm bảo bật tùy chọn Use the WSL 2-based engine, và trong Resources → WSL Integration, bật tích hợp cho bản phân phối Ubuntu của bạn.

Sau khi xong, quay lại terminal Ubuntu và chạy:

docker --version
docker ps

Bạn sẽ thấy đầu ra tương tự như sau:

Docker version 29.1.3, build f52814d
CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES

Đây là dấu hiệu tốt. Nó có nghĩa Docker khả dụng trong WSL và sẵn sàng để NanoClaw sử dụng.

Cài đặt Claude Code trong Ubuntu

Khi Node và Docker đã sẵn sàng, bước tiếp theo là cài đặt Claude Code bên trong WSL. Đây là giao diện bạn sẽ dùng để hoàn tất thiết lập có hướng dẫn của NanoClaw.

Chạy:

curl -fsSL https://claude.ai/install.sh | bash

Lệnh này cài Claude Code trực tiếp vào môi trường Ubuntu của bạn.

3. Cài đặt NanoClaw từ mã nguồn

Giờ khi môi trường đã sẵn sàng, đến lúc tải NanoClaw và mở nó trong Claude Code.

Bắt đầu bằng cách nhân bản kho và vào thư mục dự án:

git clone https://github.com/qwibitai/nanoclaw.git
cd nanoclaw

Nếu bạn dự định tùy biến NanoClaw sau này, bạn có thể fork kho trước rồi clone bản của riêng mình. Cho lần thiết lập đầu tiên, clone kho chính là hoàn toàn ổn.

Khi đã ở trong thư mục nanoclaw, chạy:

claude

Lần đầu khởi chạy Claude Code, bạn sẽ được hướng dẫn qua quy trình đăng nhập và cấu hình ban đầu. Bạn có thể đăng nhập bằng tài khoản Claude.ai, hoặc dùng quyền truy cập Anthropic API trực tiếp với khóa API.

Nếu bạn đã có gói đăng ký Claude Pro hoặc Max, quy trình đăng nhập thường là lựa chọn đơn giản nhất. Nếu bạn làm việc với hình thức tính phí qua API, Claude Code cũng có thể được cấu hình để dùng khóa Anthropic API của bạn.

Sau khi đăng nhập hoàn tất, Claude Code sẽ mở bên trong dự án NanoClaw của bạn và bạn sẵn sàng tiếp tục thiết lập.

4. Thiết lập NanoClaw

Với Claude Code đang mở trong thư mục nanoclaw, bạn có thể bắt đầu quá trình thiết lập đầy đủ.

Chạy:

/setup

Lệnh này khởi động quy trình thiết lập có hướng dẫn của NanoClaw.

Những gì diễn ra trong quá trình thiết lập

Khi bạn chạy /setup, Claude Code sẽ bắt đầu chuẩn bị NanoClaw cho bạn. Phần này có thể mất một chút thời gian, vì vậy hãy để nó chạy qua từng giai đoạn.

Đầu tiên, công cụ sẽ cài các phụ thuộc của dự án và kiểm tra môi trường cục bộ của bạn đã sẵn sàng chưa. 

Sau đó, nó chuyển sang giai đoạn thiết lập container, nơi chạy các lệnh Docker cần thiết để dựng container tùy chỉnh của NanoClaw và kiểm tra xem nó khởi động đúng không.

Khi container được dựng và xác minh, quá trình thiết lập tiếp tục bằng cách cài OneCLI. Đây là một phần quan trọng trong stack của NanoClaw vì nó giúp quản lý bí mật và quyền truy cập container an toàn hơn.

Sau khi hoàn tất, bạn có thể mở bảng điều khiển Docker Desktop và xác nhận các container đang chạy. Lúc này, bạn sẽ thấy các dịch vụ NanoClaw xuất hiện ở đó, bao gồm container ứng dụng và các dịch vụ hỗ trợ như PostgreSQL.

Thiết lập token Claude cho OneCLI

Mặc dù Claude Code đã đăng nhập trong WSL, container NanoClaw cần cách riêng, an toàn để truy cập Claude. Để làm vậy, bạn cần tạo một token và đăng ký nó với OneCLI.

Mở một terminal mới và chạy:

claude setup-token

Lệnh này sẽ tạo một liên kết để bạn mở trong trình duyệt. Đăng nhập, phê duyệt yêu cầu, rồi dán mã trả về vào terminal. Sau đó, Claude Code sẽ cung cấp cho bạn một token.

Sao chép token đó, rồi chạy lệnh sau trong terminal, thay YOUR_TOKEN bằng token bạn vừa tạo:

onecli secrets create --name Anthropic --type anthropic --value YOUR_TOKEN --host-pattern api.anthropic.com

Bước này giúp container NanoClaw truy cập Claude một cách an toàn mà không để lộ trực tiếp thông tin xác thực của bạn bên trong container. Khi xong, quá trình thiết lập sẵn sàng cho giai đoạn tiếp theo.

5. Thiết lập WhatsApp cho NanoClaw

Sau khi phần thiết lập chính hoàn tất, Claude Code sẽ chuyển sang giai đoạn thiết lập kênh. Đây là nơi bạn chọn cách tương tác với NanoClaw.

Tạo mã QR cho WhatsApp

Chọn WhatsApp (bạn cũng có thể chọn các kênh khác được hỗ trợ như Discord, Telegram hoặc Slack để dùng sau, nhưng hiện tại chúng ta sẽ tập trung vào WhatsApp), rồi tiếp tục.

Vì một lý do nào đó, mã QR trong trình duyệt không hoạt động với tôi. Có vẻ là do sự cố mạng giữa WSL và trình duyệt, có thể liên quan đến cách truy cập cổng cục bộ. Vì vậy, chúng ta sẽ dùng tùy chọn mã QR trong terminal thay thế.

Claude Code sẽ cố hiển thị mã QR trong terminal. Trong một số trường hợp, mã QR này có thể bị cắt hoặc hiển thị không đúng.

Để khắc phục, mở một terminal mới, rồi chạy:

cd nanoclaw
npm run auth

Lệnh này sẽ tạo một mã QR hiển thị rõ ràng trong terminal.

Kết nối WhatsApp trên điện thoại của bạn

Giờ hãy mở WhatsApp trên điện thoại và làm theo các bước sau:

• Vào Cài đặt
• Nhấn Thiết bị đã liên kết
• Nhấn Liên kết thiết bị
• Quét mã QR hiển thị trong terminal của bạn

Khi quét thành công, tài khoản WhatsApp của bạn sẽ được kết nối với NanoClaw.

Sau khi ghép nối, bạn sẽ thấy thông báo thành công trong terminal.

Hoàn tất thiết lập kênh trong Claude Code

Quay lại terminal Claude Code ban đầu của bạn và tiếp tục thiết lập.

Bạn sẽ được hỏi một vài câu cấu hình. Tạm thời, bạn có thể chọn các tùy chọn được khuyến nghị.

• Giữ từ kích hoạt mặc định
• Giữ tên trợ lý mặc định
• Chọn chế độ tự trò chuyện

Chế độ tự trò chuyện nghĩa là NanoClaw chỉ phản hồi bạn trong chính cuộc trò chuyện WhatsApp của bạn. Điều này hữu ích để thử nghiệm, vì không ai khác có thể tương tác với agent của bạn.

Hoàn tất thiết lập và kiểm thử

Khi mọi thứ đã được cấu hình, NanoClaw sẽ dựng lại container với cài đặt mới. Việc này có thể mất một lúc.

Sau đó, bạn sẽ thấy hướng dẫn cách sử dụng NanoClaw.

Để thử:

• Mở WhatsApp
• Tìm cuộc trò chuyện với chính số điện thoại của bạn (self chat)
• Gửi một tin nhắn như:

@Andy hello

Nếu mọi thứ hoạt động đúng, NanoClaw sẽ phản hồi trong cuộc trò chuyện của bạn.

6. Kiểm thử NanoClaw với WhatsApp

Bây giờ mọi thứ đã được thiết lập, bạn có thể kiểm thử NanoClaw trực tiếp từ WhatsApp.

Mở WhatsApp trên điện thoại và vào cuộc trò chuyện với chính bạn. Cuộc trò chuyện này sẽ hiển thị số của bạn với “(Bạn)” trong ngoặc. Bắt đầu với một tin nhắn đơn giản như:

@Andy how are you?

Trong vài giây, NanoClaw sẽ phản hồi trong cuộc trò chuyện. Điều này xác nhận thiết lập của bạn hoạt động đúng và agent đã kết nối với WhatsApp.

Bạn cũng có thể thử cách hoạt động của từ kích hoạt. Hãy thử gửi tin nhắn không kèm từ kích hoạt, chẳng hạn:

How are you?

Bạn sẽ thấy NanoClaw không phản hồi. Đây là hành vi mong đợi. Từ kích hoạt đảm bảo agent chỉ hoạt động khi bạn gọi rõ ràng.

Khi nhắn tin cơ bản đã hoạt động, bạn có thể thử một tác vụ nâng cao hơn. Ví dụ, hãy hỏi:

@Andy Tell me the latest gold and silver prices and should i buy it or not

NanoClaw sẽ thực hiện tác vụ và trả về phản hồi có cấu trúc. Điều này cho thấy agent của bạn không chỉ trả lời tin nhắn mà còn có thể thực hiện các tác vụ nhiều bước và cung cấp kết quả hữu ích khi được cấu hình với các công cụ phù hợp, như tìm kiếm web.

Đến thời điểm này, thiết lập NanoClaw của bạn đã hoạt động đầy đủ và sẵn sàng cho các trường hợp sử dụng nâng cao hơn.

Giá vàng và bạc không chính xác, cho thấy nó thực sự không thực hiện tìm kiếm web mà thay vào đó dựa trên thông tin lỗi thời trong kiến thức tích hợp của mô hình.

Suy nghĩ cuối

Thiết lập NanoClaw mất nhiều thời gian hơn tôi mong đợi, đặc biệt trên Windows với WSL. Giữa Docker, thiết lập container, nhiều dịch vụ hỗ trợ và số lượng quyền tôi phải liên tục phê duyệt trong Claude Code, quy trình này cảm giác nặng nề hơn so với một agent nhẹ ưu tiên cục bộ. Sau một thời gian, các lời nhắc và phê duyệt liên tục trở nên mệt mỏi, và trải nghiệm thiết lập tổng thể không thân thiện với người mới.

Quy trình cài đặt cũng không mượt như tôi kỳ vọng. Ở vài thời điểm, Claude Code yêu cầu tôi mở terminal mới, chạy các lệnh xác thực bổ sung, tạo token và đăng ký thủ công với OneCLI. Nếu bạn mới với công cụ AI, container hoặc quy trình dòng lệnh, phần này có thể nhanh chóng gây rối. Có thể làm được, nhưng đòi hỏi nhiều thao tác thủ công hơn so với kỳ vọng của nhiều người dùng.

Vì vậy, cá nhân tôi thích Nanobot hơn. Tôi chỉ mất vài phút để bắt đầu nhắn tin với agent qua WhatsApp, và trải nghiệm nhanh hơn, trực tiếp hơn nhiều. Với NanoClaw, tỷ lệ công sức-bù đắp không thực sự thuyết phục.

Trải nghiệm WhatsApp cũng cần cải thiện. Phản hồi có hoạt động, nhưng tương tác còn thô. Không có chỉ báo đang gõ hoặc đang trả lời rõ ràng, và bong bóng phản hồi trông giống hệt tin nhắn của tôi, khiến cuộc trò chuyện kém tự nhiên. Sự phân biệt trực quan rõ ràng hơn và một số phản hồi cho biết agent đang xử lý sẽ tạo khác biệt lớn, đặc biệt khi câu trả lời mất thời gian.

Tổng thể, tôi vẫn nghĩ ý tưởng phía sau NanoClaw là đúng hướng. Một agent nhẹ, an toàn, ưu tiên cục bộ là hướng đi rất hữu ích. Nhưng trên thực tế, thiết lập phức tạp hơn dự kiến, và trải nghiệm cuối cùng hơi hụt so với lượng công sức bỏ ra để đạt được.