❓

FAQ — Hỏi Đáp Thường Gặp

Cơ Bản⏱ 10 phút đọc

🔧 Cài Đặt & Khởi Động

Cài đặt thất bại / npm báo lỗi

Kiểm tra Node.js >= 22. Xóa cache npm rồi cài lại.

Fix

node --version  # Cần >= 22\nnpm cache clean --force\nnpm i -g openclaw@latest

Gateway không khởi động được

Kiểm tra port 18789 có bị chiếm không. Từ v2026.3.7+ cần set gateway.auth.mode.

Fix

lsof -i :18789  # Xem ai chiếm port\nopenclaw config set gateway.auth.mode token\nopenclaw gateway restart

"Permission denied" trên macOS

Cấp quyền cho thư mục .openclaw:

Fix

chmod 700 ~/.openclaw\nchmod +x $(which openclaw)

Windows báo "running scripts is disabled"

Mở PowerShell với quyền Admin và chạy:

Fix

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Docker container không chạy

Kiểm tra volume mount và port mapping:

Fix

docker logs openclaw\ndocker run -d --name openclaw \\\n  -p 18789:18789 \\\n  -v ~/.openclaw:/root/.openclaw \\\n  nicepkg/openclaw:latest

📱 Kết Nối Kênh

Telegram bot không phản hồi

Kiểm tra bot_token đúng chưa, dùng --probe để test kết nối:

Fix

openclaw channels status --probe\nopenclaw channels logs --channel telegram

WhatsApp mất kết nối liên tục

WhatsApp Web hay bị ngắt. Scan lại QR code, hoặc nên chuyển sang Telegram cho ổn định hơn.

Fix

openclaw channels login  # Scan lại QR

Discord bot offline

Kiểm tra đã bật đủ Intents trong Discord Developer Portal (MESSAGE CONTENT, SERVER MEMBERS).

Fix

openclaw channels status --probe\n# Vào Discord Developer Portal → Bot → Privileged Intents → Bật tất cả

🤖 Model & API

API key không hoạt động

Kiểm tra format key và provider có khớp không:

Fix

openclaw config validate\n# Anthropic key bắt đầu bằng sk-ant-\n# OpenAI key bắt đầu bằng sk-\n# Google key bắt đầu bằng AI...

"Rate limit exceeded"

Hết quota API. Đổi sang model khác hoặc chờ reset:

Fix

openclaw config set model gemini-2.5-pro  # Đổi model tạm\n# Hoặc dùng OpenRouter: 1 key = nhiều model

Model trả lời chậm

Dùng /fast để toggle chế độ nhanh, hoặc đổi sang model nhẹ hơn:

Fix

/fast\n# Hoặc đổi model:\nopenclaw config set model deepseek-v3

AI "câm" — chỉ chat, không làm gì được

tools.profile phải là "full" (mặc định từ v2026.3.2). Kiểm tra:

Fix

openclaw config set tools.profile full\nopenclaw gateway restart

⚡ Tính Năng

Memory/bộ nhớ không hoạt động

Chạy lệnh index lại toàn bộ bộ nhớ:

Fix

openclaw memory index --all\nopenclaw memory search --query 'test'

Heartbeat không gửi thông báo

Kiểm tra file HEARTBEAT.md không rỗng, và activeHours đúng timezone:

Fix

cat ~/.openclaw/workspace/HEARTBEAT.md\nopenclaw config get agent.heartbeat

Cron job không chạy

Kiểm tra danh sách cron và schedule syntax:

Fix

openclaw cron list\nopenclaw cron run <tên>  # Test thủ công

Context đầy — AI quên hết

Dùng /compact để nén context, hoặc /new để bắt đầu cuộc hội thoại mới:

Fix

/compact\n# Hoặc:\n/new

🔄 Cập Nhật & Bảo Trì

Cập nhật bị lỗi

Xóa cache rồi cài lại phiên bản mới nhất:

Fix

npm cache clean --force\nnpm i -g openclaw@latest\nopenclaw --version

Config lỗi sau khi upgrade

Validate config và chạy doctor:

Fix

openclaw config validate\nopenclaw doctor --deep --yes

Dung lượng đầy

Dọn dẹp các phiên cũ:

Fix

openclaw sessions cleanup\ndu -sh ~/.openclaw  # Kiểm tra dung lượng

💡 Gặp vấn đề không có trong danh sách? Chạy openclaw doctor --deep --yes — lệnh này tự chẩn đoán và sửa hầu hết lỗi phổ biến.

Chữa bách bệnh

openclaw doctor --deep --yes

←

Chương 12

Case thực chiến — Siêu cá thể

Chương 14

Mẫu Config Có Sẵn

→