Khi phát triển AI với OPenClaw, bạn chắc chắn sẽ gặp không ít lỗi làm gián đoạn công việc. Dù là lỗi gọi API thất bại hay vấn đề về quyền tài khoản, bài viết này tổng hợp một số mã lỗi thường gặp và cách khắc phục, hy vọng giúp bạn tránh được nhiều rắc rối.
Lỗi xác thực API: 401 và 403
Khi gặp 401 Unauthorized, điều đó thường có nghĩa là khóa API của bạn không hợp lệ hoặc đã hết hạn. Trước tiên, hãy kiểm tra xem khóa có bị thiếu ký tự nào không, sau đó vào trang "API Keys" trong bảng điều khiển OPenClaw để tạo lại khóa mới, nhớ sao chép đầy đủ cả khoảng trắng đầu và cuối. Còn 403 Forbidden thường xảy ra khi khóa không có quyền truy cập vào một endpoint cụ thể. Hãy đăng nhập vào bảng điều khiển, kiểm tra cài đặt vai trò và quyền hạn, xác nhận rằng tài khoản của bạn đã được gán Scope chính xác.
Lỗi timeout và mạng: 408 và 429
408 Request Timeout cho thấy máy chủ đã chờ yêu cầu của bạn quá lâu, nguyên nhân phổ biến là độ trễ mạng cao hoặc kích thước yêu cầu quá lớn. Bạn nên giới hạn dữ liệu mỗi lần gửi dưới 2MB và kiểm tra xem proxy mạng có ổn định không. 429 Too Many Requests là do bạn đã vượt quá giới hạn tốc độ – OPenClaw giới hạn số lần yêu cầu mỗi phút cho mỗi tài khoản. Lúc này hãy đợi 60 giây rồi thử lại, hoặc nâng cấp gói để tăng hạn mức, tránh việc truy vấn liên tục.
Lỗi máy chủ: 500 và 502
500 Internal Server Error là lỗi tạm thời từ phía máy chủ, thường được đội ngũ OPenClaw khắc phục trong vài phút. Bạn có thể kiểm tra trạng thái dịch vụ tại status.openclaw.com, nếu hiển thị bình thường thì thử gửi lại yêu cầu; nếu lỗi vẫn tiếp diễn, hãy liên hệ bộ phận hỗ trợ kỹ thuật kèm theo log yêu cầu đầy đủ. 502 Bad Gateway thường liên quan đến lớp gateway, chỉ cần đợi 5 phút rồi thử lại là có thể khắc phục, đừng tải lại trang liên tục.
Khóa tài khoản và hạn chế gói đăng ký
Nếu sau khi đăng nhập bạn thấy thông báo Account Locked, khả năng cao là do nhập sai mật khẩu nhiều lần hoặc phát hiện đăng nhập bất thường. Hãy đặt lại mật khẩu qua email đã liên kết và kiểm tra lịch sử đăng nhập gần đây. Ngoài ra, một số tính năng cao cấp yêu cầu gói đăng ký cụ thể – khi gặp lỗi 400 Bad Request kèm thông báo "insufficient plan", điều đó có nghĩa gói hiện tại của bạn không hỗ trợ thao tác này. Hãy nâng cấp lên phiên bản Pro để sử dụng.
Mẹo nhỏ hàng ngày để tránh lỗi
Hãy tạo thói quen chạy một bài kiểm tra quy mô nhỏ mỗi khi sửa code hoặc cấu hình, điều này giúp giảm đáng kể các lỗi phát sinh. Đồng thời luôn cập nhật SDK OPenClaw lên phiên bản mới nhất, vì phiên bản cũ có thể gây ra lỗi kỳ lạ do thay đổi API. Khi gặp lỗi khó hiểu, hãy tra cứu trực tiếp trang tài liệu chính thức về Error Code – đó là nơi cung cấp giải thích chính xác nhất.
