Thành thật mà nói, việc cài đặt OpenClaw trên Windows khó hơn một chút so với cài trên Mac hoặc Ubuntu. Môi trường Windows có nhiều yếu tố phụ thuộc vào cấu hình hệ thống và quyền người dùng, khiến quá trình cài đặt dễ phát sinh lỗi ở những chỗ không ngờ tới nhất. Rất có thể bạn sẽ bị mắc kẹt ở một bước nào đó mà không biết phải làm gì tiếp theo.
Bản thân mình cũng từng trải qua những tình huống đó. Sau khi đã thử đi thử lại và tổng hợp kinh nghiệm, mình đã dành một ngày để sắp xếp lại toàn bộ quy trình, xác minh từng bước hoạt động thật sự, và viết ra bài hướng dẫn này. Mục tiêu là dù bạn không rành kỹ thuật cũng có thể làm theo và cài đặt thành công.
Bài viết sẽ đi từng bước một cách chi tiết: từ việc cài đặt các công cụ cần thiết như Node.js, pnpm, git, đến lúc giao diện OpenClaw hiện lên trên trình duyệt của bạn. Các lỗi phổ biến và cách khắc phục cũng được đưa vào để bạn không phải mất thời gian tìm kiếm.
⚙️ Yêu Cầu Hệ Thống
Trước khi bắt tay vào cài đặt, hãy kiểm tra lại máy tính của bạn có đáp ứng đủ các yêu cầu tối thiểu dưới đây không. Nếu máy không đủ cấu hình, OpenClaw có thể chạy chậm hoặc không ổn định.
- Hệ điều hành: Windows 10 (64-bit) hoặc Windows 11 — OpenClaw không hỗ trợ Windows 32-bit hoặc các phiên bản cũ hơn.
- RAM: Tối thiểu 2 GB, khuyến nghị 4 GB trở lên để chạy ổn định. Nếu bạn có 8 GB thì càng tốt — trải nghiệm sẽ rất mượt.
- CPU: Tối thiểu 2 nhân xử lý. Hầu hết các máy tính sản xuất sau năm 2015 đều đáp ứng được yêu cầu này.
- Ổ cứng: Tối thiểu còn trống 1 GB, khuyến nghị 4 GB để đủ chỗ cho mã nguồn, dependencies và các file sinh ra trong quá trình build.
- Kết nối Internet: Bắt buộc trong quá trình cài đặt để tải xuống Node.js, git và các gói phụ thuộc của dự án qua pnpm.
⚠️ Lưu ý bảo mật: Nếu bạn chưa hoàn toàn tin tưởng OpenClaw hoặc muốn thử nghiệm trước, hãy cài trên VPS hoặc máy ảo (Virtual Machine). Điều này giúp bảo vệ máy tính chính của bạn trong trường hợp có vấn đề phát sinh.
📦 Bước 1: Cài Đặt Node.js
Node.js là nền tảng runtime JavaScript mà OpenClaw được xây dựng trên đó. Không có Node.js, OpenClaw không thể khởi động. Đây là bước đầu tiên và quan trọng nhất bạn cần thực hiện.
1.1 Tại Sao Cần Node.js v22 Trở Lên?
OpenClaw sử dụng nhiều tính năng JavaScript hiện đại chỉ có sẵn từ Node.js v22 trở lên, bao gồm các API mới về xử lý bất đồng bộ và quản lý bộ nhớ. Nếu bạn cài phiên bản cũ hơn, rất có thể sẽ gặp lỗi ngay trong bước build hoặc khi khởi chạy.
1.2 Tải Xuống Node.js
Mở trình duyệt web (Chrome, Edge, Firefox đều được) và truy cập vào trang chủ chính thức của Node.js tại địa chỉ nodejs.org. Trên trang chủ, bạn sẽ thấy nút “Get Node.js” — nhấp vào đó.
Trang sẽ chuyển sang phần chọn phiên bản. Bạn sẽ thấy hai lựa chọn chính: LTS (Long-Term Support) và Current. Hãy luôn chọn phiên bản LTS vì đây là phiên bản được hỗ trợ lâu dài, ổn định và đã được kiểm thử kỹ lưỡng. Sau khi chọn LTS, nhấp vào “Windows Installer (.msi)” để tải file cài đặt về máy.
File tải về sẽ có tên dạng node-v24.x.x-x64.msi (số phiên bản có thể khác nhau tùy thời điểm bạn tải). Đây là file cài đặt chính thức từ Node.js — không cần lo ngại về virus hay phần mềm độc hại.
1.3 Tiến Hành Cài Đặt Node.js
Sau khi tải xong, tìm file .msi vừa tải trong thư mục Downloads của bạn. Nhấn đúp chuột trái vào file đó để khởi chạy trình cài đặt.
Windows có thể hiện lên hộp thoại hỏi quyền: “Do you want to allow this app to make changes to your device?” — hãy nhấn Yes để tiếp tục. Đây là bước bình thường khi cài bất kỳ phần mềm nào trên Windows.
Trình cài đặt Node.js sẽ mở ra. Bạn chỉ cần làm theo các bước sau:
- Nhấn Next ở màn hình chào mừng.
- Đọc và tích vào ô “I accept the terms in the License Agreement”, sau đó nhấn Next.
- Chọn thư mục cài đặt — mặc định là C:\Program Files\nodejs, bạn nên giữ nguyên mặc định này. Nhấn Next.
- Tại màn hình Custom Setup, giữ nguyên tất cả các tùy chọn mặc định và nhấn Next.
- Tại màn hình Tools for Native Modules, không cần tích vào ô này trừ khi bạn cần làm việc với các module native — nhấn Next.
- Nhấn Install để bắt đầu quá trình cài đặt thật sự.
- Chờ thanh tiến trình chạy xong (thường mất khoảng 1-3 phút tùy tốc độ máy).
- Nhấn Finish để hoàn tất.
✅ Mẹo: Trong quá trình cài đặt, không cần làm gì cả — chỉ cần chờ thanh tiến trình chạy xong. Đừng nhấn Cancel dù quá trình có vẻ dừng lại một lúc.
1.4 Kiểm Tra Node.js Đã Cài Thành Công Chưa?
Sau khi cài xong, chúng ta cần xác nhận Node.js đã được cài đặt đúng và hệ thống nhận ra nó. Cách kiểm tra nhanh nhất là qua Command Prompt (cmd).
Để mở cmd với quyền Administrator (bắt buộc để các lệnh tiếp theo hoạt động đúng), bạn làm như sau: Nhấp vào biểu tượng kính lúp 🔍 trên thanh taskbar (hoặc nhấn phím Windows), gõ vào “cmd”. Khi kết quả “Command Prompt” hiện ra, nhấp chuột phải vào nó và chọn “Run as administrator”. Một hộp thoại xác nhận quyền có thể hiện lên — nhấn Yes.
Cửa sổ Command Prompt màu đen sẽ xuất hiện. Đây là nơi bạn sẽ gõ các lệnh trong phần lớn quá trình cài đặt. Tại dấu nhắc lệnh (thường có dạng C:\Windows\system32>), gõ lệnh sau và nhấn Enter:
node -v
Nếu Node.js đã được cài đặt thành công, bạn sẽ thấy một dòng hiện ra như sau (số phiên bản có thể khác):
v24.14.0
Bất kỳ số phiên bản nào từ v22 trở lên (v22.x.x, v23.x.x, v24.x.x) đều là thành công. Tiếp theo, kiểm tra npm — trình quản lý gói đi kèm với Node.js:
npm -v
Kết quả sẽ là một số phiên bản của npm, ví dụ như 10.9.0. Chỉ cần hiện số phiên bản là npm đã sẵn sàng — không cần quan tâm cụ thể số đó là bao nhiêu.
⚠️ Nếu lỗi ‘node’ is not recognized: Điều này có nghĩa là Node.js chưa được thêm vào PATH của hệ thống. Cách khắc phục đơn giản nhất: đóng cmd lại, sau đó mở lại với quyền Administrator. Windows cần khởi động lại cmd để nhận các biến môi trường mới.
1.5 Cài Đặt pnpm — Trình Quản Lý Gói Tốt Hơn npm
pnpm (Performant npm) là một trình quản lý gói thay thế cho npm được cộng đồng Node.js đánh giá cao. OpenClaw sử dụng pnpm thay vì npm mặc định vì một số lý do kỹ thuật quan trọng:
- Tốc độ cài đặt nhanh hơn đáng kể: pnpm sử dụng cơ chế cache và symlink thông minh, giúp cài đặt dependencies nhanh hơn npm thông thường từ 2-3 lần trong nhiều trường hợp.
- Tiết kiệm dung lượng ổ đĩa: Thay vì sao chép các gói vào từng dự án như npm, pnpm tạo một kho lưu trữ trung tâm (content-addressable store) và dùng hard link hoặc symlink để tham chiếu đến chúng. Nếu bạn có nhiều dự án Node.js, tiết kiệm được có thể lên đến hàng GB.
- Quản lý dependencies an toàn hơn: pnpm tạo ra cấu trúc node_modules nghiêm ngặt hơn, ngăn chặn các gói truy cập vào dependencies không được khai báo — một lỗ hổng tiềm ẩn khi dùng npm.
Để cài đặt pnpm, tại cửa sổ cmd đang mở, gõ lệnh sau và nhấn Enter:
npm install -g pnpm
Cờ -g có nghĩa là “global” — pnpm sẽ được cài đặt trên toàn hệ thống, không chỉ cho một dự án cụ thể. Sau khi chạy lệnh, npm sẽ tải xuống và cài đặt pnpm. Bạn sẽ thấy một thanh tiến trình và cuối cùng là thông báo tương tự:
added 1 package in Xs
Thông báo như vậy nghĩa là cài thành công. Kiểm tra lại bằng lệnh:
pnpm -v
Màn hình sẽ hiện số phiên bản pnpm, ví dụ 10.32.1. Nếu hiện số phiên bản là thành công hoàn toàn.
⚠️ Nếu pnpm không được nhận dạng ngay lập tức: Đóng cửa sổ cmd và mở lại với quyền Administrator. Đây là lỗi PATH thường gặp trên Windows — khởi động lại cmd là đủ để khắc phục.
🔧 Bước 2: Cài Đặt Git
Git là hệ thống quản lý phiên bản (version control system) phổ biến nhất thế giới. Mặc dù trong hướng dẫn này chúng ta không clone bằng git mà tải ZIP, nhưng Git vẫn cần thiết vì: Git Bash — terminal đi kèm với Git trên Windows — là môi trường tốt nhất để chạy các lệnh pnpm build và pnpm start. Nhiều lệnh OpenClaw hoạt động tốt hơn và ổn định hơn trong Git Bash so với cmd thông thường.
2.1 Tải Xuống Git
Mở trình duyệt và truy cập vào trang chủ chính thức của Git tại git-scm.com. Trang web sẽ tự động phát hiện hệ điều hành của bạn và đề xuất phiên bản phù hợp. Nhấp vào nút “Download for Windows”.
Trên trang tiếp theo, bạn sẽ thấy nhiều lựa chọn tải xuống khác nhau. Hãy chọn “Git for Windows / x64 setup” — đây là bản cài đặt dành cho máy 64-bit (hầu hết máy tính hiện đại). File có tên dạng Git-2.xx.x-64-bit.exe với dung lượng khoảng 50-60 MB.
2.2 Tiến Hành Cài Đặt Git
Sau khi tải xong, tìm file Git-2.xx.x-64-bit.exe trong thư mục Downloads và nhấn đúp chuột để khởi chạy. Windows sẽ hỏi quyền — chọn Yes.
Trình cài đặt Git có nhiều màn hình tùy chỉnh. Tin vui là bạn không cần thay đổi gì — hãy giữ tất cả các tùy chọn mặc định và nhấn Next qua từng bước. Đây là lý do tại sao cài đặt mặc định là tốt nhất cho người mới:
- Default editor: Git chọn Vim làm editor mặc định. Nếu bạn muốn đổi sang Notepad hoặc VS Code, bạn có thể chọn ở bước này, nhưng không bắt buộc.
- PATH environment: Chọn “Git from the command line and also from 3rd-party software” — đây là tùy chọn mặc định và tốt nhất. Nó cho phép lệnh git hoạt động cả trong cmd lẫn PowerShell.
- Line ending: Chọn “Checkout Windows-style, commit Unix-style line endings” — mặc định, phù hợp nhất cho Windows.
Sau khi đã qua hết các màn hình tùy chọn, nhấn Install và chờ quá trình cài đặt hoàn tất. Khi hoàn tất, tại màn hình cuối cùng, hãy làm như sau: Tích vào ô “Launch Git Bash” (để Git Bash tự động mở ngay sau khi nhấn Finish), và bỏ tích ô “View Release Notes” (không cần xem ghi chú phát hành). Sau đó nhấn Finish.
Git Bash — một terminal màu đen với giao diện Unix-like — sẽ tự động mở ra. Đây sẽ là công cụ bạn dùng chủ yếu trong các bước tiếp theo.
2.3 Kiểm Tra Git Đã Cài Thành Công Chưa?
Tại cửa sổ Git Bash vừa mở, gõ lệnh sau và nhấn Enter:
git –version
Bạn sẽ thấy kết quả như:
git version 2.53.0.windows.1
Số phiên bản hiện ra là xác nhận Git đã hoạt động. Bạn cũng có thể kiểm tra trong cmd bằng lệnh tương tự — kết quả sẽ giống nhau.
✅ Điểm quan trọng: Từ đây trở đi trong hướng dẫn này, khi mình nói “mở Git Bash”, bạn có thể tìm nó trong Start Menu bằng cách gõ “Git Bash” và chọn “Run as administrator”.
🦞 Bước 3: Cài Đặt OpenClaw
Đây là bước trung tâm — chúng ta sẽ tải mã nguồn về, cài các gói phụ thuộc, build dự án và chạy OpenClaw lần đầu tiên.
3.1 Tải Xuống Mã Nguồn OpenClaw
Mở trình duyệt và truy cập vào trang GitHub chính thức của OpenClaw. Trên trang GitHub, bạn sẽ thấy nút màu xanh lá cây “Code” ở phía trên bên phải danh sách file. Nhấp vào nút đó, một menu thả xuống sẽ hiện ra, chọn “Download ZIP”.
Trình duyệt sẽ bắt đầu tải file openclaw-main.zip về máy. Dung lượng file khoảng vài MB, tùy tốc độ mạng có thể mất vài giây đến vài phút.
Sau khi tải xong, bạn cần tạo một nơi lưu trữ cho dự án. Hãy vào ổ D (hoặc ổ C nếu bạn muốn) và tạo cấu trúc thư mục như sau: Tạo thư mục “ai” trong ổ D, bên trong đó tạo thêm thư mục “openclaw”. Cấu trúc sẽ là D:\ai\openclaw.
Sao chép file openclaw-main.zip vào thư mục D:\ai\openclaw. Nhấp chuột phải vào file openclaw-main.zip và chọn “Extract here” (hoặc “Giải nén tại đây” tùy ngôn ngữ Windows của bạn). Sau khi giải nén xong, bạn sẽ thấy thư mục mới tên là “openclaw-main” xuất hiện bên trong D:\ai\openclaw.
⚠️ Quan trọng về đường dẫn: Ghi nhớ đường dẫn đầy đủ đến thư mục dự án: D:\ai\openclaw\openclaw-main. Bạn sẽ cần dùng đường dẫn này trong các lệnh phía sau. Nếu bạn đặt thư mục ở vị trí khác, hãy thay thế đường dẫn tương ứng.
3.2 Cài Đặt Các Thành Phần Phụ Thuộc (Dependencies)
OpenClaw phụ thuộc vào rất nhiều gói thư viện Node.js bên ngoài để hoạt động — từ các thư viện xử lý API đến các công cụ build. Tất cả những gói này được liệt kê trong file package.json bên trong dự án, và pnpm sẽ tự động đọc file đó và tải tất cả về cho bạn.
Mở Command Prompt với quyền Administrator (gõ cmd trong thanh tìm kiếm, nhấp phải → Run as administrator). Đầu tiên, chuyển sang ổ D bằng cách gõ:
d:
Nhấn Enter. Dấu nhắc lệnh sẽ thay đổi thành D:\>. Tiếp theo, điều hướng vào thư mục ai:
cd ai
Tiếp tục vào thư mục openclaw:
cd openclaw
Cuối cùng, vào thư mục openclaw-main — đây là thư mục gốc của dự án:
cd openclaw-main
Khi thành công, dấu nhắc lệnh sẽ hiển thị đường dẫn đầy đủ dạng D:\ai\openclaw\openclaw-main>. Đây là dấu hiệu bạn đang ở đúng vị trí. Bây giờ, chạy lệnh cài đặt dependencies:
pnpm install
Sau khi nhấn Enter, pnpm sẽ bắt đầu đọc file package.json, tính toán toàn bộ cây phụ thuộc (dependency tree), và tải xuống từng gói từ registry npm. Bạn sẽ thấy một thanh tiến trình và nhiều dòng log hiện ra. Quá trình này thường mất từ 1 đến 5 phút tùy tốc độ Internet.
Khi hoàn tất thành công, terminal sẽ hiển thị thông báo tóm tắt kết quả cài đặt — số gói đã được thêm vào, thời gian thực hiện và trạng thái. Nếu thấy thông báo không có lỗi (no errors), bạn đã sẵn sàng cho bước tiếp theo.
⚠️ Lỗi mạng trong quá trình pnpm install: Đây là lỗi phổ biến nhất trong toàn bộ quy trình cài đặt, và cũng là lỗi đơn giản nhất để khắc phục. Nguyên nhân thường do kết nối Internet không ổn định trong lúc tải. Giải pháp: gõ lại đúng lệnh pnpm install và nhấn Enter. Hầu hết trường hợp chạy lại 1-2 lần là thành công hoàn toàn.
3.3 Build Dự Án
Bước build là quá trình biên dịch mã nguồn TypeScript/JavaScript của OpenClaw thành định dạng tối ưu để chạy trên máy của bạn. Quá trình này chỉ cần thực hiện một lần duy nhất — sau khi đã build thành công, bạn không cần build lại mỗi lần khởi động.
Để build, chúng ta cần dùng Git Bash thay vì cmd thông thường vì một số lệnh build của OpenClaw sử dụng cú pháp Unix không hoạt động trong cmd. Mở Git Bash bằng một trong hai cách:
- Cách 1 (khuyến nghị): Điều hướng đến thư mục D:\ai\openclaw\openclaw-main trong File Explorer của Windows, sau đó nhấp chuột phải vào khoảng trắng bên trong thư mục và chọn “Git Bash here”. Git Bash sẽ tự động mở tại đúng thư mục đó — bạn không cần gõ thêm lệnh cd nào.
- Cách 2: Tìm “Git Bash” trong Start Menu, mở nó với quyền Administrator, sau đó gõ lệnh cd để điều hướng đến thư mục dự án:
cd /d/ai/openclaw/openclaw-main
Lưu ý cú pháp đường dẫn trong Git Bash dùng dấu gạch chéo thuận (/) thay vì dấu gạch chéo ngược (\) như trong cmd, và ổ D được viết thành /d/ ở đầu đường dẫn.
Khi đã ở đúng thư mục dự án trong Git Bash, chạy lệnh build:
pnpm build
Quá trình build sẽ bắt đầu. Bạn sẽ thấy nhiều dòng log liên quan đến quá trình compile TypeScript, bundle các module và tạo file output. Toàn bộ quá trình thường mất từ 30 giây đến 2 phút. Khi build thành công, terminal sẽ hiển thị thông báo thành công — thường bao gồm danh sách các file đã được tạo ra và tổng thời gian build.
⚠️ Nếu pnpm build thất bại: Kiểm tra lại hai điều: (1) Bạn đang ở đúng thư mục openclaw-main chưa? Gõ pwd trong Git Bash để xem đường dẫn hiện tại. (2) Node.js phiên bản đủ v22 chưa? Gõ node -v để kiểm tra.
3.4 Khởi Chạy OpenClaw Lần Đầu
Sau khi build thành công, đã đến lúc khởi động OpenClaw. Vẫn trong cửa sổ Git Bash đang mở, gõ lệnh sau:
pnpm start
Lệnh này sẽ khởi động server OpenClaw. Bạn sẽ thấy nhiều dòng log xuất hiện liên tục, cho thấy OpenClaw đang khởi động các module khác nhau của nó. Khi quá trình khởi động hoàn tất, terminal sẽ dừng xuất log và hiển thị trạng thái sẵn sàng. Đây là lúc chúng ta chạy Gateway — cổng kết nối chính mà trình duyệt sẽ dùng để giao tiếp với OpenClaw. Mở một cửa sổ Git Bash khác (hoặc tab mới nếu bạn dùng Windows Terminal) và gõ:
pnpm openclaw gateway
Sau một vài giây, Gateway sẽ khởi động và hiển thị địa chỉ kết nối, thường là:
http://127.0.0.1:18789
Hãy sao chép địa chỉ này (bôi đen và nhấn Ctrl+C hoặc nhấp chuột phải → Copy), sau đó mở trình duyệt yêu thích của bạn, dán vào thanh địa chỉ và nhấn Enter. Giao diện web của OpenClaw sẽ tải lên — bạn sẽ thấy màn hình chào mừng hoặc giao diện chat của OpenClaw.
🎉 CHÚC MỪNG! Bạn đã cài đặt thành công OpenClaw trên Windows! Đây là thành quả của toàn bộ quá trình trên. Nếu giao diện OpenClaw hiện ra, mọi thứ đã hoạt động đúng.
3.5 Cấu Hình OpenClaw với API Key
OpenClaw cần được kết nối với một nhà cung cấp AI để hoạt động — đây là nơi bạn nhập API key của mình. Trước tiên, hãy dừng Gateway đang chạy bằng cách quay lại cửa sổ Git Bash đang hiển thị Gateway và nhấn Ctrl + C. Sau đó chạy lệnh cấu hình:
pnpm openclaw configure
Trình cấu hình tương tác sẽ khởi động với một loạt câu hỏi. Hãy làm theo từng bước:
Câu hỏi đầu tiên: “Where will the Gateway run?” — Hệ thống hỏi bạn muốn chạy Gateway ở đâu. Dùng phím mũi tên để di chuyển và nhấn Enter để chọn “Local (this machine)”. Đây là tùy chọn phổ biến nhất — chạy trực tiếp trên máy của bạn, không cần server từ xa.
Câu hỏi tiếp theo: “Model” — Chọn mục này và nhấn Enter để tiếp tục. Hệ thống sẽ liệt kê danh sách đầy đủ các nhà cung cấp AI được hỗ trợ, bao gồm OpenAI (GPT-4, GPT-3.5), Anthropic (Claude), Google (Gemini), xAI (Grok), Minimax và nhiều nhà cung cấp khác.
Dùng phím mũi tên để chọn nhà cung cấp AI bạn muốn sử dụng. Nếu chưa biết chọn ai, Minimax là lựa chọn đáng cân nhắc vì chi phí thấp và chất lượng tốt. Nhấn Enter để xác nhận lựa chọn.
Tiếp theo, hệ thống có thể hỏi về region — chọn mục có chữ “CN” nếu bạn ở châu Á để có độ trễ thấp nhất. Cuối cùng, hệ thống sẽ yêu cầu bạn nhập API key. Dán API key của nhà cung cấp bạn đã chọn vào đây và nhấn Enter.
Sau khi nhập API key, hệ thống sẽ hiển thị tóm tắt toàn bộ cấu hình bạn đã thiết lập. Kiểm tra lại cho đúng, sau đó nhấn Enter để xác nhận và lưu. Dùng phím mũi tên để điều hướng qua các lựa chọn cuối cùng và nhấn Enter lần cuối để kết thúc quá trình cấu hình.
⚠️ Về API key: Bạn cần đăng ký tài khoản tại nhà cung cấp AI bạn chọn (ví dụ: platform.openai.com cho OpenAI, console.anthropic.com cho Anthropic) và tạo API key từ dashboard của họ. API key thường bắt đầu bằng sk- (OpenAI) hoặc các ký tự đặc trưng khác.
3.6 Xác Minh Toàn Bộ Cấu Hình
Sau khi cấu hình xong, hãy kiểm tra lại toàn bộ hệ thống bằng cách khởi động lại Gateway:
pnpm openclaw gateway
Nếu Gateway khởi động thành công và hiển thị địa chỉ 127.0.0.1:18789 như trước, hãy mở địa chỉ đó trong trình duyệt. Lần này, OpenClaw sẽ có thể giao tiếp với nhà cung cấp AI mà bạn đã cấu hình. Thử gửi một tin nhắn thử nghiệm đơn giản để xác nhận kết nối API hoạt động.
✅ Cấu hình chỉ cần thực hiện một lần duy nhất. Tất cả thông tin cấu hình được lưu vào file trên máy bạn. Lần sau bạn khởi động lại, chỉ cần chạy Gateway là đủ — không cần cấu hình lại.
🔴 Tổng Hợp Lỗi Thường Gặp & Cách Khắc Phục
Dưới đây là danh sách các lỗi thường gặp nhất được rút ra từ kinh nghiệm thực tế, kèm hướng dẫn khắc phục chi tiết:
Lỗi 1: pnpm install thất bại do lỗi mạng
Đây là lỗi phổ biến nhất. Bạn sẽ thấy thông báo lỗi đỏ liên quan đến network, ECONNREFUSED, ETIMEOUT hoặc tương tự. Nguyên nhân là kết nối Internet không ổn định trong quá trình tải các gói.
Cách khắc phục: Không cần làm gì phức tạp — chỉ cần chạy lại đúng lệnh đó:
pnpm install
Hầu hết trường hợp, chạy lại 1-2 lần là thành công. pnpm thông minh đủ để bỏ qua các gói đã tải thành công và chỉ tải lại những gói bị lỗi.
Lỗi 2: ‘pnpm’ is not recognized as an internal or external command
Lỗi này xuất hiện khi bạn gõ pnpm trong cmd nhưng hệ thống không tìm thấy lệnh đó. Nguyên nhân là sau khi cài pnpm, biến môi trường PATH chưa được cập nhật trong phiên cmd hiện tại.
Cách khắc phục: Đóng toàn bộ cửa sổ cmd đang mở, sau đó mở lại cmd mới với quyền “Run as administrator”. Gõ lại pnpm -v để kiểm tra — lần này sẽ hoạt động.
Lỗi 3: Access denied / Permission denied
Lỗi quyền truy cập thường xuất hiện khi bạn cố chạy lệnh trong cmd hoặc Git Bash không có quyền Administrator. Windows bảo vệ các thư mục hệ thống và không cho phép cài đặt global packages nếu không có quyền đủ cao.
Cách khắc phục: Luôn mở cmd và Git Bash bằng cách nhấp chuột phải → “Run as administrator”. Đây là thói quen cần có khi làm việc với Node.js trên Windows.
Lỗi 4: pnpm build thất bại
Nếu pnpm build báo lỗi, hãy kiểm tra hai điều theo thứ tự: Thứ nhất, xác nhận bạn đang ở đúng thư mục. Trong Git Bash, gõ pwd — bạn phải thấy đường dẫn kết thúc bằng /openclaw-main. Nếu không, gõ lại:
cd /d/ai/openclaw/openclaw-main
Thứ hai, kiểm tra phiên bản Node.js:
node -v
Phải là v22 trở lên. Nếu thấp hơn, hãy quay lại Bước 1 và cài lại Node.js phiên bản mới hơn.
Lỗi 5: Gateway không khởi động được
Nếu pnpm openclaw gateway không hiển thị địa chỉ 127.0.0.1:18789 mà báo lỗi về port, nguyên nhân có thể là cổng 18789 đang bị một ứng dụng khác chiếm dụng. Thử tắt các ứng dụng đang chạy ngầm không cần thiết, sau đó thử lại.
💡 Kết Luận: Cách Sử Dụng OpenClaw Sau Khi Tắt Máy
Câu hỏi mà hầu hết mọi người đặt ra sau khi cài đặt xong là: “Nếu tôi tắt máy tính, tôi có phải cài lại từ đầu không?” Câu trả lời dứt khoát là KHÔNG. Tất cả những gì bạn đã cài đặt — Node.js, pnpm, Git, mã nguồn OpenClaw, dependencies và cấu hình API — đều được lưu lại trên ổ cứng của bạn và không bị mất khi tắt máy.
Mỗi lần muốn sử dụng OpenClaw sau khi khởi động lại máy, bạn chỉ cần thực hiện đúng 2 bước sau:
Bước 1 — Mở Git Bash (tìm trong Start Menu, chạy với quyền Administrator) và điều hướng đến thư mục dự án:
cd /d/ai/openclaw/openclaw-main
Bước 2 — Khởi động Gateway:
pnpm openclaw gateway
Sau khoảng 5-10 giây, địa chỉ 127.0.0.1:18789 sẽ hiện ra trong terminal. Sao chép địa chỉ đó, dán vào trình duyệt, nhấn Enter — và bạn đã có thể sử dụng OpenClaw ngay lập tức.
✅ Chỉ 2 lệnh sau mỗi lần khởi động. Không cần cài lại bất cứ thứ gì. Không cần chạy pnpm install hay pnpm build lần nữa. Chỉ đơn giản là cd vào thư mục và chạy gateway.
Nếu bạn gặp bất kỳ khó khăn nào trong quá trình cài đặt mà không tìm thấy giải pháp trong bài viết này, hãy để lại bình luận bên dưới mô tả chi tiết bước bạn đang thực hiện và thông báo lỗi bạn nhận được. Chúng tôi sẽ cố gắng hỗ trợ bạn sớm nhất có thể.
0 Thảo luận Khoa học