Trang chủ / Tài liệu hướng dẫn / OpenClaw
Hiểu về OpenClaw · Bài 7

Nhật ký triển khai: những lỗi Aduca gặp khi cài OpenClaw và cách xử lý

Không có lần cài đặt nào hoàn hảo ngay từ đầu. Đây là hai sự cố thật Aduca gặp khi triển khai OpenClaw, những gì tài liệu chính thức giải thích được về chúng, và cách làm lại sạch khi hệ thống đã rối.

Cập nhật 02/10/2026⏱ 8 phút đọcKiến thức nềnNgười mới

Cài xong chạy được chưa phải là xong

Nhiều người cài OpenClaw theo hướng dẫn, nhắn thử bot thấy trả lời, rồi yên tâm giao việc. Vài hôm sau máy khởi động lại, và mọi thứ "tự nhiên" không chạy — chỉ còn một con bot im lặng. (Tình huống minh hoạ.)

Aduca cũng gặp những lần như vậy. Bài này ghi lại hai sự cố thật trong quá trình triển khai, giải thích nguyên nhân ở mức tài liệu chính thức xác nhận được, rồi tổng hợp cách làm lại sạch và các lỗi phổ biến khác.

Nhật ký triển khai dùng để làm gì?

Nhật ký triển khai là bản ghi các lỗi cài OpenClaw và vận hành đã gặp thật, kèm cách chẩn đoán, cách xử lý và nguồn đối chiếu, để lần sau sửa nhanh hơn và không lặp lại.

Theo ẩn dụ nhân viên số: nếu Agent là nhân viên và Gateway là văn phòng, thì nhật ký triển khai là sổ bảo trì toà nhà. Văn phòng mất điện thì nhân viên giỏi mấy cũng nghỉ; sổ bảo trì cho biết chỗ nào hay hỏng, kiểm tra gì trước.

Thứ tự chẩn đoán trước khi đoán mò

  1. openclaw triageTự kiểm tra sức khoẻ, viết bản chẩn đoán đã lược thông tin nhạy cảm
  2. openclaw statusKênh nào đã cấu hình, có lỗi xác thực không
  3. openclaw gateway statusGateway có đang chạy và trả lời không
  4. openclaw doctorLỗi cấu hình, dịch vụ chạy nền
  5. openclaw channels status --probeTừng kênh chat còn kết nối không
  6. openclaw logs --followXem nhật ký trực tiếp khi cần đào sâu
Thang chẩn đoán theo tài liệu OpenClaw — chạy từ trên xuống, dừng ở bước đầu tiên báo lỗi.

Nguồn: OpenClaw – General troubleshooting

Sự cố 1: Cài trên Mac bằng tài khoản riêng, khởi động lại máy là Gateway mất kết nối

Chuyện đã xảy ra

Aduca cài OpenClaw trên một máy Mac bằng một tài khoản người dùng riêng. Sau khi máy khởi động lại, Gateway mất kết nối. Khi Gateway không chạy, không Agent nào nhận được tin nhắn.

Tài liệu chính thức giải thích được gì

Từ đó, nguyên nhân phù hợp nhất là: sau khi khởi động lại, tài khoản riêng của OpenClaw chưa đăng nhập nên LaunchAgent của nó chưa chạy. Aduca không khẳng định đây là nguyên nhân duy nhất; các yếu tố về chế độ ngủ ở trên cũng nên được loại trừ.

Cách xử lý theo tài liệu

Nguồn: OpenClaw – Gateway on macOS · OpenClaw – Gateway runbook · OpenClaw – Gateway service and process · OpenClaw – macOS VMs

Sự cố 2: Lỗi khi Node.js được cài qua nvm

Chuyện đã xảy ra

Trong một lần cài, máy đã có Node.js được quản lý bằng nvm (công cụ cài nhiều phiên bản Node song song). Aduca gặp lỗi liên quan đến Node khi cài và chạy OpenClaw trên máy này.

Tài liệu chính thức chỉ ra những điểm dễ vấp

Aduca không suy đoán thêm lỗi cụ thể của lần đó ngoài các điểm trên. Bài học chung: một máy, một nguồn Node. Trên máy riêng cho OpenClaw, để script chính thức tự lo Node; nếu buộc phải dùng nvm, đặt phiên bản mặc định đạt yêu cầu rồi chạy openclaw gateway install --force và openclaw doctor.

