AI Agent

後台位置： System › Settings › AI provider (/settings/ai) ——模組開關與提供者；System › Admin › License & updates (/license) ——模組開關。portal 位置： AI Agent (/ai/agent) 以及頁面 /chat/agent，或聊天室內的 Agent 模式。

功能

AI Agent 會透過 SSH 連線至客戶自己的 Linux 虛擬機器，並執行以日常語言描述的任務：「檢查系統健康狀態」、「安裝 Docker」、「尋找近期錯誤」、「釋放磁碟空間」。它會顯示所提出的每一道指令及其輸出。唯讀指令可自動執行；任何會變更伺服器的操作都須等待客戶按下 Run。

需求

項目	需求
AI 模組與提供者	開啟 AI 模組並具備運作中的 AI provider。Agent 也需要支援工具呼叫的模型。
openssh-client 於面板伺服器上	Agent 使用面板自身的 ssh 程式 (/usr/bin/ssh) 執行指令。安裝程式會安裝 openssh-client；請透過 ssh -V 檢查。若無此程式，Agent 會回報「ssh client is not installed on the panel server」。
無獨立 SSH 通道	在預設安裝中，會使用內建 SSH 且不需要 ssh-proxy 網頁終端機。唯有啟用選用的 web SSH 功能 (feature_ssh_web) 並安裝 ssh-proxy 服務時，Agent 才會改透過 ssh-proxy 連線。
網路	面板伺服器必須能夠透過 SSH 連接埠（預設為 22）觸達虛擬機器的 IP。請檢查面板與客體網路之間的防火牆與安全性群組。
VM	客戶所有、執行中、未鎖定且為 Linux（拒絕 Windows 虛擬機器），並具有公開或可觸達的 IP 位址。
SSH 憑證	由 NexCMP 儲存的虛擬機器登入使用者與密碼（建立虛擬機器或重設密碼時儲存，已加密），或安裝了面板的操作金鑰。若兩者皆不存在，Agent 會表示無法登入。

準備基礎設施

1. 檢查面板伺服器上的 SSH 用戶端：

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

2. 檢查面板伺服器是否可對客體虛擬機器開啟 SSH：

   nc -vz 198.51.100.10 22

   將位址替換為測試虛擬機器的 IP。若此步驟失敗，請先修復路由或防火牆。

3. 確定客體允許 NexCMP 所儲存之使用者的密碼登入（某些雲端映像檔會停用此功能），或客體上已安裝面板的操作金鑰。

在 NexCMP 中連線

1. 完成 AI provider：已開啟模組、已儲存提供者、Test connection 顯示綠色。
2. 管理端無需設定其他項目。模組開關會讓客戶 portal 中出現 AI Agent 項目。
3. 以客戶身分：開啟 AI Agent，選擇執行中的伺服器並點擊 Choose server。該頁面會先以固定的無害指令探測 SSH（不使用 AI 呼叫），並顯示 SSH connected 或失敗原因。
4. 輸入任務或選擇快速啟動（Check system health、Install Docker、Install Nginx、Find recent errors、Security check、Free up disk space）。

指令執行方式

• 來源：面板伺服器，透過系統 ssh 客戶端，一次執行一個非互動式指令。目標永遠是資料庫中的虛擬機器 IP，絕非來自請求；僅能連線至擁有者自己的執行中且未鎖定的虛擬機器。

• **驗證：**儲存的密碼會透過處理程序環境中的單次 SSH_ASKPASS 輔助程式傳遞——不會寫入磁碟或放入命令列。主機金鑰不進行釘選（虛擬機器會以新金鑰重新安裝）。每個指令的輸出限制為 200 KB，且每個指令皆設有時間限制（60 秒）。

• **Agent 迴圈：**AI 會提出指令並讀取輸出結果；一個回合在最多 10 個步驟後結束。

