AI Agent

관리자 설정 위치: System › Settings › AI provider (/settings/ai) — 모듈 스위치 및 공급자; System › Admin › License & updates (/license) — 모듈 스위치. 포털 위치: AI Agent (/ai/agent) 및 /chat/agent 페이지, 또는 채팅 내 Agent 모드.

작동 내용

AI Agent는 고객의 Linux VM에 SSH로 직접 연결하여 "시스템 상태 확인", "Docker 설치", "최근 오류 찾기", "디스크 공간 확보"와 같은 평문으로 설명된 작업을 수행합니다. 제안하는 모든 명령어와 그 출력을 표시합니다. 읽기 전용 명령어는 자동으로 실행될 수 있으며, 서버를 변경하는 작업은 고객이 Run을 누를 때까지 대기합니다.

요구 사항

항목	요구 사항
AI 모듈 및 공급자	AI 모듈이 켜져 있고 작동 중인 AI provider가 필요합니다. 또한 에이전트는 도구 호출(tool calling)을 지원하는 모델이 필요합니다.
패널 서버의 openssh-client	에이전트는 패널 자체의 ssh 프로그램(/usr/bin/ssh)을 사용하여 명령어를 실행합니다. 설치 프로그램이 openssh-client을(를) 설치하며, ssh -V(으)로 확인할 수 있습니다. 이 프로그램이 없으면 에이전트는 "ssh client is not installed on the panel server" 오류를 보고합니다.
별도 SSH 게이트웨이 없음	기본 설치에서는 내장 SSH가 사용되며 ssh-proxy 웹 터미널은 필요하지 않습니다. 선택 사항인 web SSH 기능(feature_ssh_web)이 활성화되고 ssh-proxy 서비스가 설치된 경우에만 에이전트가 ssh-proxy을(를) 거쳐 연결됩니다.
네트워크	패널 서버는 VM의 IP에 있는 SSH 포트(기본값 22)에 도달할 수 있어야 합니다. 패널과 게스트 네트워크 간의 방화벽과 보안 그룹을 확인하세요.
VM	고객 소유, 실행 중, 잠기지 않음, 공개 또는 도달 가능한 IP 주소를 가진 Linux VM (Windows VM은 지원되지 않음).
SSH 자격 증명	NexCMP에 저장된 VM 로그인 계정 및 비밀번호(VM 생성 시 또는 비밀번호 재설정 시 암호화되어 저장됨) 또는 패널의 운영 키가 설치된 경우 해당 키. 둘 다 없는 경우 에이전트는 로그인할 수 없다고 표시합니다.

인프라 준비

1. 패널 서버에서 SSH 클라이언트 확인:

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

2. 패널 서버가 게스트 VM에 SSH로 연결할 수 있는지 확인:

   nc -vz 198.51.100.10 22

   주소를 테스트 VM의 IP로 바꾸세요. 이 작업이 실패하면 라우팅 또는 방화벽을 먼저 수정하세요.

3. 게스트가 NexCMP에 저장된 사용자의 비밀번호 로그인을 허용하는지(일부 클라우드 이미지는 비활성화함), 또는 패널의 운영 키가 게스트에 설치되어 있는지 확인하세요.

NexCMP에서 연결

1. AI provider 완료: 모듈 켜기, 공급자 저장, Test connection 녹색 표시.
2. 관리자 측에서 추가로 설정할 것은 없습니다. 모듈 스위치를 켜면 고객 포털에 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 클라이언트를 사용하는 패널 서버이며, 한 번에 하나의 비대화식 명령이 실행됩니다. 대상은 요청이 아닌 데이터베이스의 VM IP이며, 소유자 본인의 실행 중이고 잠기지 않은 VM만 접근할 수 있습니다.

• 인증: 저장된 비밀번호는 프로세스 환경의 일회용 SSH_ASKPASS 헬퍼를 통해 전달되며, 디스크에 기록되거나 명령줄에 포함되지 않습니다. 호스트 키는 고정되지 않습니다(VM은 새 키로 재설치됨). 명령당 출력은 200 KB로 제한되며 각 명령에는 시간 제한(60초)이 있습니다.

• 에이전트 루프: AI가 명령을 제안하고 출력을 읽으며, 한 턴은 최대 10단계 후에 종료됩니다.