Nguồn: OpenClaw – Node.js · OpenClaw – Installer (nvm) · OpenClaw – Update troubleshooting

Cách làm lại sạch khi hệ thống đã rối

Khi đã sửa chồng lên nhau nhiều lần, làm lại sạch thường nhanh hơn. Trình tự theo tài liệu gỡ cài đặt:

Lệnh tham khảoChạy từng dòng trên máy chạy OpenClaw — đọc kỹ chú thích trước khi Enter
openclaw backup create --verify --output ~/openclaw-backups   # 1. sao lưu và kiểm tra ngay
openclaw uninstall --dry-run --all     # 2. xem trước những gì sẽ bị gỡ
openclaw uninstall                     # 3. gỡ dịch vụ Gateway (chọn phạm vi trong menu)
npm rm -g openclaw                     # 4. gỡ lệnh openclaw bằng đúng npm đã cài nó
command -v openclaw                    # 5. mở cửa sổ mới: không in gì là đã sạch
node -v                                # 6. cần Node 24.16+ hoặc 26.1+
curl -fsSL https://openclaw.ai/install.sh | bash   # 7. cài lại bằng script chính thức
openclaw onboard --install-daemon      # 8. cấu hình và cài dịch vụ chạy nền

Trình tự đầy đủ có trong mục 5b – Sao lưu & khôi phục của hướng dẫn cài đặt.

Nguồn: OpenClaw – Uninstall · OpenClaw – Backups

Các lỗi phổ biến khác

Hiện tượngNguyên nhân thường gặpCách xử lýNguồn
openclaw: command not foundThư mục chứa lệnh chưa nằm trong PATHThêm vào file khởi động shell, mở cửa sổ mớiDocs Node.js
Thoát SSH là bot tắt (VPS)Chưa bật lingersudo loginctl enable-linger $USER rồi khởi động lại GatewayDocs Gateway, Aduca
Bot Telegram im lặngChưa duyệt người nhắn, token sai, Gateway dừngKiểm tra kênh, danh sách chờ duyệt, trạng thái GatewayAduca
Mã duyệt không dùng đượcMã hết hạn sau 1 giờ, hoặc duyệt nhầm botNhắn lại để lấy mã mới, duyệt đúng botDocs Pairing
EADDRINUSE / "another gateway instance"Hai Gateway tranh cùng cổngGiữ một Gateway mỗi máy, gỡ dịch vụ thừaDocs Gateway service
"refusing to bind gateway … without auth"Mở Gateway ra mạng mà chưa đặt mật khẩu/tokenGiữ ở 127.0.0.1 hoặc đặt gateway.authDocs Gateway service
Lỗi 429, hết hạn mứcVượt giới hạn hoặc hết tiền ở nhà cung cấp modelNạp thêm, giảm tần suất, đổi model cho Agent phụAduca
Gateway không chạy sau cập nhậtCấu hình/dữ liệu cần chuyển đổiopenclaw doctor --fix rồi khởi động lạiAduca
Bot chậm, tự tắtHết RAMThêm swap, nâng RAMAduca

Nguồn: OpenClaw – Node.js · OpenClaw – Gateway service · OpenClaw – Pairing · Aduca – Lỗi thường gặp & tự sửa lỗi

Từ "chữa cháy" sang có quy trình

ViệcKhi chưa có quy trìnhKhi có quy trìnhNgười duyệt ở đâu
Phát hiện lỗiBiết khi khách hoặc sếp hỏi vì sao không có báo cáoBáo cáo sức khoẻ hệ thống mỗi sángBạn đọc 1 dòng "HỆ THỐNG ỔN"
Chẩn đoánTìm trên mạng, thử lệnh ngẫu nhiênChạy thang chẩn đoán theo thứ tựBạn xem kết quả trước khi sửa
Sửa lỗiSửa chồng lên nhau, không ghi lạiAgent đề xuất, bạn trả lời "OK" mới sửaBạn duyệt từng thay đổi

Khi thấy bất thường mà Gateway vẫn chạy, có thể nhờ bot chính tự chẩn đoán — nó chỉ được sửa khi bạn đồng ý:

Tin nhắn TelegramCopy rồi dán vào khung chat với bot
Chạy openclaw triage và openclaw channels status --probe.
Giải thích lỗi bằng tiếng Việt, ngắn gọn, và đề xuất cách sửa theo thứ tự an toàn nhất.
Chỉ sửa khi tôi trả lời "OK". Không in token, mật khẩu hay nội dung file cấu hình.