• 模式：

  模式	行為
  Confirm	每個指令皆需等待 Run。
  Auto	僅有符合嚴格唯讀允許清單的指令會自動執行（例如 df -h、ps、journalctl）。其他任何內容，以及解析器無法確切分析的內容（變數、指令替代、重新導向至檔案），皆需等待 Run。

• **風險標籤：**覆寫或刪除檔案、寫入磁碟、變更帳戶或 SSH 金鑰、將資料傳送至外部伺服器、開啟原始網路連線、執行混淆程式碼、下載並執行腳本、關閉或重新啟動機器，或連線至其他伺服器的指令，即使在 Auto 模式下，也一律會顯示 Needs confirmation。

• **不受信任的輸出：**指令輸出會作為不受信任的資料顯示給模型；其中的指令將不會被執行。

驗證

1. 選擇一部執行中的測試虛擬機器。頁面會顯示 SSH connected。
2. 詢問「Check CPU, RAM and disk」。在 Auto 模式下，唯讀指令會執行，並由答案進行總結。
3. 詢問「Install Nginx」。安裝指令會與 Run 和 Skip 一同出現；在您按下 Run 之前，不會執行任何動作。
4. 頂端計數器會顯示今日已使用的 AI 呼叫次數（例如 3/300）。

限制與注意事項

• **每日限制：**每位客戶每天（UTC）300 次 AI 呼叫；於 00:00 UTC 重設。用盡時，Agent 會回答「Daily AI quota reached」。
• **並行限制：**每位客戶同時最多 2 個 Agent 執行；一個工作階段一次執行一個回合。
• **工作階段：**每個工作階段最多 100 則訊息，每則訊息 4,000 個字元。一個工作階段屬於一部虛擬機器；若虛擬機器遭到刪除或轉移，舊的工作階段將變為唯讀。
• **鎖定或停止的虛擬機器，或 Windows：**虛擬機器會顯示為 Locked、Stopped、Windows 或 No address，且無法被選取。
• **模擬登入：**管理員模擬登入客戶時，無法使用 Agent 的憑證功能（請參閱 Log in as a customer）。
• **責任：**Agent 可能會發生錯誤。門戶網站會提醒客戶在執行指令前進行審查。請在您的服務條款中告知客戶，他們須對自己批准的指令負責。
• 關閉 AI 模組會移除 Agent 項目，且路由會回傳 404 module_disabled。

故障排除

症狀	原因	修正方式
「控制台伺服器未安裝ssh用戶端 (apt install openssh-client)」	沒有 ssh 二進位檔	sudo apt-get install -y openssh-client.
「Agent無法登入」/ ssh: no saved credentials for this VM	沒有儲存的密碼且沒有操作金鑰	在門戶網站中重設虛擬機器密碼以使其重新儲存，或安裝操作金鑰。
「伺服器未及時回應」	防火牆、SSH 未監聽、虛擬機器忙碌中	從面板伺服器測試 nc -vz <ip> 22；在虛擬機器中啟動 sshd。
"無法連線至此伺服器的 SSH"	路由或安全性群組	允許面板伺服器透過連接埠 22 連線至虛擬機器。
"虛擬機器未執行" / "禁止"	虛擬機器已停止、鎖定、刪除或不屬於該客戶	啟動它、解鎖它或挑選另一台。
"無法使用：N (已停止、鎖定或 Windows)"	如上方所列之原因	該虛擬機器必須為 Linux 且正在執行。
"SSH 閘道暫時無法使用"	Web SSH 功能已啟用但 ssh-proxy 已停機	啟動 ssh-proxy，或關閉 Web SSH 功能以使用內建 SSH。
"AI 回應速度過慢 (超過 90 秒)"	供應商速度緩慢	使用較快的模型或較低的 Reasoning effort。
"已達每日 AI 配額"	已使用 300 次呼叫	等待至 00:00 UTC。
"此工作階段仍在執行中"	另一個回合正在進行中	請等待或按下 Stop。