AI Agent

Vị trí trong trang admin: System › Settings › AI provider (/settings/ai) — công tắc kích hoạt module và provider; System › Admin › License & updates (/license) — công tắc module. Vị trí trong portal: AI Agent (/ai/agent) và trang /chat/agent, hoặc chế độ Agent bên trong khung chat.

Chức năng

AI Agent kết nối tới VM Linux của khách hàng qua SSH và thực hiện các tác vụ được mô tả bằng ngôn ngữ tự nhiên: "kiểm tra tình trạng hệ thống", "cài đặt Docker", "tìm các lỗi gần đây", "giải phóng dung lượng đĩa". Hệ thống hiển thị từng lệnh được đề xuất và kết quả đầu ra tương ứng. Các lệnh chỉ đọc có thể tự động thực thi; bất kỳ thao tác nào làm thay đổi máy chủ đều phải đợi khách hàng nhấn Run.

Yêu cầu

Hạng mục	Yêu cầu
Module AI và provider	Module AI đang bật và AI provider đang hoạt động. Agent cũng cần một model hỗ trợ tool calling.
openssh-client trên máy chủ panel	Agent chạy các lệnh bằng chương trình ssh có sẵn trên panel (/usr/bin/ssh). Trình cài đặt sẽ cài openssh-client; kiểm tra bằng lệnh ssh -V. Nếu thiếu, Agent sẽ báo lỗi "ssh client is not installed on the panel server".
Không cần SSH gateway riêng	Trong bản cài đặt mặc định, SSH tích hợp sẵn sẽ được sử dụng và không cần đến web terminal ssh-proxy. Chỉ khi tính năng web SSH tùy chọn (feature_ssh_web) được kích hoạt và dịch vụ ssh-proxy đã được cài đặt thì Agent mới chuyển qua kết nối thông qua ssh-proxy.
Mạng	Máy chủ panel phải kết nối được tới IP của VM qua cổng SSH (mặc định là 22). Hãy kiểm tra tường lửa và security group giữa panel với mạng guest.
VM	Thuộc sở hữu của khách hàng, đang running, không bị khóa, chạy hệ điều hành Linux (từ chối VM Windows), có địa chỉ IP công khai hoặc có thể truy cập được.
Thông tin đăng nhập SSH	Tên người dùng và mật khẩu đăng nhập của VM do NexCMP lưu trữ (được mã hóa và lưu lại khi tạo VM hoặc khi đặt lại mật khẩu), hoặc SSH key vận hành của panel nếu có cài đặt. Nếu không có thông tin nào, Agent sẽ thông báo không thể đăng nhập.

Chuẩn bị hạ tầng

1. Kiểm tra SSH client trên máy chủ panel:

   ssh -V
   sudo apt-get install -y openssh-client   # only if missing

2. Kiểm tra máy chủ panel có thể mở kết nối SSH tới guest VM:

   nc -vz 198.51.100.10 22

   Thay thế địa chỉ bằng IP của một VM thử nghiệm. Nếu kết nối thất bại, hãy khắc phục sự cố định tuyến hoặc tường lửa trước.

3. Hãy đảm bảo máy khách cho phép đăng nhập bằng mật khẩu đối với người dùng được NexCMP lưu trữ (một số image đám mây tắt tính năng này), hoặc operations key của panel đã được cài đặt trên máy khách.

Kết nối trong NexCMP

1. Hoàn tất AI provider: bật module, lưu provider, Test connection hiển thị màu xanh lá.
2. Không cần cấu hình thêm gì khác ở phía quản trị viên. Công tắc module sẽ hiển thị các mục AI Agent trong cổng thông tin khách hàng.
3. Dưới vai trò khách hàng: mở AI Agent, chọn một máy chủ đang chạy và nhấp vào Choose server. Trang trước tiên sẽ kiểm tra SSH bằng một lệnh an toàn cố định (không dùng lệnh gọi AI) và hiển thị SSH connected hoặc lý do thất bại.
4. Nhập tác vụ hoặc chọn một tác vụ nhanh (Check system health, Install Docker, Install Nginx, Find recent errors, Security check, Free up disk space).

Cách thực thi lệnh

• Từ đâu: từ máy chủ panel, sử dụng client ssh của hệ thống, từng lệnh không tương tác tại một thời điểm. Mục tiêu luôn là IP của VM từ cơ sở dữ liệu, không bao giờ lấy từ request; chỉ có thể truy cập VM đang chạy, không bị khóa của chính chủ sở hữu.

• Xác thực: mật khẩu đã lưu được truyền qua một helper SSH_ASKPASS dùng một lần trong biến môi trường tiến trình — mật khẩu không được ghi vào ổ đĩa hay đặt trên dòng lệnh. Host key không được ghim cố định (VM được cài đặt lại với key mới). Đầu ra cho mỗi lệnh được giới hạn ở mức 200 KB và mỗi lệnh có giới hạn thời gian (60 giây).

• Vòng lặp Agent: AI đề xuất các lệnh và đọc đầu ra; một lượt kết thúc sau tối đa 10 bước.

