OpenClaw cho người mới #1: Cài xong nhưng không chạy — kiểm tra gì trước?

Cập nhật lần cuối: 19/03/2026 | Phiên bản: 1.0

Cài xong OpenClaw mà không chạy được? Đừng hoảng. Chạy lần lượt openclaw status --all → openclaw doctor --fix → openclaw logs --follow. Ba lệnh này giải quyết được khoảng 80% vấn đề. Bài viết này hướng dẫn bạn từng bước chẩn đoán từ A đến Z, từ lỗi Node.js cho đến Gateway không khởi động, channel không kết nối, và agent im lặng.

Bối cảnh: OpenClaw hoạt động thế nào?

Trước khi debug, bạn cần hiểu kiến trúc cơ bản. OpenClaw gồm ba lớp chính: Gateway, Channel và Agent. Nếu bất kỳ mắt xích nào đứt, bạn sẽ thấy im lặng hoặc lỗi.

Bước 0: “Thang chẩn đoán” — Chạy đúng thứ tự này

openclaw status
openclaw status --all
openclaw gateway probe
openclaw gateway status
openclaw doctor
openclaw channels status --probe
openclaw logs --follow

Khi mọi thứ hoạt động bình thường: openclaw gateway probe báo reachable, openclaw gateway status báo runtime running, openclaw doctor không có lỗi blocking.

Nhóm 1: Lỗi môi trường — Node.js, npm, PATH

• Node.js phiên bản cũ: OpenClaw yêu cầu Node.js 22 trở lên.
• Lệnh openclaw không tìm thấy: thường là lỗi PATH.
• Lỗi permission trên npm: đặc biệt hay gặp ở Linux/WSL2.

Nhóm 2: Gateway không khởi động

• gateway.mode not configured → cấu hình lại gateway mode.
• gateway already running hoặc port bị chiếm → dừng tiến trình cũ và khởi động lại.
• gateway token missing / pairing required → kiểm tra auth, device pairing và config sau upgrade.
• Config JSON lỗi → chạy openclaw doctor --fix hoặc validate file cấu hình.

Nhóm 3: Gateway chạy rồi nhưng Agent im lặng

• Model/API key thiếu hoặc hết hạn → kiểm tra openclaw models status.
• Tools profile đang là messaging → chuyển sang full hoặc coding.
• Channel bị lọc tin nhắn → kiểm tra mention gating, pairing pending, allowlist.

Nhóm 4: Lỗi sau khi upgrade

Sau mỗi lần nâng cấp, nên chạy openclaw doctor --fix để phát hiện config drift, device reset, hoặc service metadata lỗi.

Nhóm 5: Lỗi đặc thù theo nền tảng

• macOS: kiểm tra launchd và xung đột Node từ Homebrew/nvm.
• Linux/VPS: kiểm tra systemd linger và headless browser nếu dùng browser control.
• Windows: nên dùng WSL2 thay vì chạy trực tiếp trên PowerShell.

“Nút bấm khẩn cấp” — Khi không còn cách nào khác

Nếu đã thử mọi cách mà vẫn lỗi, backup ~/.openclaw, dừng gateway, rồi setup lại từ đầu.

Checklist tự kiểm tra nhanh

• Node.js >= 22
• openclaw có trong PATH
• openclaw doctor không có lỗi blocking
• Gateway đang chạy
• API key đã cấu hình
• Channel kết nối được
• Tools profile đúng
• Log không có fatal error lặp lại

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

Bài viết cũng giải thích độ an toàn của openclaw doctor --fix, thời gian sẵn sàng của gateway trong Docker, khác biệt khi dùng OAuth, và cách xác minh hệ thống đã hoạt động ổn định sau khi sửa.

Xem thêm

• Tài liệu chính thức — Troubleshooting
• Tài liệu chính thức — Gateway Troubleshooting
• OpenClaw FAQ
• GitHub Issues

Nguồn tham khảo: OpenClaw Docs, GitHub openclaw/openclaw và kinh nghiệm triển khai thực tế.