• 모드:

  모드	동작
  Confirm	모든 명령은 Run을 기다립니다.
  Auto	엄격한 읽기 전용 허용 목록을 통과한 명령만 자동으로 실행됩니다(예: df -h, ps, journalctl). 그 외의 것과 파서가 확실하게 분석할 수 없는 것(변수, 명령 치환, 파일 리디렉션)은 Run을 기다립니다.

• 위험 레이블: 파일을 덮어쓰거나 삭제하고, 디스크에 쓰고, 계정이나 SSH 키를 변경하고, 외부 서버로 데이터를 전송하고, 원시 네트워크 연결을 열고, 난독화된 코드를 실행하고, 스크립트를 다운로드하여 실행하고, 기기를 종료 또는 재시작하거나, 다른 서버에 도달하는 명령은 Auto 모드에서도 항상 Needs confirmation을 표시합니다.

• 신뢰할 수 없는 출력: 명령 출력은 신뢰할 수 없는 데이터로 모델에 표시되며, 그 안의 지시는 따르지 않습니다.

확인

1. 실행 중인 테스트 VM을 선택합니다. 페이지에 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에 초기화됩니다. 한도가 소모되면 에이전트는 "Daily AI quota reached"로 응답합니다.
• 동시성: 고객당 동시에 최대 2개의 에이전트가 실행될 수 있으며, 세션은 한 번에 한 턴씩 실행됩니다.
• 세션: 세션당 최대 100개의 메시지, 메시지당 4,000자가 허용됩니다. 세션은 하나의 VM에 속하며, VM이 삭제되거나 이전되면 기존 세션은 읽기 전용이 됩니다.
• 잠기거나 중지된 VM 또는 Windows: VM이 Locked, Stopped, Windows 또는 No address로 표시되며 선택할 수 없습니다.
• 가장(Impersonation): 고객을 가장하는 관리자는 에이전트의 자격 증명 기능을 사용할 수 없습니다(Log in as a customer 참고).
• 책임: 에이전트는 실수를 할 수 있습니다. 포털은 고객에게 명령을 실행하기 전에 검토하도록 안내합니다. 승인된 명령에 대한 책임은 고객에게 있음을 약관에 명시하세요.
• AI 모듈을 끄면 에이전트 항목이 제거되고 라우트는 404를 반환합니다 module_disabled.

Troubleshooting

증상	원인	해결 방법
"패널 서버에 ssh 클라이언트가 설치되어 있지 않습니다 (apt install openssh-client)"	ssh 바이너리 없음	sudo apt-get install -y openssh-client.
"에이전트가 로그인할 수 없습니다" / ssh: no saved credentials for this VM	저장된 비밀번호 및 운영 키 없음	포털에서 VM 비밀번호를 재설정하여 다시 저장되도록 하거나 운영 키를 설치합니다.
"서버가 제때 응답하지 않았습니다"	방화벽, SSH가 수신 대기 중이 아님, VM이 바쁨	패널 서버에서 nc -vz <ip> 22을(를) 테스트하고, VM에서 sshd을(를) 시작합니다.
"이 서버의 SSH에 연결할 수 없습니다"	라우팅 또는 보안 그룹	패널 서버가 포트 22를 통해 VM에 도달할 수 있도록 허용합니다.
"VM이 실행 중이 아님" / "권한 없음"	VM이 중지되었거나, 잠겼거나, 삭제되었거나 고객의 소유가 아님	시작하거나, 잠금을 해제하거나, 다른 VM을 선택합니다.
"사용 불가: N (중지됨, 잠김 또는 Windows)"	위에 나열된 이유	VM은 Linux여야 하며 실행 중이어야 합니다.
"SSH 게이트웨이를 일시적으로 사용할 수 없습니다"	웹 SSH 기능이 활성화되었으나 ssh-proxy이(가) 다운됨	ssh-proxy을(를) 시작하거나, 기본 제공 SSH를 사용하려면 웹 SSH 기능을 끕니다.
"AI 응답이 너무 느립니다 (90초 초과)"	제공자 응답 지연	더 빠른 모델 또는 더 낮은 Reasoning effort을(를) 사용하세요.
"일일 AI 할당량 도달"	300회 호출 사용됨	00:00 UTC까지 기다리세요.
"이 세션이 여전히 실행 중입니다"	다른 턴이 진행 중	기다리거나 Stop을(를) 누르세요.