Xử lý sự cố

Các vấn đề thường gặp và cách giải quyết.

Vấn đề Gateway

Gateway không khởi động

• Xung đột cổng, Một tiến trình khác có thể đang sử dụng cổng 18789. Kiểm tra bằng lsof -i :18789.
• Lỗi cấu hình, JSON không hợp lệ trong neotask.json. Gateway xác thực cấu hình khi khởi động và báo cáo lỗi cụ thể.
• Khóa Gateway, Một phiên bản trước đó có thể đã để lại tệp khóa cũ. Công cụ chẩn đoán có thể phát hiện và khắc phục điều này.
• Phiên bản Node.js, Neotask yêu cầu Node 22+.

Gateway khởi động nhưng không có kênh kết nối

• Thiếu thông tin xác thực, Mỗi kênh cần xác thực riêng (bot token, quét mã QR, API key).
• Vấn đề mạng, Các kênh cần truy cập internet để kết nối với API nền tảng nhắn tin.
• Giới hạn tốc độ, Một số nền tảng giới hạn tốc độ các kết nối mới. Chờ và thử lại.

Không thể kết nối từ ứng dụng desktop

• Sai cổng, Đảm bảo ứng dụng desktop kết nối với cổng Gateway đúng.
• Token không khớp, Token Gateway phải khớp.
• Tường lửa, Đảm bảo cổng có thể truy cập nếu Gateway đang trên một máy khác.

Vấn đề kênh

WhatsApp không kết nối

• Mã QR đã hết hạn, Mã QR hết hạn sau khoảng 60 giây. Quét lại nhanh chóng.
• Giới hạn đa thiết bị, WhatsApp giới hạn các thiết bị được liên kết.
• Phiên bị hỏng, Xóa thư mục phiên WhatsApp và ghép nối lại.

Bot Telegram không nhận được tin nhắn

• Bot token không hợp lệ, Xác minh bot token của bạn với BotFather.
• Chế độ riêng tư, Các bot chỉ thấy tin nhắn khi được đề cập trong các nhóm theo mặc định.
• Xung đột webhook, Một dịch vụ khác có thể đang tiêu thụ tin nhắn.

Bot Discord không phản hồi

• Thiếu intent, Bật các Gateway Intents yêu cầu trong Discord Developer Portal.
• Thiếu quyền, Bot cần quyền đọc và gửi trong các kênh mục tiêu.

Vấn đề mô hình

Lỗi xác thực

• Key chưa được cấu hình, Đảm bảo API key của nhà cung cấp được đặt.
• Key đã hết hạn, Một số OAuth token hết hạn. Xác thực lại.
• Giới hạn tốc độ, Xoay vòng key sẽ chuyển đổi tự động nếu bạn có nhiều key.

Phản hồi chậm

• Lựa chọn mô hình, Các mô hình lớn hơn thì chậm hơn. Thử một mô hình nhanh hơn cho các nhiệm vụ nhanh.
• Kích thước ngữ cảnh, Các cuộc trò chuyện dài làm chậm xử lý. Thử /compact.
• Độ trễ mạng, Kiểm tra kết nối với nhà cung cấp mô hình của bạn.

Vấn đề node

Ứng dụng đồng hành không thể tìm thấy Gateway

• Chế độ ràng buộc, Gateway phải được ràng buộc với LAN hoặc Tailnet (không phải loopback) cho các thiết bị bên ngoài.
• Cùng mạng, Để khám phá Bonjour, cả hai thiết bị phải trên cùng một mạng.
• Nhập thủ công, Nhập host và cổng Gateway thủ công trong cài đặt ứng dụng.

Vấn đề phiên

Vượt quá cửa sổ ngữ cảnh

• Nén, Sử dụng /compact để tóm tắt và đặt lại ngữ cảnh.
• Bật tự động nén, Đặt ngưỡng nén trong cấu hình.
• Phiên mới, Bắt đầu lại với /new.

Chẩn đoán

Công cụ chẩn đoán tích hợp kiểm tra các vấn đề thường gặp và có thể tự động khắc phục nhiều vấn đề:

• Xác thực cấu hình
• Quyền tệp
• Kết nối kênh
• Trạng thái xác thực mô hình
• Tương thích Node.js
• Cấu hình mạng

Kiểm tra nhật ký Gateway để biết thông tin lỗi chi tiết. Endpoint /health cung cấp trạng thái có thể đọc bằng máy của tất cả các thành phần.

Nhận trợ giúp

1. Chạy công cụ chẩn đoán để tự động khắc phục
2. Kiểm tra nhật ký Gateway để biết thông báo lỗi chi tiết
3. Liên hệ hỗ trợ qua widget chat Intercom trong ứng dụng desktop