OpenClaw là công cụ AI Agent mã nguồn mở dùng để cấu hình và quản lý tác nhân AI, nhưng trong thực tế thường gặp lỗi khởi động hoặc kết nối proxy. Bài viết này tổng hợp các mã lỗi phổ biến nhất cùng nguyên nhân, đồng thời cung cấp các bước sửa lỗi đã được kiểm chứng, giúp bạn nhanh chóng khôi phục OpenClaw hoạt động ổn định.
Lỗi khởi động: Sai cấu hình tệp và thiếu phụ thuộc
Khi OpenClaw báo lỗi "config.json parse error" hoặc "missing required field", thường do định dạng tệp cấu hình sai hoặc thiếu tham số quan trọng. Hãy kiểm tra tệp config.json có chứa các trường bắt buộc như api_key, model_endpoint và proxy_mode hay không, đồng thời dùng công cụ kiểm tra JSON để xác nhận không có dấu phẩy thừa hoặc nháy kép không khớp. Nếu gặp lỗi "dependency not found", nghĩa là chưa cài gói Python cần thiết, hãy chạy pip install -r requirements.txt để khắc phục.
Một số người dùng trên Windows còn gặp lỗi "permission denied" do OpenClaw cần quyền đọc cài đặt proxy hệ thống. Hãy chạy terminal với quyền Administrator, hoặc kiểm tra xem phần mềm diệt virus có chặn quyền nghe cổng không.
Kết nối proxy bất thường: Cổng bị chiếm dụng và xung đột proxy mạng
Khi OpenClaw báo "port already in use", nghĩa là cổng mặc định (ví dụ 8080) đã bị chương trình khác chiếm dụng. Có thể dùng lsof -i :8080 (Linux/macOS) hoặc netstat -ano | findstr 8080 (Windows) để tìm tiến trình đang chiếm và kết thúc nó, hoặc thêm tham số --port 8081 khi khởi động để chuyển cổng. Nếu xuất hiện lỗi "connection refused", cần kiểm tra lại địa chỉ và cổng của dịch vụ AI mục tiêu, cũng như xem tường lửa cục bộ có cho phép kết nối không.
Đối với người dùng dùng proxy hệ thống, OpenClaw có thể không phân luồng đúng giữa mạng nội bộ và mạng ngoài. Nên đặt proxy_mode trong config.json thành exclusive hoặc direct để tránh lồng proxy.