Khắc phục lỗi OPenClaw: Mã lỗi thường gặp và cách xử lý nhanh

Gặp mã lỗi khi sử dụng OPenClaw thực sự rất phiền phức. Dù là lỗi gọi API thất bại hay kết nối bị timeout, việc nhanh chóng xác định vấn đề mới có thể khôi phục luồng công việc. Bài viết này tổng hợp các lỗi tần suất cao của OPenClaw và các bước sửa thủ công, giúp bạn đi đúng đường.

API Key không hợp lệ hoặc hết hạn

Mã lỗi 401 thường có nghĩa key sai hoặc đã hết hạn. Trước tiên hãy đăng nhập vào trang quản trị OPenClaw, vào mục "API Keys" để kiểm tra trạng thái key hiện tại. Nếu hiển thị màu đỏ "Expired", hãy tạo key mới ngay và thay thế giá trị cũ trong code. Lưu ý khi copy đừng để thừa khoảng trắng – nhiều người mới mắc lỗi nhỏ này.

Nếu key vẫn hợp lệ nhưng báo lỗi 403, có thể do chưa chọn đúng phạm vi quyền. Đảm bảo key đã được gắn quyền truy cập các model bạn cần, ví dụ "claw-4" hoặc "claw-vision". Sau khi lưu, đợi 1 phút rồi thử lại – đồng bộ quyền của OPenClaw đôi khi bị chậm.

Giới hạn tốc độ (lỗi 429)

Gửi request quá thường xuyên sẽ kích hoạt Rate Limit, mã lỗi 429. Bản miễn phí của OPenClaw cho phép tối đa 30 request mỗi phút, bản trả phí từ 60-200 tùy gói. Giải pháp đơn giản: thêm độ trễ trong code. Ví dụ trong Python dùng time.sleep(2) để mỗi request cách nhau ít nhất 2 giây. Nếu xử lý hàng loạt, nên dùng thuật toán exponential backoff.

Ngoài ra kiểm tra xem có đang chạy nhiều script cùng lúc không. Trang "Usage" trong Dashboard hiển thị tốc độ request theo thời gian thực – nếu vượt quá vạch đỏ thì dừng lại vài phút. Bình tĩnh rồi chạy lại, đừng cố đấm ăn xôi.

Model không khả dụng hoặc timeout

Mã lỗi 503 hoặc 504 cho thấy máy chủ OPenClaw đang quá tải hoặc mạng không ổn định. Trước tiên ping api.openclaw.com – nếu tỉ lệ mất gói trên 10%, hãy thử đổi môi trường mạng, chẳng hạn chuyển sang hotspot điện thoại. Nếu ping bình thường, khả năng cao model đang quá tải, bạn có thể chuyển sang model dự phòng, ví dụ từ "claw-4" sang "claw-3.5".

Một trường hợp khác là request body quá lớn dẫn đến timeout. OPenClaw giới hạn đầu vào tối đa 8K token (bản trả phí 16K). Trước khi dùng, ước lượng số token bằng len(text) / 4, nếu vượt quá thì chia nhỏ và gửi từng phần. Nếu vẫn không được, hãy bật chế độ Stream – kết quả trả về từ từ, ít nhất không bị treo.

Tài khoản bị khóa hoặc trạng thái bất thường

Nhập sai mật khẩu liên tục hoặc đăng nhập bất thường sẽ kích hoạt khóa tài khoản, mã lỗi 400 kèm mô tả "Account Locked". Hãy kiểm tra email đã đăng ký để tìm link mở khóa từ OPenClaw, thường chỉ cần nhấp vào là khôi phục. Nếu không nhận được email, liên hệ hỗ trợ và cung cấp tên tài khoản cùng ảnh chụp lỗi – họ xử lý khá nhanh.

Lưu ý không dùng proxy IP công cộng để đăng nhập đi đăng nhập lại, vì hệ thống chống gian lận của OPenClaw khá nhạy. Nên bật xác thực hai bước với Google Authenticator – vừa an toàn vừa giảm nguy cơ bị khóa nhầm.