OpenClaw là một công cụ cục bộ cho phép AI agent của bạn kết nối với các ứng dụng như Telegram hoặc WhatsApp và thực hiện hành động, chẳng hạn gửi tin nhắn hoặc xử lý tác vụ. Việc thiết lập khá đơn giản khi bạn nắm được quy trình. Hướng dẫn này bao quát cách cài đặt trên macOS, Linux và Windows.
Tổng quan nhanh về các lựa chọn thiết lập OpenClaw
Chọn cách thiết lập phù hợp với nhu cầu của bạn. Chạy OpenClaw cục bộ giúp mọi thứ ở trên máy của bạn và cần cài các phụ thuộc như npm hoặc dùng script tự động. Nếu muốn bỏ qua bước thiết lập, các nền tảng được lưu trữ hoàn toàn như Kimi Claw sẽ lo môi trường cho bạn, để bạn có thể bắt đầu ngay.
| macOS / Linux | Windows | |
|---|---|---|
| Chạy cục bộ | Lệnh Terminal một dòng | Lệnh PowerShell một dòng |
| Qua npm | Qua npm | |
| Qua Homebrew | Qua WSL2 | |
| Chạy trực tuyến | Giải pháp dựa trên đám mây (ví dụ: Kimi Claw) | Giải pháp dựa trên đám mây (ví dụ: Kimi Claw) |
Cách cài đặt OpenClaw trên macOS và Linux
macOS và Linux dùng chung trình cài đặt và các lệnh. Các hướng dẫn này áp dụng cho cả hai hệ thống, trừ khi có ghi chú khác.
Dưới đây là hướng dẫn thiết lập nhanh. Để xem phần hướng dẫn đầy đủ từng bước kèm ảnh chụp màn hình, xem Cách cài đặt OpenClaw trên macOS.
Phương pháp 1: Dùng script cài đặt một dòng
Bước 1: Chạy script cài đặt trong Terminal
Chạy script cài đặt chính thức để thiết lập OpenClaw. Script sẽ kiểm tra xem Node.js 22 trở lên đã được cài chưa. Nếu thiếu hoặc đã lỗi thời, Node.js 24 sẽ được cài tự động. Sau đó, script cài OpenClaw CLI và khởi chạy trình hướng dẫn onboarding.
Bước 2: Hoàn tất trình hướng dẫn onboarding
Làm theo trình hướng dẫn onboarding để thiết lập môi trường agent của bạn, bao gồm chọn nhà cung cấp mô hình (ví dụ: Kimi API), nhập API key, chọn kênh và cấu hình các thiết lập cơ bản.
Bước 3: Kiểm tra bản cài đặt
Chạy lệnh sau để xác nhận phiên bản OpenClaw của bạn.
Bước 4: Xác minh gateway và hoàn tất thiết lập
Chạy lệnh sau để kiểm tra gateway OpenClaw đang hoạt động.
Trình cài đặt cũng đăng ký LaunchAgent trên macOS hoặc dịch vụ systemd trên Linux, để OpenClaw tiếp tục chạy trong nền. Khi mọi thứ đã được thiết lập, agent của bạn đã sẵn sàng sử dụng. Bạn có thể bắt đầu trò chuyện, kết nối công cụ hoặc cấu hình quy trình làm việc theo nhu cầu.
Phương pháp 2: Cài đặt bằng Homebrew
Bước 1: Cài đặt hoặc nâng cấp Node.js
Dùng Homebrew để cài Node.js bằng cách chạy lệnh sau trong Terminal. Nếu Node.js đã được cài, hãy chạy lệnh nâng cấp để bảo đảm bạn đang dùng phiên bản mới nhất.
Bước 2: Cài đặt OpenClaw CLI
Chạy lệnh sau để cài đặt OpenClaw CLI trên toàn hệ thống.
Bước 3: Chạy onboarding và thiết lập daemon
Chạy lệnh sau để khởi chạy trình hướng dẫn onboarding và đăng ký daemon nền. Làm theo trình hướng dẫn để cấu hình môi trường agent của bạn, bao gồm chọn nhà cung cấp mô hình (ví dụ: Kimi API), nhập API key và kết nối kênh nhắn tin. Sau khi thiết lập xong, agent của bạn đã sẵn sàng sử dụng. Bạn có thể bắt đầu trò chuyện, kết nối công cụ hoặc cấu hình quy trình làm việc theo nhu cầu.
Phương pháp 3: Cài đặt bằng npm
Bước 1: Xác minh phiên bản runtime
Chạy lệnh sau để bảo đảm Node.js 22.14 trở lên đã được cài trên hệ thống. Nếu phiên bản của bạn đã cập nhật, bạn có thể tiếp tục cài đặt.
Bước 2: Cài đặt OpenClaw CLI
Chạy lệnh sau để cài đặt OpenClaw CLI trên toàn hệ thống.
Bước 3: Chạy onboarding và bật khả năng duy trì chạy
Chạy lệnh sau để khởi động trình hướng dẫn onboarding và đăng ký daemon nền. Làm theo trình hướng dẫn để cấu hình môi trường agent của bạn, bao gồm chọn nhà cung cấp mô hình (ví dụ: Kimi API), nhập API key và chọn kênh nhắn tin. Sau khi thiết lập xong, agent của bạn đã sẵn sàng. Bạn có thể bắt đầu tương tác, kết nối công cụ hoặc xây dựng quy trình làm việc theo nhu cầu.
Ghi chú nền tảng: OpenClaw hỗ trợ cả máy Mac dùng Intel và Apple Silicon. Nếu quá trình cài đặt bị Gatekeeper chặn, bạn có thể cho phép trong System Settings, mục Privacy & Security.
Cách cài đặt OpenClaw trên Windows
Windows có ba cách chính để cài đặt OpenClaw: trình cài đặt PowerShell để thiết lập nguyên bản nhanh chóng, WSL2 để có môi trường Linux đầy đủ, và npm để cài đặt thủ công.
Dưới đây là hướng dẫn thiết lập nhanh. Để xem phần hướng dẫn đầy đủ từng bước kèm ảnh chụp màn hình, xem Cách cài đặt OpenClaw trên Windows.
Phương pháp 1: Dùng trình cài đặt PowerShell (Windows nguyên bản)
Bước 1: Chạy script cài đặt trong PowerShell
Mở PowerShell với quyền quản trị viên và chạy script một dòng chính thức để cài đặt OpenClaw.
Bước 2: Hoàn tất trình hướng dẫn onboarding
Làm theo các bước onboarding để cấu hình môi trường agent của bạn, bao gồm chọn nhà cung cấp mô hình (ví dụ: Kimi API), nhập API key và chọn kênh nhắn tin.
Bước 3: Xác minh cài đặt
Chạy lệnh sau để xác nhận OpenClaw đã được cài đúng cách và gateway đang hoạt động.
Bước 4: Bắt đầu sử dụng agent của bạn
Sau khi thiết lập xong, agent của bạn đã sẵn sàng. Bạn có thể bắt đầu tương tác, kết nối công cụ hoặc cấu hình quy trình làm việc theo nhu cầu.
Phương pháp 2: Cài đặt bằng WSL2
Bước 1: Thiết lập môi trường Linux
Mở PowerShell với quyền quản trị viên và chạy lệnh sau để bật và khởi tạo WSL2.
Bước 2: Chạy trình cài đặt trong Linux
Mở terminal Linux của bạn và chạy script cài đặt tiêu chuẩn để cài OpenClaw.
Bước 3: Hoàn tất trình hướng dẫn onboarding
Làm theo các bước onboarding để cấu hình môi trường agent của bạn, bao gồm chọn nhà cung cấp mô hình (ví dụ: Kimi API), nhập API key và chọn kênh nhắn tin.
Sau khi thiết lập xong, agent của bạn đã sẵn sàng. Bạn có thể bắt đầu tương tác, kết nối công cụ hoặc cấu hình quy trình làm việc theo nhu cầu.
Phương pháp 3: Cài đặt bằng npm trên Windows
Bước 1: Kiểm tra phiên bản Node.js của bạn
Chạy lệnh sau để xác minh Node.js đã được cài và đang ở phiên bản mới nhất.
Bước 2: Cài đặt OpenClaw CLI
Chạy lệnh sau để cài đặt OpenClaw CLI trên toàn hệ thống.
Bước 3: Chạy onboarding và bật khả năng duy trì chạy
Chạy lệnh sau để khởi động trình hướng dẫn onboarding và đăng ký daemon nền.
Làm theo các bước onboarding để cấu hình môi trường agent của bạn, bao gồm chọn nhà cung cấp mô hình (ví dụ: Kimi API), nhập API key và chọn kênh nhắn tin.
Sau khi thiết lập xong, agent của bạn đã sẵn sàng. Bạn có thể bắt đầu tương tác, kết nối công cụ hoặc cấu hình quy trình làm việc theo nhu cầu.
Cách chạy OpenClaw trực tuyến với Kimi Claw
Các phương pháp trên cần terminal, phiên bản Node.js được hỗ trợ và một máy luôn bật. Kimi Claw cung cấp tùy chọn lưu trữ hoàn toàn, giúp bạn chạy OpenClaw mà không phải cài đặt hay duy trì môi trường cục bộ.
Bước 1: Mở Kimi Claw và tạo một instance
Truy cập trang Kimi Claw rồi nhấp Create để bắt đầu.
Bước 2: Xác nhận triển khai
Xác nhận triển khai trong cửa sổ bật lên. Kimi Claw sẽ tự động thiết lập môi trường OpenClaw của bạn, bao gồm gateway và workspace, mà không cần cấu hình cục bộ nào.
Bước 3: Bắt đầu sử dụng workspace của bạn
Sau khi triển khai xong, workspace của bạn sẽ mở trong dashboard. Bạn có thể bắt đầu tương tác với agent, thiết lập kỹ năng, cấu hình tác vụ theo lịch và quản lý tệp trực tiếp trong trình duyệt.
Tính năng chính của Kimi Claw
Lưu trữ đám mây: Kimi Claw chạy gateway của bạn trên đám mây, nên agent vẫn luôn sẵn sàng ngay cả khi máy cục bộ của bạn ngoại tuyến.
Bảo trì tự động: Các bản cập nhật và bản vá được xử lý trong nền, không cần thiết lập thủ công hay khởi động lại.
Năng lực tích hợp sẵn: Bao gồm lập lịch tác vụ, lưu trữ bền vững và tải kỹ năng động theo prompt của bạn, đồng thời truy cập liền mạch trên nhiều thiết bị.
Khắc phục các lỗi cài đặt OpenClaw thường gặp
Hầu hết sự cố cài đặt OpenClaw thuộc một vài nhóm phổ biến, như cấu hình PATH, thiếu dependency hoặc xung đột cổng. Các phần dưới đây giúp bạn nhanh chóng xác định và xử lý những vấn đề hay gặp nhất trên macOS, Windows và Linux.
"openclaw: command not found" sau khi cài đặt
OpenClaw không nằm trong PATH của hệ thống.
Cách khắc phục: Thêm thư mục bin toàn cục của npm vào PATH.
Sau đó tải lại shell (ví dụ: source ~/.zshrc) hoặc khởi động lại terminal. Trên Windows, hãy thêm đường dẫn vào biến môi trường rồi khởi động lại PowerShell.
Lỗi build Sharp trên macOS
Điều này thường xảy ra khi libvips được cài toàn cục xung đột với thư viện Sharp.
Cách khắc phục: Chạy lệnh cài đặt với biến môi trường này.
Nếu thấy lỗi node-gyp, hãy cài đặt Xcode Command Line Tools:
OpenClaw không khởi động sau khi reboot
daemon nền chưa được cài đặt trong quá trình onboarding.
Cách khắc phục: Chạy lại onboarding với cờ daemon.
Sau đó xác minh service:
Gateway không phản hồi hoặc hiển thị "0 tokens used"
Tiến trình gateway có thể đã dừng hoặc xác thực API có thể đã thất bại.
Cách khắc phục: Khởi động lại gateway.
Chạy kiểm tra tình trạng:
Để xem nhật ký gỡ lỗi:
Ngoài ra, hãy xác minh API key của bạn còn hợp lệ.
Cổng 18789 đã được sử dụng
Một tiến trình khác đang dùng cổng gateway của OpenClaw.
Cách khắc phục: Tìm và dừng tiến trình gây xung đột
Sau đó khởi động lại gateway:
Lỗi quyền EACCES
Điều này thường có nghĩa là thư mục toàn cục của npm chưa có quyền phù hợp.
Cách khắc phục: Cập nhật quyền sở hữu thư mục.
Trên Windows, chạy PowerShell với quyền Administrator hoặc đặt prefix npm tùy chỉnh:
Với thiết lập Docker, hãy sửa quyền volume:
Lỗi "spawn git ENOENT"
Git chưa được cài đặt hoặc không khả dụng trong PATH.
Cách khắc phục: Cài đặt Git từ git-scm.com, khởi động lại terminal rồi thử cài đặt lại.
WSL2 systemd không hoạt động
Systemd chưa được bật trong cấu hình WSL của bạn.
Cách khắc phục: Chỉnh sửa
/etc/wsl.confvà thêm nội dung sau.
Sau đó khởi động lại WSL:
Mở lại terminal Linux của bạn rồi xác minh:
Hết bộ nhớ khi chạy npm install trên VPS
Các instance VPS ít bộ nhớ có thể gặp lỗi trong quá trình cài đặt gói.
Cách khắc phục: Tạo tệp swap.
Sau đó chạy lại cài đặt.
"Access not configured" khi kết nối với các nền tảng nhắn tin
Tài khoản của bạn chưa được OpenClaw ủy quyền.
Cách khắc phục: Phê duyệt tài khoản bằng mã ghép nối.
Ngoài ra, hãy xác minh thông tin xác thực bot của bạn (token, webhook, quyền) đã được cấu hình đúng.
Kết luận
Việc cài đặt OpenClaw trên macOS, Linux và Windows khá đơn giản. Tùy vào thiết lập của mình, bạn có thể dùng script một dòng, PowerShell, WSL2 hoặc npm. Trình hướng dẫn onboarding sẽ dẫn bạn qua các bước chọn mô hình, cấu hình API và thiết lập kênh nhắn tin. Nếu không muốn tự quản lý môi trường cục bộ, Kimi Claw cung cấp tùy chọn lưu trữ hoàn toàn để bạn chạy OpenClaw trực tiếp trên đám mây.
Câu hỏi thường gặp
node --version để xác nhận phiên bản đáp ứng yêu cầu tối thiểu.npm install -g openclaw@latest trong terminal. Lệnh này cập nhật CLI lên phiên bản mới nhất. Bạn cũng có thể chạy lại trình cài đặt một dòng; trình này sẽ tự động nâng cấp bản cài đặt hiện có. OpenClaw cũng hỗ trợ cập nhật trong ứng dụng qua Control UI tại 127.0.0.1:18789. Sau khi cập nhật, hãy khởi động lại gateway bằng openclaw gateway restart để nạp phiên bản mới.openclaw gateway status để xác nhận daemon đang hoạt động. Trên Windows, WSL2 có bật systemd mang lại thiết lập luôn chạy đáng tin cậy nhất. Nếu không muốn quản lý dịch vụ cục bộ, các tùy chọn được lưu trữ hoàn toàn như Kimi Claw cho phép bạn chạy OpenClaw liên tục trên đám mây.