Guia
Como adicionar um chatbot de suporte com AI e um agente SSH a uma nuvem CloudStack
O NexCMP é uma solução auto-hospedada de faturamento e portal do cliente para Apache CloudStack e Proxmox VE, e a versão 1.2.0 traz dois módulos de IA: o AI Chat, um assistente integrado ao portal do cliente, e o AI Agent, que executa tarefas na própria VM do cliente via SSH. Este guia ensina a configurar ambos com uma chave de API compatível com OpenAI, usando capturas de tela do portal do cliente e do console de administração.
Tempo necessário: cerca de 15 minutos em uma instalação existente do NexCMP.
A stack
Quatro componentes, três dos quais você provavelmente já executa.
NexCMP 1.2.0
O painel que seus clientes já usam, instalado no Ubuntu 22.04 ou 24.04. O AI Chat e o AI Agent fazem parte da licença — sem custo adicional.
Um endpoint compatível com a OpenAI
Qualquer API de chat-completions compatível com chamadas de ferramentas (function calling): um provedor hospedado ou um proxy que você execute na frente de múltiplos provedores.
Uma chave com limite de gastos
Crie uma chave exclusiva para o painel e defina um orçamento mensal para ela no provedor ou no seu proxy, garantindo que o consumo nunca fuja do controle.
Suas VMs do CloudStack
O AI Agent acessa a VM do cliente via SSH a partir do servidor do painel, usando as credenciais que o cliente salvou para essa VM.
Passo a passo
Atualize o painel para a versão 1.2.0
No console de administração, abra License e clique em Update, ou execute sudo nexcmp update no servidor. A atualização é assinada e verificada antes de ser instalada.
Crie uma chave de API com limite
No seu provedor de AI (ou no seu proxy), crie uma chave exclusiva para este painel e defina um orçamento mensal. Um modelo rápido e de baixo custo é suficiente para o chat de suporte.
Insira a chave em Admin › Settings › AI provider
Cole a URL do endpoint, a chave e o nome do modelo e, em seguida, clique em Test connection. A chave é armazenada criptografada no banco de dados do painel e nunca mais é exibida.
Ative o módulo de IA
Em Licença › Módulos, ative a IA. O AI Chat e o AI Agent aparecem no menu do portal do cliente após a página ser recarregada; desativar o módulo os oculta novamente.
Clientes perguntam ao AI Chat
O AI Chat responde a dúvidas sobre seus planos e preços e sobre os próprios serviços do cliente. Quando uma pergunta exigir atendimento humano, o cliente pode transferir a conversa para a sua equipe de suporte.
Clientes executam o AI Agent em uma VM
O cliente escolhe uma de suas próprias VMs e descreve a tarefa em linguagem natural. O agente executa os comandos via SSH e exibe cada comando com sua respectiva saída.
Acompanhe o consumo
O consumo é faturado pelo seu provedor de IA, não pelo NexCMP. Acompanhe os gastos no painel do provedor ou do proxy e ajuste o orçamento da chave à medida que seus clientes adotarem o recurso.
O que você precisa antes de começar
- NexCMP 1.2.0 ou posterior, com o módulo de IA em Licença › Módulos.
- Um provedor de IA com endpoint de chat/completions compatível com a OpenAI e um modelo com suporte a tool (function) calling: OpenAI, OpenRouter, um gateway LiteLLM ou seu próprio servidor vLLM são todos compatíveis.
- Para o AI Agent, openssh-client no servidor do painel (o instalador o adiciona) e uma rota de rede do servidor do painel para a porta SSH de cada VM, 22 por padrão.
- Para o AI Agent, uma VM Linux que pertença ao cliente, esteja em execução e não bloqueada, com login salvo (armazenado quando a VM foi criada ou sua senha redefinida) ou a chave de operações do painel. VMs Windows não são aceitas.
- Opcional para transferência do AI Chat para a equipe: um bot do Telegram e chat ID em Configurações › Alertas do administrador.
ssh -V
nc -vz 198.51.100.10 22Teste o endpoint a partir do servidor do painel primeiro
O NexCMP adiciona /chat/completions a URLs que terminam em /v1, e /v1/chat/completions a qualquer outra URL; uma URL que já termina em /chat/completions é usada como está. Antes de inserir o endpoint, envie uma requisição a ele a partir do servidor do NexCMP. Uma resposta JSON com choices[0].message.content indica que o endpoint e o modelo estão funcionando.
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"}]}'Como o AI Agent executa comandos e o que ele não executa sozinho
- Os comandos são executados a partir do servidor do painel com seu próprio cliente ssh, um comando não interativo por vez. O destino é sempre o endereço IP da VM registrado no banco de dados, nunca um valor obtido da requisição.
- A senha armazenada é transmitida por meio de um helper SSH_ASKPASS de uso único nas variáveis de ambiente do processo: ela não é gravada em disco nem informada na linha de comando.
- A saída de cada comando é limitada a 200 KB, cada interação termina em no máximo 10 etapas e um cliente pode ter no máximo 2 execuções do agente em andamento simultaneamente.
- No modo Confirm, cada comando aguarda o cliente clicar em Run. No modo Auto, apenas comandos em uma lista restrita de somente leitura, como df -h, ps ou journalctl, são executados automaticamente.
- Comandos que sobrescrevem ou excluem arquivos, alteram contas ou chaves SSH, enviam dados para um servidor externo, baixam e executam scripts ou desligam/reiniciam a máquina sempre exibem Needs confirmation, mesmo no modo Auto.
- A saída do comando é apresentada ao modelo como dados não confiáveis, e instruções contidas nela não são seguidas.
Solução de problemas
As mensagens que você tem mais chances de encontrar e o que verificar.
O teste de conexão falha com 401
- Causa provável
- A chave está incorreta para esse endpoint.
- O que fazer
- Verifique a chave e o endpoint, e digite a chave novamente caso tenha alterado a URL base.
O teste de conexão falha com 404 ou model not found
- Causa provável
- Caminho ou ID do modelo incorreto.
- O que fazer
- Verifique se a URL base termina em /v1 e use o ID exato do modelo do provedor.
O portal não exibe o menu de IA
- Causa provável
- O módulo está desativado ou o provedor não está habilitado para uso.
- O que fazer
- Ative o módulo de IA em Licença › Módulos e habilite o provedor.
O Agent não conseguiu fazer login
- Causa provável
- Nenhuma senha armazenada e nenhuma chave de operações para essa VM.
- O que fazer
- Redefina a senha da VM no portal para que seja salva novamente.
O servidor não respondeu a tempo
- Causa provável
- Um firewall, SSH não escutando ou uma VM ocupada.
- O que fazer
- Execute nc -vz <vm-ip> 22 a partir do servidor do painel e inicie o sshd na VM.
A IA está respondendo muito devagar
- Causa provável
- O provedor ou modelo está lento.
- O que fazer
- Use um modelo mais rápido ou reduza o Reasoning effort em Settings › AI provider.
Faça login para usar o AI Chat
- Causa provável
- O visitante não está conectado.
- O que fazer
- Esperado: o AI Chat é exclusivo para clientes autenticados.
Privacidade e custos
As perguntas dos clientes e os dados que a IA lê para esse cliente (somente leitura) são enviados ao seu provedor de IA. Informe isso em sua política de privacidade.
O NexCMP não contabiliza os custos de IA. Use os recursos de orçamento do seu provedor e reduza a configuração de turnos de IA por dia por cliente (40 por padrão, em Customers › Support › Ticket › AI settings) para limitar os gastos.
Próximos passos
O AI Chat e o AI Agent permanecem desativados até você salvar uma chave de provedor, portanto nada é cobrado de você nem enviado para lugar algum antes da sua decisão. Leia a visão geral ou conheça os outros módulos.
Perguntas sobre os módulos de IA
Quais modelos de IA funcionam?
O agente pode acessar servidores de outros clientes?
O NexCMP cobra pelo uso de IA?
Como testo a conexão com o provedor de IA?
O AI Agent precisa de um gateway SSH separado?
Visitantes que não estão conectados podem usar o AI Chat?
O AI Agent funciona em VMs Windows?
Posso desativá-lo?
Referências
Especificações mencionadas neste guia.
Adicione IA à sua nuvem
O AI Chat e o AI Agent estão inclusos em todas as licenças do NexCMP — grátis no primeiro ano ou $499 em pagamento único com o código-fonte.
Última atualização: