指南
如何为CloudStack云添加AI支持聊天机器人和SSH Agent
NexCMP是一款面向Apache CloudStack和Proxmox VE的自托管账单与客户门户软件，其1.2.0版本推出了两个AI模块：客户门户内置助手AI Chat，以及通过SSH在客户自有虚拟机上执行任务的AI Agent。本指南配有客户门户和管理控制台的屏幕截图，指导如何使用兼容OpenAI的API Key配置这两个模块。
所需时间：在现有的NexCMP安装上约需15分钟。
技术栈
包含四个组成部分，其中三个您可能已经在运行。
NexCMP 1.2.0
您的客户已在使用的控制面板，安装于Ubuntu 22.04或24.04上。AI Chat和AI Agent均包含在许可证内，无额外费用。
兼容OpenAI的端点
任何支持工具（函数）调用的chat-completions API：可以是托管提供商，也可以是部署在多个提供商前面的代理。
带有支出上限的密钥
为控制面板分配独立密钥，并在提供商处或您的代理中为其设定月度预算，以防用量失控。
您的CloudStack VM
AI Agent使用客户为该VM保存的登录凭据，从控制面板服务器通过SSH连接到客户的VM。
分步操作
将控制面板更新至1.2.0
在管理控制台中打开License并点击Update，或在服务器上运行sudo nexcmp update。更新包在安装前均经过签名校验。
创建设定上限的API密钥
在您的AI提供商处（或代理中）为该控制面板专门创建一个密钥并设定月度预算。对于支持聊天，快速且低成本的模型即已足够。
在Admin › Settings › AI provider中输入
粘贴端点URL、密钥和模型名称，然后点击Test connection。密钥加密存储在控制面板数据库中，且之后不再显示。
开启AI模块
在License › Modules中开启AI。页面刷新后，AI Chat和AI Agent将显示在客户门户菜单中；关闭该模块即可将其再次隐藏。
客户向AI Chat提问
AI Chat可回答有关您的套餐方案、定价以及客户自身服务的问题。当问题需要人工介入时，客户可以将对话转接给您的支持团队。
客户在虚拟机上运行AI Agent
客户选择自己名下的一台虚拟机，并用自然语言描述任务。Agent会通过SSH执行命令，并完整显示每条命令及其输出结果。
监控使用量
使用量由您的AI提供商计费，而非NexCMP。请在提供商或代理网关的控制面板中查看支出，并随着客户对该功能的使用逐步调整密钥的预算额度。
准备工作
- NexCMP 1.2.0或更高版本，并在License › Modules中包含AI模块。
- 拥有兼容OpenAI chat/completions端点且模型支持工具（函数）调用的AI提供商：OpenAI、OpenRouter、LiteLLM网关或自建vLLM服务器均可。
- 如需使用AI Agent，面板服务器上需安装openssh-client（安装程序会自动添加），且面板服务器到各虚拟机的SSH端口（默认为22）网络路由通畅。
- 如需使用AI Agent，目标需为属于该客户、正在运行且未被锁定的Linux虚拟机，并具备保存的登录凭据（在创建虚拟机或重置密码时保存）或面板的操作密钥。不支持Windows虚拟机。
- 可选（用于AI Chat人工转接）：在Settings › Admin alerts下配置Telegram机器人和chat ID。
ssh -V
nc -vz 198.51.100.10 22先从面板服务器测试端点
NexCMP会为以/v1结尾的URL自动追加/chat/completions，为其它的URL追加/v1/chat/completions；若URL已以/chat/completions结尾，则保持原样直接使用。在填入端点之前，请先从NexCMP服务器向其发送一次请求。若返回包含choices[0].message.content的JSON响应，即表明端点和模型工作正常。
curl -s https://ai.example.com/v1/chat/completions \
-H "Authorization: Bearer XXXX" -H "Content-Type: application/json" \
-d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Reply with one word: OK"}]}'AI Agent如何执行命令，以及哪些操作不会自动执行
- 命令由面板服务器使用自带的ssh客户端执行，每次执行一条非交互式命令。目标始终为数据库中记录的虚拟机IP地址，绝不会使用来自请求中的地址。
- 存储的密码通过进程环境变量中单次生效的SSH_ASKPASS辅助工具传递：绝不会写入磁盘或暴露在命令行中。
- 单条命令的输出大小限制为200 KB，单轮对话最多执行10步，且单个客户同时最多只能运行2个Agent任务。
- 在Confirm模式下，每条命令都必须等待客户点击Run。在Auto模式下，仅有严格只读白名单中的命令（例如df -h、ps或journalctl）才会自动执行。
- 凡是涉及覆盖或删除文件、修改账户或SSH keys、向外部服务器发送数据、下载并运行脚本，或者关闭/重启机器的命令，即使在Auto模式下也始终会提示Needs confirmation。
- 命令输出内容均作为不可信数据提供给模型，其中包含的任何指令均不会被采纳执行。
故障排查
最常见的问题提示及排查方法。
Test connection失败，返回401
- 可能原因
- 密钥与该端点不匹配。
- 解决方法
- 检查密钥和端点；若修改过基础URL，请重新输入密钥。
Test connection失败，返回404或model not found
- 可能原因
- 路径或模型ID错误。
- 解决方法
- 确保基础URL以/v1结尾，并填入提供商准确的模型ID。
门户中未显示AI菜单
- 可能原因
- 模块未启用，或该提供商未被设置为启用状态。
- 解决方法
- 在License › Modules中开启AI模块并启用提供商。
Agent无法登录
- 可能原因
- 该虚拟机未保存密码且无操作密钥。
- 解决方法
- 在门户中重置虚拟机密码以重新保存。
服务器未及时响应
- 可能原因
- 防火墙拦截、SSH未监听或虚拟机繁忙。
- 解决方法
- 在面板服务器上运行nc -vz <vm-ip> 22并在虚拟机中启动sshd。
AI响应过慢
- 可能原因
- 服务商或模型响应缓慢。
- 解决方法
- 在Settings › AI provider中选用更快的模型或降低Reasoning effort。
登录以使用AI Chat
- 可能原因
- 访客尚未登录。
- 解决方法
- 符合预期：AI Chat仅供已登录客户使用。
隐私与成本
客户的提问以及AI为该客户读取的数据（只读）都会发送至您的AI服务商。请在您的隐私政策中对此予以说明。
NexCMP不对AI成本进行计量。请使用服务商的预算功能，并调低每位客户每日AI轮次设置（默认为40，位于Customers › Support › Ticket › AI settings）以控制支出。
后续操作
AI Chat和AI Agent在您保存服务商Key之前均保持关闭状态，因此在您做出决定前不会产生任何费用，也不会向任何地方发送数据。您可以阅读概览，或了解其他模块。
关于AI模块的常见问题
支持哪些AI模型？
Agent能否访问其他客户的服务器？
NexCMP是否对AI收取费用？
如何测试AI服务商连接？
AI Agent是否需要独立的SSH网关？
未登录的访客可以使用AI Chat吗？
AI Agent支持Windows虚拟机吗？
可以关闭该功能吗？
最后更新：