Khi gọi API OPenClaw, bạn thường gặp các lỗi như 401 Unauthorized, 500 Internal Server Error hoặc timeout kết nối. Những lỗi này không chỉ làm gián đoạn workflow mà còn có thể dẫn đến mất dữ liệu. Bài viết này tập trung vào ba mã lỗi phổ biến nhất, cung cấp hướng dẫn đầy đủ từ phân tích nguyên nhân đến các bước khắc phục, giúp bạn khôi phục dịch vụ nhanh chóng.
401 Unauthorized: Key hết hạn và thiếu quyền truy cập
Lỗi 401 thường cho thấy API key của bạn không hợp lệ hoặc không có quyền truy cập vào tài nguyên được chỉ định. Đầu tiên, hãy kiểm tra xem key đã hết hạn hay bị thu hồi đột ngột chưa – đăng nhập vào bảng điều khiển OPenClaw để xem trạng thái key. Nếu key còn hiệu lực, hãy xác nhận key đó có scope (phạm vi) cần thiết để gọi endpoint hiện tại hay không.
Cách sửa: Tạo một key mới và thay thế ngay key cũ trong code. Nếu vẫn gặp lỗi, kiểm tra định dạng của header Authorization – phải đúng là “Bearer ”. Ngoài ra, một số tính năng nâng cao yêu cầu nâng cấp gói dịch vụ, hãy đối chiếu gói đăng ký của bạn xem có bao gồm API đó không.
500 Internal Server Error: Lỗi máy chủ và chiến lược thử lại
Lỗi 500 cho thấy máy chủ OPenClaw gặp sự cố nội bộ, không liên quan đến cấu hình client. Nguyên nhân thường gặp bao gồm quá tải tạm thời, lỗi cơ sở dữ liệu hoặc bug trong bản cập nhật. Khi gặp lỗi này, đừng vội sửa code – hãy thử đợi 30 giây rồi gửi lại request.
Nếu thử lại nhiều lần vẫn báo 500, hãy kiểm tra trang trạng thái chính thức của OPenClaw (status.openclaw.io) để xem dịch vụ có hoạt động bình thường không. Nếu trang trạng thái bình thường, bạn có thể thử đổi endpoint API hoặc hạ cấp xuống phiên bản cũ hơn (ví dụ từ v1 sang v0) để bypass lỗi. Đồng thời, hãy triển khai cơ chế thử lại với exponential backoff trong code để tránh bị khóa do gửi request quá thường xuyên.
Timeout kết nối và lỗi tầng mạng
Lỗi timeout (như TimeoutError hoặc ETIMEDOUT) thường do mạng không ổn định, cấu hình proxy sai hoặc máy chủ OPenClaw phản hồi quá chậm. Bước đầu tiên: kiểm tra kết nối internet của bạn, thử ping api.openclaw.io xem có mất gói không. Nếu bạn dùng proxy công ty, hãy đảm bảo cấu hình proxy đúng và đã set biến môi trường HTTP_PROXY, HTTPS_PROXY.
Gói miễn phí của OPenClaw có rate limit rất nghiêm ngặt – khi vượt quá, request sẽ bị loại bỏ và dẫn đến timeout. Bạn nên thêm giới hạn tốc độ trong code (ví dụ tối đa 5 request mỗi giây) và đặt thời gian chờ hợp lý (khuyến nghị 30 giây). Nếu timeout vẫn thường xuyên xảy ra, hãy cân nhắc nâng cấp lên gói trả phí để có quota đồng thời cao hơn.
