Nếu bạn đang cố gắng chạy OpenClaw (thường được nhắc đến trong các bản fork hoặc gói cộng đồng với tên Moltbot/Clawdbot) trên máy cục bộ, phần khó khăn thường không phải là clone kho lưu trữ—mà là xử lý các phiên bản runtime, biến môi trường và các vấn đề xây dựng dành riêng cho nền tảng.
Hướng dẫn này cung cấp cho bạn một lộ trình cài đặt thực tế, đa nền tảng, cùng với các bước gỡ lỗi hữu ích khi mọi thứ không suôn sẻ.
Thiết lập OpenClaw thường bao gồm những gì
Hầu hết các bản phân phối OpenClaw đều tuân theo mô hình triển khai tương tự:
- Clone mã nguồn từ Git.
- Cài đặt các phụ thuộc ngôn ngữ/runtime.
- Cấu hình một tệp
.env(token, cơ sở dữ liệu, khóa API). - Khởi tạo bộ nhớ (SQLite/Postgres/Redis tùy thuộc vào bản dựng).
- Chạy các script di chuyển/khởi động.
- Khởi động dịch vụ và xác thực các điểm cuối kiểm tra sức khỏe.
Ngay cả khi bản fork cụ thể của bạn khác biệt, danh sách kiểm tra này vẫn áp dụng cho hầu hết mọi cài đặt.
Điều kiện tiên quyết (tất cả các hệ điều hành)
Trước khi thực hiện các bước dành riêng cho hệ điều hành, hãy xác nhận những điều cơ bản sau:
- Git: để clone và kéo cập nhật.
- Runtime: thường là Node.js (LTS) hoặc Python (3.10+), tùy thuộc vào bản fork.
- Trình quản lý gói: npm/pnpm/yarn cho Node, pip/poetry cho Python.
- Cơ sở dữ liệu (tùy chọn): SQLite để khởi động nhanh cục bộ, Postgres để sử dụng cho nhóm/môi trường staging.
- Shell terminal: PowerShell (Windows), zsh/bash (macOS/Linux).
Xác minh công cụ của bạn
bash git --version node -v npm -v python3 --version pip --version
Nếu tài liệu dự án của bạn chỉ định các phiên bản chính xác, hãy ghim chúng ngay bây giờ. Sự sai lệch phiên bản là nguyên nhân số 1 gây ra lỗi cài đặt "chỉ chạy trên máy của tôi".
Cài đặt OpenClaw trên macOS/Linux
Trên macOS hoặc Linux, chạy trình cài đặt hợp nhất:
curl -fsSL https://openclaw.ai/install.sh | bash
Để biết các phương pháp cài đặt thay thế và yêu cầu hệ thống chi tiết, hãy xem phần Cài đặt.
1. Chạy Trình hướng dẫn thiết lập ban đầu
openclaw onboard --install-daemon
Trình hướng dẫn này thiết lập xác thực, cấu hình cổng kết nối và bất kỳ kênh nhắn tin tùy chọn nào (WhatsApp, Telegram, v.v.).
Để biết hướng dẫn chi tiết, tham khảo tài liệu Hướng dẫn thiết lập ban đầu.
2. Xác minh Cổng kết nối
Nếu bạn đã cài đặt dịch vụ chạy nền (daemon), nó sẽ đang chạy. Kiểm tra trạng thái của nó bằng cách:
openclaw gateway status
3. Mở Giao diện người dùng điều khiển
Khởi chạy bảng điều khiển:
openclaw dashboard
Giờ đây bạn có thể truy cập phiên bản OpenClaw của mình thông qua giao diện người dùng điều khiển dựa trên trình duyệt.
Cài đặt OpenClaw trên Windows
Trên Windows (với PowerShell), chạy trình cài đặt hợp nhất:
iwr -useb https://openclaw.ai/install.ps1 | iexĐể biết các phương pháp cài đặt thay thế và yêu cầu hệ thống chi tiết, hãy xem phần Cài đặt.
1. Chạy Trình hướng dẫn thiết lập ban đầu
openclaw onboard --install-daemon
Trình hướng dẫn này thiết lập xác thực, cấu hình cổng kết nối và bất kỳ kênh nhắn tin tùy chọn nào (WhatsApp, Telegram, v.v.).
Để biết hướng dẫn chi tiết, tham khảo tài liệu Hướng dẫn thiết lập ban đầu.
2. Xác minh Cổng kết nối
Nếu bạn đã cài đặt dịch vụ chạy nền (daemon), nó sẽ đang chạy. Kiểm tra trạng thái của nó bằng cách:
openclaw gateway status
3. Mở Giao diện người dùng điều khiển
Khởi chạy bảng điều khiển:
openclaw dashboard
Giờ đây bạn có thể truy cập phiên bản OpenClaw của mình thông qua giao diện người dùng điều khiển dựa trên trình duyệt.
Cài đặt dựa trên Docker (khuyên dùng để đảm bảo tính nhất quán)
Nếu bạn muốn giảm thiểu các vấn đề phụ thuộc cấp máy chủ, hãy chạy OpenClaw bằng Docker Compose.
Ví dụ mẫu docker-compose.yml:
yaml version: '3.9' services: app: build: . ports: - "3000:3000" env_file: - .env depends_on: - db - redis
db: image: postgres:15 environment: POSTGRES_USER: openclaw POSTGRES_PASSWORD: openclaw POSTGRES_DB: openclaw ports: - "5432:5432"
redis: image: redis:7 ports: - "6379:6379"
Khởi động:
bash docker compose up --build
Cách tiếp cận này mang lại môi trường có thể tái tạo trên macOS, Windows và Linux, đặc biệt cho các nhóm.
Các lỗi cài đặt phổ biến và cách khắc phục
1) Lỗi MODULE_NOT_FOUND hoặc lỗi import
Nguyên nhân: các phụ thuộc chưa được cài đặt, lockfile sai hoặc runtime không tương thích.
Khắc phục:
- Xóa
node_modulesvà cài đặt lại bằngnpm ci. - Đối chiếu runtime với tài liệu dự án (
.nvmrc,pyproject.toml,runtime.txt). - Không trộn lẫn các trình quản lý gói trừ khi kho lưu trữ hỗ trợ điều đó.
2) Kết nối cơ sở dữ liệu bị từ chối
Nguyên nhân: Dịch vụ cơ sở dữ liệu bị ngừng hoặc DATABASE_URL sai.
Khắc phục:
- Xác nhận trạng thái dịch vụ (
systemctl status postgresql,brew services list). - Xác thực tên máy chủ/cổng/người dùng/mật khẩu/cơ sở dữ liệu.
- Kiểm tra kết nối độc lập với
psql.
3) Cổng đã được sử dụng
Khắc phục: tìm và dừng tiến trình xung đột.
macOS/Linux:
bash lsof -i :3000 kill -9
Windows:
powershell netstat -ano | findstr :3000 taskkill /PID /F
4) Quyền bị từ chối trên Linux/macOS
Nguyên nhân: script thiếu quyền thực thi.
bash chmod +x ./scripts/*.sh
Tránh chạy các lệnh ứng dụng bằng sudo trừ khi thực sự cần thiết.
5) Biến môi trường không được tải
Khắc phục:
- Đảm bảo tệp
.envnằm trong thư mục gốc của dự án. - Khởi động lại tiến trình sau khi thay đổi
.env. - Xác minh gói tải (
dotenv) được khởi tạo sớm.
Danh sách kiểm tra bảo mật sau cài đặt
Sau khi OpenClaw khởi động thành công, hãy thực hiện các bước sau trước khi chia sẻ với đồng đội:
- Xoay vòng các khóa bí mật mặc định.
- Thực thi các token API mạnh.
- Hạn chế CORS và URL callback.
- Đặt mức độ ghi nhật ký an toàn cho môi trường sản xuất.
- Thêm các kiểm tra sức khỏe/sẵn sàng.
- Cấu hình chiến lược sao lưu cho các volume cơ sở dữ liệu.
Nếu bạn phơi bày nó ra ngoài localhost, hãy đặt nó sau một reverse proxy (Nginx/Caddy) có TLS.
Xác thực và kiểm tra nhanh chóng các API OpenClaw
Sau khi cài đặt, bạn nên xác minh hành vi của điểm cuối—không chỉ việc khởi động tiến trình.
Một mô hình nhanh chóng:
- Import tệp OpenAPI của OpenClaw (nếu có).
- Tạo biến môi trường cho các URL cục bộ/staging.
- Xây dựng các kiểm tra hồi quy cho các điểm cuối xác thực, CRUD và webhook.
Đây là lúc Apidog giúp giảm ma sát. Bạn có thể thiết kế, gỡ lỗi, kiểm tra và tài liệu hóa API trong một không gian làm việc duy nhất, để việc xác thực thiết lập không trải rộng trên nhiều công cụ.
Quy trình làm việc thực tế trong Apidog:
- Import schema và tạo các bộ sưu tập yêu cầu.
- Thêm kiểm thử tự động với các xác nhận dựa trên kịch bản.
- Giả lập các phụ thuộc bị thiếu bằng các phản hồi động.
- Chia sẻ tài liệu tương tác với nhóm của bạn sau khi ổn định.
Nếu bạn đang kiểm tra các bản fork của OpenClaw với những thay đổi thường xuyên, quy trình làm việc đơn lẻ đó nhanh hơn việc duy trì thủ công các script cộng với tài liệu riêng biệt.
Chiến lược nâng cấp cho các bản fork của OpenClaw
Các bản fork của bot/công cụ mã nguồn mở phát triển nhanh chóng. Sử dụng một lộ trình cập nhật có thể lặp lại:
bash git fetch origin git checkout main git pull npm ci npm run migrate npm test npm run dev
Đối với các bản dựng Python:
bash pip install -r requirements.txt python manage.py migrate pytest
Sử dụng kiểm thử dựa trên nhánh trước khi hợp nhất các thay đổi từ upstream. Nếu nhóm của bạn sử dụng các hợp đồng API, kiểm tra sự khác biệt schema sẽ ngăn chặn các thay đổi phá vỡ âm thầm.
Lời kết
Cài đặt OpenClaw (Moltbot/Clawdbot) trên macOS, Windows hoặc Linux khá đơn giản một khi bạn kiểm soát được ba biến số: phiên bản runtime, cấu hình môi trường và các phụ thuộc dịch vụ.
Nếu bạn cài đặt cho một nhóm, Docker Compose thường là nền tảng đáng tin cậy nhất. Nếu bạn cài đặt để phát triển cục bộ, thiết lập gốc là ổn—chỉ cần ghim phiên bản và commit các script thiết lập ban đầu.
Khi OpenClaw đã chạy, hãy coi việc xác thực API là một phần của quá trình cài đặt đúng cách. Bạn có thể import và kiểm tra các điểm cuối trong Apidog, tạo các kiểm tra tự động và giữ cho tài liệu được đồng bộ hóa khi bản fork của bạn phát triển.
Hãy dùng thử miễn phí—không yêu cầu thẻ tín dụng—và sử dụng nó để khóa chặt quy trình làm việc API OpenClaw của bạn từ lần khởi động đầu tiên cho đến kiểm thử hồi quy.