Chuyển tới nội dung chính
Phiên bản: v1

Xử lý Sự cố & Khắc phục Lỗi

Cẩm nang tổng hợp giúp chẩn đoán và khắc phục các vấn đề vận hành thường gặp trên môi trường Bare-Metal, Docker, Plugin WASM và quy trình làm việc của AI Agent trong ActonOS.

1. Sự cố Cài đặt & Mạng​

Lỗi: Cổng 8080 Đã Bị Chiếm dụng (Docker)​

  • Hiện tượng: docker: Error response from daemon: Bind for 0.0.0.0:8080 failed: port is already allocated.
  • Giải pháp: Ánh xạ ActonOS sang cổng khác trên máy host: 
    docker run -d -p 8888:8080 -v acton-data:/data ghcr.io/actonos/actonos:latest
    Sau đó truy cập trang quản trị tại http://localhost:8888.

Lỗi: Trang Captive Portal Không Tự Động Mở (Bare-Metal)​

  • Hiện tượng: Đã kết nối Wi-Fi ActonOS-XXXX nhưng trình duyệt không tự bật lên.
  • Giải pháp: Mở trình duyệt web và nhập thủ công http://192.168.4.1 hoặc http://acton.local:8080. Tạm thời tắt kết nối dữ liệu di động 4G/5G trên điện thoại.

2. Sự cố Plugin WASM & Môi trường Sandbox​

Lỗi: domain not permitted in manifest net_outbound​

  • Hiện tượng: Plugin không thể gửi HTTP request; log ghi nhận vi phạm an ninh egress.
  • Giải pháp: Mở tệp manifest.json của plugin và đảm bảo tên miền đích (ví dụ "api.weather.com") đã được khai báo trong permissions.net_outbound. Đóng gói lại và tải lên tệp .actonpkg.

Lỗi: missing secret ... in vault​

  • Hiện tượng: Plugin không thể xác thực hoặc không lấy được token khi khởi chạy.
  • Giải pháp: Kiểm tra tiền tố khóa bí mật đã được khai báo trong permissions.secrets và đã nhập giá trị trong modal Cài đặt của plugin trên giao diện Web UI chưa.

Lỗi: WebSocket connection closed (-1)​

  • Hiện tượng: Kênh chat không nhận được thông điệp thời gian thực.
  • Giải pháp: Kiểm tra dịch vụ bên ngoài có yêu cầu header xác thực hoặc bắt tay token đặc thù khi thiết lập kết nối (acton_ws: ws_connect) hay không.

3. Kênh Giao tiếp & Tích hợp​

Lỗi: Telegram Bot Không Phản hồi​

  • Hiện tượng: Bot nhận được tin nhắn nhưng không trả lời.
  • Giải pháp:
    1. Kiểm tra mục Plugins trên Dashboard để đảm bảo plugin Telegram đang ở trạng thái 🟢 Running.
    2. Xác nhận bạn đã hoàn thành bước nhập Mã PIN Ghép đôi.
    3. Đảm bảo Bot Token chưa bị thu hồi qua @BotFather.

Lỗi: Discord Bot Thiếu Quyền Đọc Nội dung Tin nhắn​

  • Hiện tượng: Bot đã vào server nhưng không đọc được nội dung câu lệnh người dùng.
  • Giải pháp: Trong Discord Developer Portal, mở mục Bot → Privileged Gateway Intents và kích hoạt Message Content Intent.

Lỗi: Agent không tìm thấy report.pdf (hoặc Python báo FileNotFoundError)​

  • Hiện tượng: Bạn đã tải tệp với tên bình thường, nhưng agent tìm theo mã ID dài, hoặc script Python không mở được report.pdf.
  • Giải pháp:
    1. Kiểm tra tệp đã nằm trên trang Workspace (không chỉ đính kèm trong Chat).
    2. Nhờ: “Tìm report.pdf trong workspace.”
    3. Nhờ agent mở theo tên. ActonOS hiện tại đưa tệp workspace ra theo tên gốc cho script (user-workspace/report.pdf).
    4. Nếu tệp mới chỉ thả vào Chat, hãy nói: “Lưu vào workspace thành report.pdf.”

Lỗi: Báo “đã gửi” trên Zalo nhưng không thấy tệp​

  • Hiện tượng: Agent (hoặc log plugin) nói đã gửi tệp. Chat Zalo không hiện gì, cũng không có lỗi rõ ràng.
  • Giải pháp:
    1. Cài lại plugin Zalo mới nhất (.actonpkg). Plugin cũ dùng multipart kiểu Telegram — Zalo bỏ qua nhưng vẫn trả HTTP 200.
    2. Mở Plugins → Zalo → Logs. Plugin hiện tại báo lỗi rõ khi Zalo trả "ok": false.
    3. Gửi tới một cuộc trò chuyện Zalo cụ thể, không gửi “tất cả kênh.”
    4. Xác nhận bot được phép gửi tệp trong chat đó (đã ghép đôi, bot không bị hạn chế).

Lỗi: PDF tải về bị lỗi font​

  • Hiện tượng: Telegram hoặc Discord nhận được PDF, nhưng mở ra thì thiếu font hoặc chữ méo.
  • Giải pháp: Cài lại plugin kênh mới nhất rồi gửi lại tệp từ Workspace. Plugin cũ nhét byte PDF vào trường JSON dạng chữ, thay thế UTF-8 không hợp lệ và làm hỏng bảng font. Plugin hiện tại gửi nguyên tệp.

4. Cách ly Sandbox & Phê duyệt Hành động​

Lỗi: Công cụ Agent Thất bại do Out of Memory (OOM)​

  • Hiện tượng: Lệnh thực thi bị hủy với mã lỗi exit code 137.
  • Giải pháp: Môi trường Bubblewrap sandbox giới hạn mặc định 512 MB RAM. Biên dịch dự án lớn có thể chạm trần này. Hãy tách nhỏ công việc hoặc chạy ngoài lần gọi công cụ trong sandbox.

Lỗi: Nhiệm vụ Bị Tạm dừng Chờ Phê duyệt​

  • Hiện tượng: Nhiệm vụ hiển thị Running nhưng tiến độ không thay đổi.
  • Giải pháp: Kiểm tra thanh Thông báo Chờ Phê duyệt trên đầu Dashboard hoặc mở trang Missions → Approval Queue để duyệt hoặc từ chối hành động.