• Các chế độ:

  Chế độ	Hành vi
  Confirm	Mọi lệnh đều chờ Run.
  Auto	Chỉ các lệnh vượt qua danh sách cho phép nghiêm ngặt chỉ đọc mới tự chạy (ví dụ df -h, ps, journalctl). Bất kỳ lệnh nào khác và bất kỳ lệnh nào trình phân tích cú pháp không thể phân tích chắc chắn (biến số, thay thế lệnh, chuyển hướng tệp) đều phải chờ Run.

• Nhãn rủi ro: các lệnh ghi đè hoặc xóa tệp, ghi vào ổ đĩa, thay đổi tài khoản hoặc SSH Keys, gửi dữ liệu đến máy chủ bên ngoài, mở kết nối mạng thô, chạy mã bị làm mờ, tải xuống và chạy script, tắt hoặc khởi động lại máy, hay truy cập máy chủ khác luôn hiển thị Needs confirmation, ngay cả trong chế độ Auto.

• Đầu ra không tin cậy: đầu ra của lệnh được hiển thị cho mô hình dưới dạng dữ liệu không tin cậy; các chỉ dẫn bên trong đầu ra sẽ không được làm theo.

Kiểm tra

1. Chọn một VM thử nghiệm đang chạy. Trang hiển thị SSH connected.
2. Yêu cầu "Check CPU, RAM and disk". Ở chế độ Auto, các lệnh chỉ đọc sẽ chạy và câu trả lời tóm tắt kết quả của chúng.
3. Yêu cầu "Install Nginx". Lệnh cài đặt xuất hiện kèm Run và Skip; không có gì chạy cho đến khi bạn nhấn Run.
4. Bộ đếm ở trên cùng hiển thị số lượt gọi AI đã dùng hôm nay (ví dụ 3/300).

Hạn mức & lưu ý

• Giới hạn hàng ngày: 300 lượt gọi AI cho mỗi khách hàng mỗi ngày (UTC); giới hạn đặt lại vào 00:00 UTC. Khi hết hạn ngạch, Agent sẽ trả lời "Daily AI quota reached".
• Tính đồng thời: tối đa 2 tác vụ Agent chạy cùng lúc cho mỗi khách hàng; một phiên chỉ chạy một lượt tại một thời điểm.
• Phiên làm việc: tối đa 100 tin nhắn mỗi phiên, 4,000 ký tự mỗi tin nhắn. Phiên làm việc thuộc về một VM; nếu VM bị xóa hoặc chuyển giao, phiên làm việc cũ sẽ chuyển sang trạng thái chỉ đọc.
• VM bị khóa, dừng hoặc Windows: VM sẽ hiển thị là Locked, Stopped, Windows hoặc No address và không thể chọn.
• Mạo danh: quản trị viên đang mạo danh khách hàng không thể sử dụng các tính năng thông tin xác thực của Agent (xem Log in as a customer).
• Trách nhiệm: Agent có thể mắc lỗi. Cổng thông tin luôn nhắc khách hàng xem xét kỹ các lệnh trước khi chạy. Hãy nêu rõ trong điều khoản của bạn rằng khách hàng chịu trách nhiệm về các lệnh mà họ phê duyệt.
• Tắt module AI sẽ gỡ bỏ các mục Agent và các tuyến đường sẽ phản hồi 404 module_disabled.

Xử lý sự cố

Hiện tượng	Nguyên nhân	Cách khắc phục
"ssh client chưa được cài đặt trên panel server (apt install openssh-client)"	Không có binary ssh	sudo apt-get install -y openssh-client.
"Agent không thể đăng nhập" / ssh: no saved credentials for this VM	Không có mật khẩu được lưu và không có operations key	Đặt lại mật khẩu VM trong portal để lưu lại, hoặc cài đặt operations key.
"Máy chủ không phản hồi kịp thời"	Tường lửa, SSH không lắng nghe, VM đang bận	Kiểm tra nc -vz <ip> 22 từ panel server; khởi động sshd trong VM.
"Không thể kết nối SSH trên máy chủ này"	Định tuyến hoặc security group	Cho phép panel server kết nối tới VM qua cổng 22.
"VM không chạy" / "Forbidden"	VM đã dừng, bị khóa, đã xóa hoặc không thuộc về khách hàng	Khởi động VM, mở khóa hoặc chọn VM khác.
"Không khả dụng: N (đã dừng, bị khóa hoặc Windows)"	Các nguyên nhân được liệt kê ở trên	VM phải là Linux và đang chạy.
"SSH gateway tạm thời không khả dụng"	Tính năng Web SSH đã bật nhưng ssh-proxy không hoạt động	Khởi động ssh-proxy, hoặc tắt tính năng web SSH để sử dụng SSH tích hợp sẵn.
"AI phản hồi quá chậm (quá 90 giây)"	Provider phản hồi chậm	Sử dụng model nhanh hơn hoặc giảm Reasoning effort.
"Đã đạt hạn mức AI hàng ngày"	Đã sử dụng hết 300 lượt gọi	Chờ đến 00:00 UTC.
"Phiên này vẫn đang chạy"	Một lượt phản hồi khác đang diễn ra	Chờ hoặc nhấn Stop.