TÓM TẮT
Khắc phục sự cố OpenClaw bao gồm lỗi mất kết nối, lỗi xác thực, lỗi định tuyến và vấn đề về hiệu suất. Hầu hết các vấn đề bắt nguồn từ sự bất ổn của mạng, khóa API không chính xác hoặc cấu hình kênh sai. Hướng dẫn này cung cấp các bước sửa lỗi cho 15 lỗi OpenClaw phổ biến nhất.
Vấn đề cài đặt và thiết lập
Lỗi phiên bản Node.js không khớp
Vấn đề: Lệnh openclaw không tìm thấy hoặc báo lỗi "unsupported Node version."
Nguyên nhân: OpenClaw yêu cầu Node.js 22 trở lên. Các phiên bản cũ hơn thiếu các tính năng cần thiết.
Cách khắc phục:
Kiểm tra phiên bản Node của bạn:
node --version
Nếu phiên bản dưới 22, hãy cập nhật Node:
# Sử dụng nvm (khuyên dùng)
nvm install 22
nvm use 22
# Hoặc tải xuống từ nodejs.org
Cài đặt lại OpenClaw:
npm install -g openclaw@latest
Xác minh cài đặt:
openclaw --version
Bị từ chối quyền trong quá trình cài đặt
Vấn đề: npm install -g openclaw thất bại với lỗi EACCES hoặc lỗi quyền.
Nguyên nhân: npm cố gắng ghi vào các thư mục hệ thống mà không có quyền thích hợp.
Cách khắc phục:
Không sử dụng sudo. Thay vào đó, cấu hình npm để sử dụng thư mục người dùng:
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
Thêm vào hồ sơ shell của bạn (~/.zshrc hoặc ~/.bashrc):
export PATH=~/.npm-global/bin:$PATH
Tải lại shell của bạn:
source ~/.zshrc
Cài đặt OpenClaw:
npm install -g openclaw@latest
Không tìm thấy tệp cấu hình
Vấn đề: OpenClaw không thể tìm thấy ~/.openclaw/config.json sau khi cài đặt.
Nguyên nhân: Trình hướng dẫn thiết lập ban đầu (onboarding wizard) không chạy hoặc thất bại một cách âm thầm.
Cách khắc phục:
Chạy thiết lập ban đầu thủ công:
openclaw onboard
Nếu thất bại, hãy tạo thư mục cấu hình:
mkdir -p ~/.openclaw
Tạo một tệp cấu hình tối thiểu:
cat > ~/.openclaw/config.json << 'EOF'
{
"version": "1.0.0",
"providers": {},
"agents": {},
"channels": {},
"routing": []
}
EOF
Chạy thiết lập ban đầu lần nữa:
openclaw onboard
Vấn đề kết nối kênh
Không thể quét mã QR WhatsApp
Vấn đề: Mã QR xuất hiện nhưng ứng dụng WhatsApp báo "Invalid QR code" (Mã QR không hợp lệ) hoặc không phản hồi.
Nguyên nhân: Mã QR đã hết hạn hoặc sự cố mạng giữa điện thoại của bạn và OpenClaw.
Cách khắc phục:
- Đảm bảo điện thoại và máy tính của bạn đang ở cùng một mạng
- Tạo lại mã QR:
openclaw channels logout whatsapp
openclaw channels login whatsapp
- Quét trong vòng 30 giây (mã QR hết hạn nhanh chóng)
- Nếu vẫn thất bại, hãy kiểm tra cài đặt tường lửa:
# macOS
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /usr/local/bin/node
# Linux (ufw)
sudo ufw allow 18789/tcp
WhatsApp bị ngắt kết nối sau vài giờ
Vấn đề: WhatsApp hoạt động ban đầu nhưng bị ngắt kết nối sau 2-4 giờ.
Nguyên nhân: Giao thức của WhatsApp yêu cầu tín hiệu giữ kết nối định kỳ (heartbeats). Các thay đổi mạng hoặc chế độ ngủ làm gián đoạn kết nối.
Cách khắc phục:
Bật tự động kết nối lại:
openclaw channels config whatsapp --auto-reconnect true --reconnect-interval 300
Thao tác này kiểm tra kết nối cứ sau 5 phút và kết nối lại nếu cần.
Nếu bạn đang sử dụng máy tính xách tay, hãy ngăn máy tính ngủ trong khi OpenClaw đang chạy:
# macOS
caffeinate -i openclaw gateway
# Linux
systemd-inhibit --what=sleep openclaw gateway
Để sản xuất, hãy chạy OpenClaw trên máy chủ thay vì máy tính xách tay.
Bot Telegram không nhận được tin nhắn
Vấn đề: Bot đang trực tuyến nhưng không phản hồi tin nhắn.
Nguyên nhân: Bot thiếu các quyền cần thiết hoặc token không hợp lệ.
Cách khắc phục:
Kiểm tra token của bot:
curl https://api.telegram.org/bot<YOUR_TOKEN>/getMe
Nếu lệnh này trả về lỗi, hãy tạo lại token:
- Mở Telegram và nhắn tin cho @BotFather
- Gửi
/mybots - Chọn bot của bạn
- Chọn "API Token" → "Regenerate Token"
- Cập nhật OpenClaw:
openclaw channels update telegram --token NEW_TOKEN
Đối với các cuộc trò chuyện nhóm, hãy thêm bot làm quản trị viên với quyền "Read Messages" (Đọc tin nhắn).
Bot Discord hiển thị ngoại tuyến
Vấn đề: Bot xuất hiện ngoại tuyến trong danh sách máy chủ Discord.
Nguyên nhân: Thiếu "Message Content Intent" hoặc token không hợp lệ.
Cách khắc phục:
- Truy cập Discord Developer Portal
- Chọn ứng dụng của bạn
- Chuyển đến tab "Bot"
- Bật "Message Content Intent" trong Privileged Gateway Intents
- Lưu thay đổi
- Khởi động lại OpenClaw:
openclaw gateway restart
Nếu bot vẫn ngoại tuyến, hãy kiểm tra token:
openclaw channels test discord
Nếu thất bại, hãy tạo lại token trong Developer Portal và cập nhật OpenClaw.
Cầu nối iMessage không hoạt động (macOS)
Vấn đề: Kênh iMessage hiển thị "disconnected" (đã ngắt kết nối) hoặc không nhận được tin nhắn.
Nguyên nhân: Thiếu quyền truy cập hoặc ứng dụng Messages không chạy.
Cách khắc phục:
- Mở Cài đặt Hệ thống → Quyền riêng tư & Bảo mật → Trợ năng
- Thêm Terminal (hoặc ứng dụng terminal của bạn) vào danh sách được phép
- Khởi động lại OpenClaw:
openclaw gateway restart
- Đảm bảo ứng dụng Messages đang chạy và đã đăng nhập
- Kiểm tra bằng cách tự gửi tin nhắn cho mình
Nếu vẫn không hoạt động, hãy kiểm tra tiến trình cầu nối:
ps aux | grep openclaw-imessage-bridge
Nếu nó không chạy, hãy khởi động thủ công:
openclaw channels restart imessage
Lỗi xác thực và API
Khóa API không hợp lệ
Vấn đề: Lỗi "Authentication failed" (Xác thực thất bại) hoặc "Invalid API key" (Khóa API không hợp lệ) trong nhật ký.
Nguyên nhân: Khóa API sai, khóa hết hạn hoặc khóa không có quyền thích hợp.
Cách khắc phục:
Xác minh khóa API của bạn:
# Đối với Anthropic
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: YOUR_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model":"claude-sonnet-4-6","max_tokens":10,"messages":[{"role":"user","content":"Hi"}]}'
# Đối với OpenAI
curl https://api.openai.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"gpt-4","messages":[{"role":"user","content":"Hi"}],"max_tokens":10}'
Nếu lệnh curl thất bại, khóa của bạn không hợp lệ. Hãy lấy một khóa mới từ bảng điều khiển của nhà cung cấp.
Cập nhật OpenClaw:
openclaw config set --provider anthropic --api-key NEW_KEY
Khởi động lại Gateway:
openclaw gateway restart
Vượt quá giới hạn tỷ lệ
Vấn đề: Lỗi "Rate limit exceeded" (Đã vượt quá giới hạn tỷ lệ) hoặc "Too many requests" (Quá nhiều yêu cầu).
Nguyên nhân: Bạn đang gửi quá nhiều yêu cầu đến nhà cung cấp AI của mình.
Cách khắc phục:
Kiểm tra mức sử dụng của bạn:
openclaw stats --period 1h
Bật giới hạn tỷ lệ:
openclaw limits set --max-requests 50 --window 3600
Thao tác này giới hạn bạn ở 50 yêu cầu mỗi giờ. Điều chỉnh dựa trên giới hạn của nhà cung cấp của bạn.
Đối với lưu lượng truy cập đột biến, hãy bật xếp hàng:
openclaw config set --enable-queue true --queue-max-size 100
Tin nhắn sẽ được xếp hàng khi bạn đạt giới hạn tỷ lệ và được xử lý khi có dung lượng.
Không tìm thấy mô hình
Vấn đề: Lỗi "Model not found" (Không tìm thấy mô hình) hoặc "Invalid model" (Mô hình không hợp lệ).
Nguyên nhân: Bạn đã chỉ định một mô hình không tồn tại hoặc không khả dụng cho tài khoản của bạn.
Cách khắc phục:
Liệt kê các mô hình khả dụng:
# Anthropic
curl https://api.anthropic.com/v1/models \
-H "x-api-key: YOUR_KEY"
# OpenAI
curl https://api.openai.com/v1/models \
-H "Authorization: Bearer YOUR_KEY"
Cập nhật cấu hình tác nhân của bạn:
openclaw agents update default --model claude-sonnet-4-6
Khởi động lại Gateway:
openclaw gateway restart
Không đủ tín dụng
Vấn đề: Lỗi "Insufficient credits" (Không đủ tín dụng) hoặc "Payment required" (Yêu cầu thanh toán).
Nguyên nhân: Tài khoản nhà cung cấp AI của bạn đã hết tín dụng hoặc đạt giới hạn thanh toán.
Cách khắc phục:
Kiểm tra số dư tài khoản của bạn trên bảng điều khiển của nhà cung cấp:
- Anthropic: https://console.anthropic.com/settings/billing
- OpenAI: https://platform.openai.com/account/billing
Thêm tín dụng hoặc cập nhật phương thức thanh toán của bạn.
Trong khi chờ đợi, hãy định tuyến đến một mô hình miễn phí hoặc cục bộ:
openclaw agents add fallback --provider ollama --model llama2
openclaw routing add --fallback fallback
Lỗi định tuyến tin nhắn
Tin nhắn đi đến sai tác nhân
Vấn đề: Tin nhắn được định tuyến đến sai tác nhân AI mặc dù đã có quy tắc định tuyến.
Nguyên nhân: Các quy tắc định tuyến xung đột hoặc có độ ưu tiên không chính xác.
Cách khắc phục:
Liệt kê tất cả các quy tắc định tuyến:
openclaw routing list
Kiểm tra các xung đột. Các quy tắc có độ ưu tiên cao hơn sẽ khớp trước. Nếu bạn có:
Priority 5: channel=whatsapp → agent=default
Priority 10: sender=+1234567890 → agent=vip
Tin nhắn từ +1234567890 trên WhatsApp sẽ đến vip (độ ưu tiên 10 thắng).
Xóa các quy tắc xung đột:
openclaw routing remove <rule-id>
Thêm các quy tắc với độ ưu tiên chính xác:
openclaw routing add --channel whatsapp --agent default --priority 1
openclaw routing add --sender +1234567890 --agent vip --priority 10
Kiểm tra định tuyến:
openclaw routing test --channel whatsapp --sender +1234567890 --message "test"
Thao tác này hiển thị tác nhân nào sẽ xử lý tin nhắn mà không cần gửi nó.
Định tuyến từ khóa không hoạt động
Vấn đề: Tin nhắn có từ khóa cụ thể không được định tuyến đến tác nhân đã cấu hình.
Nguyên nhân: Từ khóa phân biệt chữ hoa/chữ thường hoặc tin nhắn không chứa từ khóa chính xác.
Cách khắc phục:
Đặt từ khóa không phân biệt chữ hoa/chữ thường:
openclaw routing add --keyword "debug" --agent debugging --case-insensitive
Sử dụng regex để khớp linh hoạt:
openclaw routing add --pattern "debug|error|bug" --agent debugging
Thao tác này khớp với "debug", "error" hoặc "bug" ở bất kỳ đâu trong tin nhắn.
Kiểm tra khớp từ khóa:
openclaw routing test --message "I found a debug issue"
Lỗi hàm định tuyến tùy chỉnh
Vấn đề: Hàm định tuyến tùy chỉnh báo lỗi hoặc không thực thi.
Nguyên nhân: Lỗi cú pháp, thiếu phụ thuộc hoặc giá trị trả về không chính xác.
Cách khắc phục:
Kiểm tra hàm định tuyến của bạn:
openclaw routing test-custom ~/.openclaw/routing.js --message "test"
Thao tác này chạy hàm của bạn và hiển thị kết quả hoặc lỗi.
Các vấn đề thường gặp:
- Lỗi cú pháp: Kiểm tra cú pháp JavaScript của bạn
- Thiếu giá trị trả về: Luôn trả về tên tác nhân
- Hàm async: Không sử dụng async/await trong các hàm định tuyến (chúng phải là đồng bộ)
Ví dụ hàm đúng:
module.exports = function route(message) {
// Luôn trả về một chuỗi (tên tác nhân)
if (message.channel === 'whatsapp') {
return 'whatsapp-agent';
}
return 'default';
};
Ví dụ hàm sai:
// KHÔNG LÀM ĐIỀU NÀY
module.exports = async function route(message) {
const result = await someAsyncOperation();
return result; // Hàm Async không được hỗ trợ
};
Tác nhân dự phòng không được kích hoạt
Vấn đề: Khi tác nhân chính thất bại, tin nhắn không được định tuyến đến tác nhân dự phòng.
Nguyên nhân: Tác nhân dự phòng chưa được cấu hình hoặc tác nhân chính không báo cáo lỗi chính xác.
Cách khắc phục:
Cấu hình tác nhân dự phòng:
openclaw routing set-fallback backup-agent
Kiểm tra tác nhân dự phòng:
# Tạm thời tắt tác nhân chính
openclaw agents disable default
# Gửi tin nhắn thử nghiệm
openclaw routing test --message "test"
# Sẽ hiển thị tác nhân dự phòng
Bật lại tác nhân chính:
openclaw agents enable default
Vấn đề về hiệu suất và bộ nhớ
Sử dụng bộ nhớ cao
Vấn đề: OpenClaw sử dụng hơn 2GB RAM và tiếp tục tăng.
Nguyên nhân: Dữ liệu phiên tích lũy theo thời gian mà không được dọn dẹp.
Cách khắc phục:
Kiểm tra mức sử dụng bộ nhớ:
openclaw stats --memory
Xóa các phiên cũ:
openclaw sessions clear --older-than 7d
Giảm thời gian chờ phiên:
openclaw config set --session-timeout 1800
Các phiên giờ đây sẽ hết hạn sau 30 phút không hoạt động thay vì 1 giờ mặc định.
Bật tự động dọn dẹp:
openclaw config set --auto-cleanup true --cleanup-interval 3600
Thao tác này chạy dọn dẹp mỗi giờ.
Thời gian phản hồi chậm
Vấn đề: Phản hồi AI mất hơn 30 giây hoặc hết thời gian chờ.
Nguyên nhân: Độ trễ mạng, nhà cung cấp AI chậm hoặc hàng đợi bị tồn đọng.
Cách khắc phục:
Kiểm tra trạng thái hàng đợi:
openclaw queue status
Nếu hàng đợi có hơn 50 tin nhắn, hãy tăng số lượng yêu cầu đồng thời:
openclaw config set --max-concurrent-requests 10
Thao tác này xử lý 10 tin nhắn đồng thời thay vì 3 tin nhắn mặc định.
Kiểm tra độ trễ mạng đến nhà cung cấp AI của bạn:
# Anthropic
ping api.anthropic.com
# OpenAI
ping api.openai.com
Nếu độ trễ cao (>200ms), hãy cân nhắc sử dụng nhà cung cấp khác hoặc mô hình cục bộ.
Bật thời gian chờ yêu cầu:
openclaw config set --request-timeout 30000
Các yêu cầu mất hơn 30 giây sẽ thất bại và thử lại.
Gateway không phản hồi
Vấn đề: Gateway ngừng phản hồi tin nhắn hoặc cuộc gọi API.
Nguyên nhân: Deadlock, vòng lặp vô hạn hoặc cạn kiệt tài nguyên.
Cách khắc phục:
Kiểm tra trạng thái Gateway:
openclaw gateway status
Nếu nó bị đóng băng, hãy lấy một thread dump:
kill -SIGUSR1 $(pgrep -f "openclaw gateway")
Thao tác này ghi thread dump vào ~/.openclaw/gateway.log. Tìm kiếm các hoạt động bị kẹt.
Khởi động lại Gateway:
openclaw gateway restart
Bật kiểm tra sức khỏe:
openclaw config set --health-check-interval 60
Gateway giờ đây sẽ kiểm tra sức khỏe của chính nó mỗi 60 giây và khởi động lại nếu không phản hồi.
Tăng đột biến mức sử dụng CPU
Vấn đề: OpenClaw liên tục sử dụng 100% CPU.
Nguyên nhân: Vòng lặp vô hạn, ghi nhật ký quá mức hoặc tràn tin nhắn.
Cách khắc phục:
Kiểm tra những gì đang tiêu thụ CPU:
top -p $(pgrep -f "openclaw gateway")
Giảm cấp độ nhật ký:
openclaw config set --log-level warn
Thao tác này tắt nhật ký debug và info, giảm I/O.
Kiểm tra tràn tin nhắn:
openclaw stats --messages --period 1h
Nếu bạn nhận được hơn 1000 tin nhắn mỗi giờ, hãy bật giới hạn tỷ lệ cho mỗi kênh:
openclaw channels config whatsapp --rate-limit 100 --rate-window 3600
Gateway gặp sự cố và khởi động lại
Gateway gặp sự cố khi khởi động
Vấn đề: Lệnh openclaw gateway gặp sự cố ngay lập tức mà không có thông báo lỗi.
Nguyên nhân: Tệp cấu hình bị hỏng hoặc thiếu phụ thuộc.
Cách khắc phục:
Chạy ở chế độ gỡ lỗi:
openclaw gateway --debug
Thao tác này hiển thị các thông báo lỗi chi tiết.
Các nguyên nhân phổ biến:
- Cấu hình bị hỏng: Sao lưu và đặt lại cấu hình
cp ~/.openclaw/config.json ~/.openclaw/config.json.backup
openclaw config reset
openclaw onboard
- Thiếu phụ thuộc: Cài đặt lại OpenClaw
npm uninstall -g openclaw
npm install -g openclaw@latest
- Cổng đã được sử dụng: Thay đổi cổng
openclaw gateway --port 18790
Gateway gặp sự cố trong quá trình hoạt động
Vấn đề: Gateway chạy một lúc rồi đột ngột gặp sự cố.
Nguyên nhân: Ngoại lệ chưa được xử lý, rò rỉ bộ nhớ hoặc tiến trình bên ngoài đã giết nó.
Cách khắc phục:
Kiểm tra nhật ký sự cố:
tail -100 ~/.openclaw/gateway.log
Tìm kiếm các stack trace hoặc thông báo lỗi trước khi xảy ra sự cố.
Bật ghi đống dữ liệu sự cố (crash dumps):
openclaw config set --enable-crash-dumps true
Lần gặp sự cố tiếp theo sẽ ghi một đống dữ liệu vào ~/.openclaw/crashes/. Chia sẻ điều này với nhóm OpenClaw để gỡ lỗi.
Chạy Gateway với tính năng tự động khởi động lại:
openclaw gateway --auto-restart
Gateway sẽ tự động khởi động lại sau các sự cố.
Để sản xuất, hãy sử dụng trình quản lý tiến trình:
# Sử dụng pm2
npm install -g pm2
pm2 start openclaw -- gateway
pm2 save
pm2 startup
Dữ liệu phiên bị mất sau khi khởi động lại
Vấn đề: Các cuộc trò chuyện bị đặt lại sau khi Gateway khởi động lại.
Nguyên nhân: Các phiên không được lưu trữ vào đĩa hoặc tệp phiên bị hỏng.
Cách khắc phục:
Bật tính năng lưu trữ phiên:
openclaw config set --persist-sessions true --session-file ~/.openclaw/sessions.db
Các phiên giờ đây sẽ lưu vào đĩa mỗi 30 giây.
Kiểm tra tệp phiên:
ls -lh ~/.openclaw/sessions.db
Nếu nó có kích thước 0 byte hoặc bị thiếu, các phiên không được lưu. Kiểm tra dung lượng đĩa:
df -h ~
Nếu đĩa đầy, hãy giải phóng dung lượng và khởi động lại Gateway.
Khôi phục từ bản sao lưu:
cp ~/.openclaw/sessions.db.backup ~/.openclaw/sessions.db
openclaw gateway restart
Các vấn đề cụ thể theo nền tảng
macOS: "openclaw" không thể mở
Vấn đề: macOS chặn OpenClaw với cảnh báo "unidentified developer" (nhà phát triển không xác định).
Nguyên nhân: Tính năng bảo mật Gatekeeper của macOS.
Cách khắc phục:
Cho phép OpenClaw:
xattr -d com.apple.quarantine $(which openclaw)
Hoặc truy cập Cài đặt Hệ thống → Quyền riêng tư & Bảo mật và nhấp vào "Cho phép Dù sao" (Allow Anyway) bên cạnh cảnh báo OpenClaw.
Linux: Bị từ chối quyền đối với inotify
Vấn đề: "ENOSPC: System limit for number of file watchers reached." (Đã đạt đến giới hạn hệ thống cho số lượng bộ theo dõi tệp.)
Nguyên nhân: Linux giới hạn số lượng tệp mà một tiến trình có thể theo dõi.
Cách khắc phục:
Tăng giới hạn:
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
Khởi động lại OpenClaw:
openclaw gateway restart
Windows: Không tìm thấy lệnh
Vấn đề: Lệnh openclaw không được nhận dạng trên Windows.
Nguyên nhân: Thư mục npm global bin không có trong PATH.
Cách khắc phục:
Tìm thư mục npm global:
npm config get prefix
Thêm nó vào PATH:
- Mở Thuộc tính Hệ thống (System Properties) → Biến môi trường (Environment Variables)
- Chỉnh sửa "Path" trong các biến Người dùng (User variables)
- Thêm
C:\Users\YourName\AppData\Roaming\npm(hoặc đường dẫn từ trên) - Nhấp OK và khởi động lại terminal của bạn
Xác minh:
openclaw --version
Docker: Vấn đề mạng
Vấn đề: OpenClaw trong Docker không thể kết nối với các nền tảng nhắn tin.
Nguyên nhân: Sự cô lập mạng của Docker.
Cách khắc phục:
Chạy với mạng máy chủ (host network):
docker run --network host openclaw/openclaw gateway
Hoặc hiển thị cổng Gateway:
docker run -p 18789:18789 openclaw/openclaw gateway
Đối với WhatsApp, bạn cần hiển thị các cổng bổ sung để quét mã QR:
docker run -p 18789:18789 -p 3000:3000 openclaw/openclaw gateway
Công cụ gỡ lỗi và nhật ký
Bật ghi nhật ký gỡ lỗi
Nhận nhật ký chi tiết:
openclaw config set --log-level debug
openclaw gateway restart
Nhật ký được lưu vào ~/.openclaw/gateway.log theo mặc định.
Xem nhật ký trong thời gian thực:
tail -f ~/.openclaw/gateway.log
Kiểm tra từng thành phần riêng lẻ
Kiểm tra kênh:
openclaw channels test whatsapp
openclaw channels test telegram
openclaw channels test discord
Kiểm tra tác nhân:
openclaw agents test default --message "Hello"
Kiểm tra định tuyến:
openclaw routing test --channel whatsapp --sender +1234567890 --message "debug issue"
Kiểm tra trạng thái Gateway
Lấy trạng thái hiện tại:
openclaw gateway inspect
Thao tác này hiển thị:
- Các kênh đang hoạt động và trạng thái của chúng
- Các tác nhân đã cấu hình và tình trạng của chúng
- Các quy tắc định tuyến và độ ưu tiên
- Kích thước hàng đợi và các tin nhắn đang chờ xử lý
- Mức sử dụng bộ nhớ và thời gian hoạt động
Xuất chẩn đoán
Tạo báo cáo chẩn đoán:
openclaw diagnostics export > openclaw-diagnostics.json
Thao tác này bao gồm:
- Cấu hình (đã ẩn khóa API)
- Nhật ký gần đây
- Số lượng lỗi
- Các chỉ số hiệu suất
- Thông tin hệ thống
Chia sẻ điều này với bộ phận hỗ trợ khi báo cáo sự cố.
Gỡ lỗi mạng
Kiểm tra kết nối đến các nhà cung cấp AI:
openclaw network test anthropic
openclaw network test openai
Thao tác này kiểm tra:
- Phân giải DNS
- Bắt tay TLS
- Khả năng truy cập điểm cuối API
- Độ trễ
Nếu bất kỳ kiểm tra nào thất bại, bạn đang gặp sự cố mạng.
Câu hỏi thường gặp
Tại sao OpenClaw sử dụng nhiều bộ nhớ như vậy?
OpenClaw giữ lịch sử phiên trong bộ nhớ để truy cập nhanh. Mỗi phiên lưu trữ toàn bộ ngữ cảnh cuộc trò chuyện. Nếu bạn có 100 phiên hoạt động, mỗi phiên có 50 tin nhắn, đó là 5000 tin nhắn trong bộ nhớ.
Giảm mức sử dụng bộ nhớ:
- Giảm thời gian chờ phiên
- Bật tự động dọn dẹp
- Giới hạn độ dài ngữ cảnh cho mỗi phiên
openclaw config set --session-timeout 1800 --auto-cleanup true --max-context-length 50
Tôi có thể chạy OpenClaw mà không có internet không?
Có, nếu bạn sử dụng mô hình AI cục bộ. Cài đặt Ollama và cấu hình OpenClaw để sử dụng nó:
# Cài đặt Ollama
curl https://ollama.ai/install.sh | sh
# Tải một mô hình
ollama pull llama2
# Cấu hình OpenClaw
openclaw agents add local --provider ollama --model llama2 --endpoint http://localhost:11434
Các nền tảng nhắn tin vẫn cần internet, nhưng suy luận AI chạy cục bộ.
Làm cách nào để di chuyển sang một máy mới?
Xuất cấu hình của bạn:
openclaw config export > openclaw-backup.json
Sao chép openclaw-backup.json sang máy mới.
Cài đặt OpenClaw:
npm install -g openclaw@latest
Nhập cấu hình:
openclaw config import openclaw-backup.json
Kết nối lại các kênh (mã QR và token không được chuyển):
openclaw channels login whatsapp
openclaw channels update telegram --token YOUR_TOKEN
Tại sao tin nhắn đến không đúng thứ tự?
OpenClaw xử lý tin nhắn đồng thời. Nếu bạn gửi 3 tin nhắn nhanh chóng, chúng có thể đến nhà cung cấp AI theo các thứ tự khác nhau tùy thuộc vào thời gian mạng.
Bật xử lý tuần tự:
openclaw config set --max-concurrent-requests 1
Thao tác này xử lý từng tin nhắn một, duy trì thứ tự. Nó chậm hơn nhưng đảm bảo trình tự.
Tôi có thể sử dụng OpenClaw cho sản xuất không?
Có, nhưng hãy làm theo các hướng dẫn sau:
- Chạy trên máy chủ, không phải máy tính xách tay
- Sử dụng trình quản lý tiến trình (pm2, systemd)
- Bật tính năng lưu trữ phiên
- Thiết lập giám sát và cảnh báo
- Cấu hình giới hạn tỷ lệ
- Sử dụng proxy ngược (nginx) cho giao diện người dùng Điều khiển
- Bật HTTPS
- Sao lưu cấu hình thường xuyên
Ví dụ dịch vụ systemd:
[Unit]
Description=OpenClaw Gateway
After=network.target
[Service]
Type=simple
User=openclaw
WorkingDirectory=/home/openclaw
ExecStart=/usr/bin/openclaw gateway --port 18789
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target
Làm cách nào để báo cáo lỗi?
- Tạo chẩn đoán:
openclaw diagnostics export > diagnostics.json
- Mở một vấn đề trên GitHub
- Bao gồm:
- Phiên bản OpenClaw (
openclaw --version) - Phiên bản Node.js (
node --version) - Hệ điều hành
- Các bước để tái tạo lỗi
- Báo cáo chẩn đoán (ẩn dữ liệu nhạy cảm)
Kết luận
Hầu hết các vấn đề của OpenClaw đều bắt nguồn từ sự cố mạng, cấu hình không chính xác hoặc các quirks cụ thể của nền tảng. Hướng dẫn này bao gồm 15 lỗi phổ biến nhất và cách khắc phục chúng.
Các bước khắc phục sự cố chính:
- Kiểm tra nhật ký trước tiên (
~/.openclaw/gateway.log) - Kiểm tra từng thành phần riêng lẻ (kênh, tác nhân, định tuyến)
- Bật chế độ gỡ lỗi để có lỗi chi tiết
- Sử dụng các công cụ chẩn đoán để xuất trạng thái
- Tham gia cộng đồng để được trợ giúp
Nếu bạn đang xây dựng quy trình làm việc API cùng với OpenClaw, hãy xem xét Apidog để thiết kế, kiểm tra và tài liệu API. Nó bổ trợ giao diện đàm thoại của OpenClaw bằng cách quản lý API có cấu trúc.
nút
Các bước tiếp theo:
- Đánh dấu hướng dẫn này để tham khảo nhanh
- Thiết lập giám sát để phát hiện sớm các vấn đề
- Tham gia OpenClaw Discord để được trợ giúp theo thời gian thực
- Đóng góp các bản sửa lỗi cho dự án trên GitHub