Gặp lỗi API hoặc timeout khi dùng OPenClaw? Bài viết này tổng hợp cách kiểm tra và giải quyết một số lỗi phổ biến, giúp bạn nhanh chóng khôi phục luồng làm việc mà không cần ngồi nhìn chằm chằm vào thông báo lỗi.
Lỗi 401 Unauthorized: Kiểm tra khóa API và quyền truy cập
Mã lỗi 401 thường có nghĩa là yêu cầu thiếu thông tin xác thực hợp lệ. Trước tiên, hãy kiểm tra xem khóa API của bạn đã được dán chính xác vào biến môi trường hoặc tệp cấu hình hay chưa, lưu ý không có khoảng trắng hoặc dòng thừa ở đầu và cuối. Nếu bạn sao chép khóa từ bảng điều khiển và dán trực tiếp, hãy thử nhập lại bằng tay — nhiều vấn đề phát sinh do thiếu ký tự khi sao chép. Ngoài ra, một số mô hình hoặc endpoint yêu cầu bật quyền bổ sung; hãy vào bảng điều khiển nhà phát triển để đảm bảo mục "Cho phép truy cập" đã được chọn.
Lỗi 429 Rate Limit: Điều chỉnh khoảng cách gọi và hạn mức
Gửi quá nhiều yêu cầu trong thời gian ngắn có thể gây ra giới hạn tốc độ, trả về mã 429. Lúc này đừng thử lại một cách mù quáng, hãy tạm dừng 5-10 giây, sau đó thử lại với chiến lược backoff theo cấp số nhân. Bạn có thể thiết lập hàng đợi yêu cầu hoặc thêm cơ chế sleep để tránh vượt quá giới hạn tốc độ. Nếu tình trạng này xảy ra thường xuyên, hãy kiểm tra xem tài khoản có đang trong giai đoạn dùng thử hay không (hạn mức dùng thử thường thấp hơn); nâng cấp gói hoặc yêu cầu tăng hạn mức sẽ giải quyết triệt để. Ngoài ra, hãy xác nhận xem có ứng dụng nào khác đang sử dụng cùng một khóa API hay không — dùng chung khóa dễ bị chạm ngưỡng giới hạn.
Kết nối timeout hoặc Socket Hang Up: Kiểm tra mạng và proxy
"Connection Timeout" hoặc "Socket Hang Up" thường do mạng không ổn định hoặc cấu hình proxy sai. Trước tiên, hãy thử kết nối trực tiếp đến máy chủ chính thức của OPenClaw, dùng lệnh ping hoặc curl để kiểm tra độ trễ. Nếu bạn sử dụng proxy, hãy xác nhận giao thức và cổng đúng, đồng thời proxy không chặn lưu lượng. Một số mạng nội bộ doanh nghiệp có thể chặn các cổng không chuẩn; chuyển sang cổng HTTPS (443) có thể vượt qua một số hạn chế. Ngoài ra, thời gian timeout cài đặt quá ngắn cũng có thể gây ra cảnh báo sai; hãy thử tăng tham số timeout từ mặc định 10 giây lên 30 giây.
Lỗi 500 Internal Server Error: Ưu tiên kiểm tra định dạng body yêu cầu
Khi máy chủ trả về lỗi 500, đừng vội nghi ngờ máy chủ bị sập — phần lớn là do định dạng yêu cầu bạn gửi không đúng. Kiểm tra xem JSON có hợp lệ không, tên trường có được viết chính xác không (ví dụ: "model" bị viết thành "module"). Đặc biệt để ý xem giá trị boolean và số có bị đặt trong dấu ngoặc kép hay không, chẳng hạn "temperature": true có thể gây lỗi ngay lập tức. Nếu body yêu cầu quá lớn, hãy thử chia nhỏ thành nhiều đoạn để gửi, hoặc kiểm tra xem trong mảng thông báo có chứa role không được hỗ trợ hay không (như vô tình dùng role function mà mô hình không hỗ trợ).
Lỗi 403 Forbidden: Kiểm tra trạng thái tài khoản và giới hạn khu vực
Lỗi 403 có thể do tài khoản bị khóa hoặc giới hạn khu vực địa lý. Trước tiên, đăng nhập vào trang web chính thức của OPenClaw để kiểm tra trạng thái tài khoản, xem có thông báo nợ hoặc vi phạm nào không. Một số mô hình chỉ khả dụng cho các khu vực cụ thể; nếu bạn dùng IP từ khu vực không được hỗ trợ, hãy thử chuyển sang node khác hoặc bật chế độ global. Ngoài ra, quyền truy cập của một số tài khoản dùng thử miễn phí có thể giảm dần theo thời gian; gia hạn hoặc nâng cấp lên gói trả phí thường sẽ giải quyết được lỗi 403.