Giới hạn cần biết

Bắt đầu từ đâu?

  1. Làm bài kiểm tra khởi động lại ngay hôm nay: khởi động lại máy chạy Gateway, không đăng nhập, nhắn bot.
  2. Bật sao lưu có kiểm tra và chép một bản ra máy khác trước mọi thay đổi lớn.
  3. Ghi nhật ký riêng của bạn: ngày, hiện tượng, lệnh đã chạy, kết quả — lần sau sẽ nhanh hơn nhiều.

Đọc thêm: Chạy OpenClaw 24/7: VPS hay máy Mac? · Bảo mật khi dùng OpenClaw · OpenClaw là gì?.

Đọc tiếp: Bảo mật OpenClaw →

Câu hỏi thường gặp

Cài OpenClaw trên Mac có ổn không?

Ổn cho thử nghiệm và cho máy Mac luôn bật được cấu hình đúng. Cần nhớ Gateway trên macOS là dịch vụ gắn với tài khoản người dùng và tự chạy khi tài khoản đó đăng nhập; máy ngủ cũng có thể làm Gateway rớt mạng. Muốn chạy 24/7 không phụ thuộc đăng nhập, tài liệu và Aduca đều nghiêng về VPS Linux.

Có nên dùng nvm để cài Node cho OpenClaw không?

Không bắt buộc. Trên máy riêng cho OpenClaw, cách gọn nhất là để script cài đặt chính thức tự lo Node. Nếu đã dùng nvm, hãy đảm bảo phiên bản mặc định đạt yêu cầu (Node 24.16+ hoặc 26.1+), nvm được nạp trong file khởi động shell, và cài lại dịch vụ Gateway sau khi đổi Node.

Làm lại từ đầu có mất hết Agent không?

Không, nếu bạn sao lưu trước. Lệnh sao lưu của OpenClaw đóng gói cấu hình, trí nhớ và thư mục làm việc; lệnh khôi phục luôn giải nén ra thư mục mới, không ghi đè dữ liệu đang chạy. Các mã bí mật nên nhập lại bằng ô nhập ẩn từ trình quản lý mật khẩu.

Khi bot im lặng, việc đầu tiên nên làm là gì?

Chạy lần lượt các lệnh chẩn đoán: openclaw triage, openclaw status, openclaw gateway status, openclaw doctor, openclaw channels status --probe. Phần lớn trường hợp sẽ chỉ ra ngay: Gateway dừng, kênh mất kết nối, hay người nhắn chưa được duyệt.

Tài liệu liên quan

Xem tất cả tài liệu hướng dẫn →

Bước tiếp theo

Để Aduca cài đặt giúp bạn

Aduca cài đặt và bàn giao hệ thống AI Agent đã cấu hình an toàn, kèm hướng dẫn vận hành.

Để Aduca cài đặt giúp bạnXem thư viện tài liệu
Về AducaChuỗi bài do đội ngũ Aduca biên soạn từ kinh nghiệm đào tạo và triển khai AI Agent cho Marketing – Sales. Aduca Academy do Nguyễn Đức – Chủ tịch Aduca Group sáng lập; ông kinh doanh thương mại điện tử từ 2012, chạy quảng cáo Facebook từ 2014 và đào tạo từ 2016. Phần thực hành từng bước nằm trong thư mục OpenClaw và thư mục Hermes Agent.

Nguồn tham khảo

Lịch sử cập nhật

Miễn trừ trách nhiệm

Bài viết thuộc chuỗi kiến thức của Công ty Cổ phần Giáo dục Aduca, chia sẻ miễn phí cho mục đích học tập. Thông tin kỹ thuật đối chiếu với tài liệu chính thức của các dự án và nền tảng tại ngày cập nhật (có ghi nguồn); phần nhận định là quan điểm của Aduca. OpenClaw, Hermes Agent và các phần mềm, dịch vụ nêu trong bài thuộc về chủ sở hữu tương ứng, không thuộc Aduca, và có thể thay đổi bất cứ lúc nào. Kết quả áp dụng phụ thuộc quy trình, dữ liệu và con người của từng doanh nghiệp; bài viết không cam kết doanh thu hay hiệu quả cụ thể. © 2026 Aduca — được trích dẫn khi ghi rõ nguồn aduca.vn.