15+ Lỗi thường gặp khi cài OpenClaw và cách khắc phục (2026)

Cài OpenClaw mà bị kẹt ở một bước nào đó? Đừng lo — hầu hết lỗi đều rơi vào một số pattern quen thuộc và fix được trong vài phút. Bài viết này tổng hợp tất cả lỗi phổ biến nhất khi cài đặt và sử dụng OpenClaw, chia theo 5 nhóm, mỗi lỗi kèm triệu chứng + nguyên nhân + cách fix cụ thể.

Chưa cài? Xem trước Hướng dẫn cài đặt OpenClaw từ A-Z để đi đúng trình tự.

Công cụ debug số 1 — openclaw doctor: Trước khi đọc từng lỗi bên dưới, hãy thử chạy:

openclaw doctor

Lệnh này tự động kiểm tra: config file, quyền file, daemon/service status, port conflict, OAuth token, model auth, và nhiều thứ khác. Nếu phát hiện vấn đề, nó gợi ý cách fix. Thêm flag --repair để tự động sửa:

openclaw doctor --repair

---

Nhóm 1: Lỗi cài đặt (Installation)

Lỗi 1: “node: command not found” hoặc Node.js version quá cũ

Triệu chứng: Chạy lệnh cài OpenClaw báo lỗi, hoặc node -v hiện version dưới 22.

Nguyên nhân: Chưa cài Node.js, hoặc version hệ thống mặc định quá cũ (Ubuntu thường đi kèm Node v12-v18).

Fix: Dùng nvm để cài đúng version:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc
nvm install 24
nvm use 24
node -v   # Phải hiện v24.x.x

OpenClaw yêu cầu Node 24 (khuyến nghị) hoặc Node 22.16+.

Hướng dẫn cài Node.js theo OS: Mac | Windows | Linux

---

Lỗi 2: “openclaw: command not found” sau khi cài

Triệu chứng: Cài xong nhưng gõ openclaw không nhận.

Nguyên nhân: PATH chưa cập nhật — shell chưa biết OpenClaw nằm ở đâu.

Fix:

source ~/.bashrc    # hoặc source ~/.zshrc trên macOS

Nếu vẫn lỗi, thêm npm global bin vào PATH thủ công:

export PATH="$(npm prefix -g)/bin:$PATH"
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc

Hoặc đơn giản hơn: đóng terminal rồi mở lại.

---

Lỗi 3: “npm ERR! node-gyp rebuild failed”

Triệu chứng: Cài OpenClaw (hoặc dependencies) dừng lại với lỗi liên quan node-gyp, python, hoặc sharp.

Nguyên nhân: Thiếu C++ compiler và build tools mà một số native module cần.

Fix theo OS:

macOS: xcode-select --install

Ubuntu/Debian: sudo apt install -y build-essential python3

Fedora: sudo dnf install -y gcc-c++ make python3

Windows (native): npm install -g windows-build-tools

Nếu lỗi riêng với sharp (thư viện xử lý ảnh):

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

---

Lỗi 4: “EACCES: permission denied” khi cài npm global

Triệu chứng: npm install -g openclaw báo lỗi quyền truy cập.

Nguyên nhân: npm cố ghi vào thư mục hệ thống mà user không có quyền. Đừng dùng sudo npm install -g — sẽ gây thêm lỗi quyền về sau.

Fix (không cần sudo):

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Hoặc tốt hơn: dùng nvm — tự quản lý quyền truy cập, không bao giờ cần sudo cho npm.

---

Lỗi 5: “pnpm install” bị timeout/failed (Windows native)

Triệu chứng: Đang cài dependencies từ source code (Cách 1 trên Windows), pnpm báo lỗi mạng hoặc timeout.

Nguyên nhân: Mạng không ổn định, hoặc DNS chậm.

Fix: Chạy lại pnpm install — pnpm tự tiếp tục từ chỗ dang dở. Nếu lỗi lặp lại, thử đổi DNS sang Google (8.8.8.8) hoặc Cloudflare (1.1.1.1).

---

Nhóm 2: Lỗi cấu hình (Configuration)

Lỗi 6: “Invalid API key” hoặc “Authentication failed” (401/403)

Triệu chứng: OpenClaw khởi động nhưng không kết nối được model AI, log hiện lỗi 401 hoặc 403.

Nguyên nhân: API key sai, hết hạn, hoặc không khớp với provider.

Fix:

1. Kiểm tra key có khoảng trắng thừa ở đầu/cuối không
2. Đảm bảo key khớp với provider: sk-ant-... cho Anthropic, sk-... cho OpenAI
3. Vào dashboard của provider kiểm tra credit/quota còn không
4. Nếu key đã bị revoke, tạo key mới

Cấu hình lại: openclaw configure hoặc sửa trực tiếp ~/.openclaw/openclaw.json.

Nếu dùng OAuth và token hết hạn:

openclaw models auth login --provider <tên-provider>

Hướng dẫn lấy key: Cấu hình API Key OpenClaw — từ Claude đến GPT

---

Lỗi 7: Config file sai format — daemon không khởi động

Triệu chứng: Sau khi sửa ~/.openclaw/openclaw.json, daemon không start, openclaw doctor báo config error.

Nguyên nhân: OpenClaw validate config chặt (strict schema). Sai format JSON5 (thiếu dấu ngoặc, comma sai chỗ) sẽ chặn khởi động.

Fix:

openclaw doctor --repair

Lệnh này tự phát hiện config lỗi và gợi ý sửa. Nếu muốn sửa thủ công, mở file config và kiểm tra cú pháp JSON5:

nano ~/.openclaw/openclaw.json

Lưu ý: JSON5 cho phép comment (//) và trailing comma, nhưng key phải đúng tên. Xem danh sách key hợp lệ bằng openclaw doctor.

---

Lỗi 8: “Cannot connect to LLM provider” — timeout/connection refused

Triệu chứng: Log báo timeout khi gọi API model.

Nguyên nhân: Mạng bị chặn (firewall công ty, proxy), hoặc provider đang outage.

Fix:

# Test kết nối trực tiếp
curl -I https://api.anthropic.com
curl -I https://api.openai.com

# Nếu dùng proxy công ty
export HTTP_PROXY=http://proxy:port
export HTTPS_PROXY=http://proxy:port

Kiểm tra status page của provider: status.anthropic.com hoặc status.openai.com.

---

Nhóm 3: Lỗi Gateway & Daemon

Lỗi 9: “EADDRINUSE” — Port 18789 bị chiếm

Triệu chứng: Gateway không start, báo “another gateway instance is already listening” hoặc EADDRINUSE.

Nguyên nhân: Một instance OpenClaw khác (hoặc ứng dụng khác) đang dùng port 18789.

Fix:

# Kiểm tra process đang dùng port
# macOS/Linux:
lsof -i :18789
kill <PID>

# Windows:
netstat -ano | findstr :18789
taskkill /PID <PID> /F

Hoặc đổi port: openclaw gateway --port 18790. Cũng có thể đổi trong config file (gateway.port).

---

Lỗi 10: “refusing to bind gateway without auth”

Triệu chứng: Cấu hình Gateway bind ra ngoài localhost (0.0.0.0) nhưng bị từ chối.

Nguyên nhân: Đây là cơ chế bảo mật — Gateway từ chối bind ra ngoài loopback nếu chưa cấu hình authentication.

Fix: Nếu bạn cần expose Gateway ra ngoài (VPS), bắt buộc đặt password:

{
  "gateway": {
    "auth": { "mode": "password" },
    "bind": "0.0.0.0"
  }
}

Hoặc cách an toàn hơn: giữ bind localhost + dùng SSH tunnel hoặc Tailscale. Xem hướng dẫn VPS.

---

Lỗi 11: systemd service không khởi động (Linux)

Triệu chứng: systemctl --user status openclaw-gateway hiện “failed” hoặc “not loaded”.

Fix:

# Xem log chi tiết
journalctl --user -u openclaw-gateway --no-pager -n 50

# Cài lại service
openclaw gateway install --force

# Hoặc dùng doctor
openclaw doctor --repair

Nguyên nhân phổ biến: Node.js path thay đổi sau khi update nvm, config file sai format, hoặc quên loginctl enable-linger.

---

Lỗi 12: LaunchAgent không chạy (macOS)

Triệu chứng: Sau khi restart Mac, OpenClaw không tự khởi động.

Fix:

# Kiểm tra trạng thái
launchctl list | grep openclaw

# Load lại
launchctl load ~/Library/LaunchAgents/ai.openclaw.gateway.plist

# Nếu lỗi Gatekeeper
xattr -d com.apple.quarantine ~/Library/LaunchAgents/ai.openclaw.gateway.plist

# Hoặc cài lại
openclaw gateway install --force

---

Nhóm 4: Lỗi channel & tin nhắn

Lỗi 13: Bot không phản hồi tin nhắn

Triệu chứng: Gửi tin nhắn cho bot (Telegram, Discord, WhatsApp…) nhưng không nhận trả lời.

Diagnostic nhanh:

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

Checklist:

1. Gateway đang chạy? → openclaw gateway status → phải hiện “running”
2. Channel đã kết nối? → openclaw channels status --probe → transport phải “connected”
3. API key còn credit? → Kiểm tra dashboard provider
4. Sender có trong allowlist? → Kiểm tra channels.<tên>.allowFrom trong config
5. Pairing chưa approve? → openclaw pairing list → approve nếu có pending request

---

Lỗi 14: “mention required” trong Discord/Telegram group

Triệu chứng: Bot hoạt động trong DM nhưng không phản hồi trong group chat.

Nguyên nhân: Mặc định, OpenClaw yêu cầu mention (@bot) trong group để tránh phản hồi mọi tin nhắn.

Fix: Mention bot trong group chat: @BotName tóm tắt cuộc trò chuyện. Hoặc tắt mention requirement trong config cho group cụ thể.

---

Lỗi 15: WhatsApp pairing/login lỗi

Triệu chứng: Quét QR code nhưng WhatsApp không kết nối, hoặc bị disconnect sau một lúc.

Fix:

# Login lại
openclaw channels login

# Nếu lỗi session cũ
openclaw doctor --repair

Lưu ý: WhatsApp Web chỉ cho phép 1 session active. Nếu đang đăng nhập WhatsApp Web trên trình duyệt, cần thoát ra trước.

---

Nhóm 5: Lỗi runtime & hiệu năng

Lỗi 16: OpenClaw crash — “JavaScript heap out of memory”

Triệu chứng: Process tự tắt sau một thời gian, log hiện “heap out of memory”.

Nguyên nhân: VPS/máy ít RAM, hoặc xử lý context quá lớn.

Fix:

# Tăng memory limit
export NODE_OPTIONS="--max-old-space-size=4096"

Nếu VPS ít RAM, thêm swap:

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile && sudo swapon /swapfile
echo '/swapfile swap swap defaults 0 0' | sudo tee -a /etc/fstab

---

Lỗi 17: “Rate limit exceeded” (429)

Triệu chứng: Sau khi dùng nhiều, API trả về lỗi 429.

Nguyên nhân: Gửi quá nhiều request đến provider trong thời gian ngắn.

Fix: Nâng tier API key (OpenAI/Anthropic cho phép request nhiều hơn ở tier cao). Hoặc dùng model nhẹ hơn cho task đơn giản (Haiku thay Opus, GPT-4o-mini thay GPT-4o).

---

Checklist debug 60 giây

Khi gặp bất kỳ lỗi nào, chạy 7 lệnh này theo thứ tự:

openclaw status                      # Kiểm tra cơ bản
openclaw status --all                # Báo cáo đầy đủ
openclaw gateway probe               # Gateway có reachable không
openclaw gateway status              # Gateway health
openclaw doctor                      # Config + service health
openclaw channels status --probe     # Channel transport status
openclaw logs --follow               # Log real-time

Kết quả tốt: gateway status → “running”, gateway probe → “Reachable: yes”, doctor → không có blocking error, channels status → “connected”.

---

Lỗi riêng theo OS

macOS: “Operation not permitted”

chmod +x install.sh
xattr -d com.apple.quarantine install.sh     # Xóa Gatekeeper flag

Nếu lỗi liên quan đến quyền Screen Recording hoặc Notifications: vào System Preferences → Privacy & Security → cấp quyền cho OpenClaw.

Windows: “execution of scripts is disabled” (PowerShell)

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

Windows: WSL2 không cài được — “Virtualization not enabled”

Vào BIOS bật Intel VT-x hoặc AMD SVM Mode. Xem chi tiết tại bài cài Windows.

Linux: Config file permission warning

openclaw doctor cảnh báo file config readable bởi other users:

chmod 600 ~/.openclaw/openclaw.json

---

Cập nhật gây lỗi? Migration issues

Sau khi chạy openclaw update, config cũ có thể không tương thích với version mới. openclaw doctor tự phát hiện các legacy config key và gợi ý migrate:

openclaw doctor --repair

Các migration phổ biến: routing.allowFrom → channels.whatsapp.allowFrom, legacy talk.voiceId → talk.provider + talk.providers.<provider>, plugin manifest updates.

---

Cách đơn giản nhất: Không cài = không lỗi

Nếu bạn đã dành hàng giờ debug mà vẫn chưa chạy được, TryOpenClaw.io là giải pháp cloud đã setup sẵn mọi thứ:

• Không cần cài Node.js, Git, hay bất kỳ dependency nào
• Không lo lỗi API key, port conflict, hay permission
• Cloud riêng, tự phục hồi khi có sự cố
• Từ 99K VND/tháng, không phù hợp thì hoàn tiền vô điều kiện

Tìm hiểu thêm: Chạy OpenClaw trên Cloud — không cần cài đặt

---

Tổng kết

Hầu hết lỗi khi cài OpenClaw rơi vào 5 nhóm: lỗi cài đặt (Node.js, build tools, PATH), lỗi cấu hình (API key, config format), lỗi Gateway/daemon (port, service), lỗi channel (allowlist, pairing), và lỗi runtime (RAM, rate limit). Bước đầu tiên luôn là chạy openclaw doctor --repair — lệnh này fix được 80% vấn đề tự động.

---