CLOVA functionCalling 을 통한 자연어 터미널 기능 구현하기

자연어 터미널 (CLOVA NLP)

1. 개요

배경

터미널 명령어는 개발자에게는 익숙하지만, 일반 사용자에게는 진입 장벽이 높습니다. 이에 "user 폴더 만들어줘" 같은 자연어를 mkdir user로 변환하는 자연어 인터페이스를 구현하고자 했습니다.

목적

사용자가 자연어로 명령을 입력하면 이를 실제 터미널 명령어로 변환하여 실행하는 기능을 구현합니다.
Naver Cloud의 HyperCLOVA X Function Calling API를 활용하여 사용자의 자연어 입력을 분석하고, 적절한 시스템 명령어를 생성합니다.

예시

사용자 입력: "현재 경로에 user 폴더를 만들어줘"
→ 시스템 해석: mkdir user
→ 실행 결과: user 디렉토리 생성 완료

주요 기능

1. 자연어 명령 파싱: "user 폴더 만들어줘" → mkdir user
2. 복합 명령어 처리: "home으로 이동하고 TEST 폴더 만들어줘" → cd /home && mkdir TEST
3. 실행 계획 미리보기: 실행 전 사용자 확인
4. Context 기반 추론: 현재 경로, 파일 목록 등을 고려한 명령어 생성
5. 안전성 검증: 위험한 명령어 차단 및 검증

실행 화면 ( Demo )

복합 명령 응답

단일 명령 응답

핵심 기술

• CLOVA AI (HyperCLOVA X): 자연어 이해 및 명령어 변환
• https://clova.ai/tech-blog/skill-function-calling
• 기존 Syscall 시스템: 명령어 실행 인프라 활용

CLOVA STUDIO function calling

대규모 언어 모델(LLM)은 자연어 처리에서 강력한 성능을 발휘하지만, 몇가지 한계를 가지고 있습니다.

첫째, 실시간으로 업데이트되는 최신 정보를 반영하기 어렵고 둘째, 직접적인 액션을 수행할 수 없다는 점입니다. 예를 들어, 기존의 AI 챗봇은 “오늘 날씨는 어때?”라는 질문에 과거 데이터를 기반으로 답변하거나, “이번 주 토요일 1시에 청첩장 모임 일정 추가해줘“라는 요청에 “제가 할 수 없는 요청이에요.”라고 응답하는 경우가 많습니다. 이는 대부분의 LLM이 사전에 학습된 데이터만을 기반으로 답변을 생성하며, 외부 데이터와 연결되거나 실제 환경에서 동작하는 기능이 부족하기 때문입니다.

HyperCLOVA X는 이러한 한계를 극복하기 위해 스킬(Skill)과 Function Calling이라는 두 가지 기능을 도입했습니다. 특히 Function Calling은 스킬보다 더 확장성이 높고 다양한 액션을 수행할 수 있어 개발자들에게 더 많은 가능성을 제공합니다. 이를 통해 LLM은 외부 데이터를 사용하고, 실제 액션을 수행할 수 있도록 확장되어 더욱 풍부하고 실용적인 AI 경험을 제공할 수 있습니다.

LLM과 외부 시스템의 연결 고리, 스킬과 Function Calling

HyperCLOVA X는 LLM이 외부 시스템과 상호작용할 수 있는 스킬과 Function Calling 기능을 제공합니다. 스킬은 LLM이 API를 호출하여 외부 데이터를 가져올 수 있도록 하는 기능입니다. 현재 CLOVA X에서는 쇼핑, 여행, 마켓컬리, 쏘카, 트리플 등의 외부 서비스 데이터를 연동한 스킬을 사용자에게 제공하고 있습니다.

Function Calling은 LLM이 사용자 질문에 답하기 위해 특정 기능을 호출할 수 있는 기능입니다. 단순한 API 호출뿐만 아니라 스크립트 실행 및 라이브러리 함수 호출까지 가능한 확장형 기능으로 Function Calling을 활용하면 개발자가 직접 함수를 호출하고, 특정 액션을 수행할 수 있습니다. 예를 들어 이메일을 전송하거나, 파일을 업로드하고 데이터베이스에서 특정 정보를 조회하는 등 다양한 작업을 자동화할 수 있습니다.

Function Calling을 활용한 AI 기반 자동화 시스템 구축

Function Calling은 단순한 정보 조회를 넘어, 외부 시스템과 연동하여 실제 액션을 수행할 수 있는 기능을 제공합니다. 이를 활용하면 AI가 단순한 대화형 비서가 아니라, 업무를 자동화하고 실제 작업을 수행하는 도구로 활용될 수 있습니다.

Function Calling의 동작 방식

AI가 제안하고, 개발자가 실행 여부를 제어합니다. 모델이 직접 호출하는 것이 아닌 개발자가 직접 함수 실행을 직접 처리하고, 응답 값을 모델에 전달합니다.

• 사용자 쿼리 입력 → AI가 사전에 정의된 도구 정보를 바탕으로 적절한 Function을 선택
• 매개변수 포함 실행 요청 생성 → AI가 필요한 데이터를 추출하여 실행 요청 생성
• 사용자가 Function 실행 → AI는 실행을 제안하고, 실제 실행은 사용자가 수행
• 실행 결과를 반영한 답변 생성 → 실행된 결과 값을 모델이 반영하여 최종 답변을 생성

최종 기술 선정 : Function Calling

이외에도 Skill 이라고 Chain of Thought(CoT) 과정에서 자동으로 API 호출을 결정하고 실행하는 모델이 있지만, Function Calling 은 AI가 제안하고, 개발자가 실행 여부를 제어합니다.

본 서비스에서 Function Calling 구현 원리: 데이터 수집 및 학습 메커니즘 자연어 터미널을 개발함에 있어서 CLOVA 가 외부 API 를 호출해서 데이터를 수집하고 이를 의사결정에 참고한다기 보다는, CLOVA 가 어떤 함수를 호출해야할지 맥락을 파악하고
이에 대한 실행은 시스템이 수행하는게 더 적절하다고 판단했습니다.

---

2. 시스템 아키텍처

2.1 전체 구조도 (Mermaid)

2.2 데이터 흐름도 (Sequence Diagram)

2.3 컴포넌트 아키텍처

2.4 NLP 처리 파이프라인

2.5 터미널 모드 상태 다이어그램

 

---

아키텍처

전체 흐름도

[사용자]
   ↓ "user 폴더 만들어줘"
[프론트엔드 - useTerminal Hook]
   ↓ POST /api/nlp/parse
[백엔드 - NlpController]
   ↓
[NlpService]
   ├─ collectContext() → 현재 경로, 파일 목록 수집
   ↓
[ClovaClient]
   ├─ buildSystemPrompt() → 프롬프트 생성
   ├─ filterFunctionSchemas() → 지원 명령어만 필터링
   ↓ POST to HyperCLOVA X API
[CLOVA API]
   ↓ Function Calling 응답
[ClovaClient]
   ├─ parseToolCalls() → Command[] 변환
   ↓
[CommandValidator]
   ├─ validateCommand() → 보안 검증
   ├─ sanitizeArgs() → 인자 새니타이징
   ↓
[NlpService]
   └─ 검증된 명령어 목록 반환
      ↓
[프론트엔드]
   ├─ ExecutionPlan 표시 (사용자 확인)
   ├─ 사용자가 Enter 입력
   ↓ POST /api/nlp/confirm
[NlpController]
   ↓
[NlpService - executeCommands()]
   └─ for each command:
      ↓
   [SyscallService.execute()]
      └─ 실제 명령어 실행
         ↓
      결과 수집 및 반환
         ↓
[프론트엔드]
   └─ 실행 결과 터미널에 표시

디렉터리 구조

apps/
├── server/
│   └── src/
│       └── nlp/
│           ├── nlp.controller.ts        # API 엔드포인트
│           ├── nlp.service.ts           # 비즈니스 로직
│           ├── clova.client.ts          # CLOVA API 클라이언트
│           ├── command.validator.ts     # 명령어 검증
│           ├── function-schemas.ts      # Function Calling 스키마
│           ├── nlp.exception.ts         # 커스텀 예외
│           ├── nlp.module.ts            # NestJS 모듈
│           └── dto/
│               ├── parse-nlp.dto.ts
│               ├── nlp-execute.dto.ts
│               └── nlp-response.dto.ts
│
└── web/
    └── src/
        ├── hooks/windows/terminal/
        │   └── useTerminal.ts           # 터미널 상태 관리
        ├── components/domain/terminal/
        │   ├── terminal.tsx             # 터미널 UI
        │   ├── executionPlan.tsx        # 실행 계획 UI
        │   └── nlpSuggestionPortal.tsx  # NLP 제안 포털
        └── apis/
            └── nlp.ts                   # API 클라이언트

상세 설계

1. API 엔드포인트

POST /api/nlp/parse

자연어 입력을 분석하여 명령어 후보를 반환합니다.

Request:

{
  "input": "user 폴더 만들어줘"
}

Response:

{
  "success": true,
  "data": {
    "functions": [
      {
        "command": "mkdir",
        "args": "user",
        "explanation": "user 디렉토리를 생성합니다",
        "isValid": true,
        "order": 1,
        "validationError": null
      }
    ]
  },
  "error": null
}

POST /api/nlp/confirm

사용자가 확인한 명령어를 실제로 실행합니다.

Request:

{
  "functions": [
    {
      "command": "mkdir",
      "args": "user",
      "explanation": "user 디렉토리를 생성합니다",
      "isValid": true,
      "order": 1
    }
  ]
}

Response (성공):

{
  "success": true,
  "data": {
    "allSuccess": true,
    "results": [
      {
        "command": "mkdir",
        "args": "user",
        "output": "user 폴더가 생성되었습니다.",
        "success": true
      }
    ],
    "successCount": 1,
    "totalCount": 1
  },
  "error": null
}

Response (실패):

{
  "success": true,
  "data": {
    "allSuccess": false,
    "results": [
      {
        "command": "cd",
        "args": "/invalid",
        "output": "",
        "success": false,
        "errorMessage": "해당 디렉토리를 찾을 수 없습니다: invalid"
      }
    ],
    "successCount": 0,
    "totalCount": 1,
    "errorMessage": "해당 디렉토리를 찾을 수 없습니다: invalid"
  },
  "error": null
}

2. Function Calling 스키마

총 13개의 터미널 명령어를 Function Schema로 정의:

명령어	설명	주요 파라미터
mkdir	디렉토리 생성	title, icon?
cd	디렉토리 이동	path
ls	파일 목록 표시	(없음)
pwd	현재 경로 출력	(없음)
cat	파일 내용 읽기	title, extension?
rm	파일/폴더 삭제	title, extension?
write	파일 생성 및 작성	title, extension?, body, icon?
clear	화면 지우기	(없음)
date	날짜/시간 표시	(없음)
help	도움말 표시	(없음)
uname	시스템 정보 표시	(없음)
exec	JavaScript 실행	filePath (.ejs만)
log	로그 조회	level? (error/warn/info/debug)

각 스키마는 apps/server/src/nlp/function-schemas.ts에 정의되어 있습니다.

3. Context 수집

CLOVA API에 전달되는 Context 정보:

{
  currentPath: string;        // 현재 작업 디렉토리 (예: "/home/user")
  recentCommands: string[];   // 최근 실행 명령어 (향후 구현)
  availableFiles: string[];   // 현재 디렉토리의 파일 목록
  supportedCommands: string[]; // 지원하는 명령어 목록
}

이를 통해 CLOVA가 다음과 같은 추론을 할 수 있습니다:

• "리포트 파일 내용 보여줘" → availableFiles에서 report.txt 매칭 → cat report.txt
• "상위 폴더로 이동" → currentPath 고려 → cd ..

4. 명령어 검증 (CommandValidator)

보안을 위한 다층 검증:

1. 화이트리스트 검증: 지원하지 않는 명령어 차단
2. 위험 패턴 감지:
   • Shell injection 시도 (;, &, |, ```, $, (, ), <, >)
   • Directory traversal (../)
   • 시스템 파일 접근 (/etc/, /root/)
3. 명령어별 추가 검증:
   • rm: 중요 파일/디렉토리 보호 (/, /home, /root)
   • exec: .ejs 파일만 허용
4. 인자 새니타이징:
   • 특수문자 제거
   • 최대 길이 제한 (500자)

5. 프론트엔드 상태 관리

useTerminal Hook에서 관리하는 상태:

{
  // 기본 터미널 상태
  currentInput: string;
  commandList: Command[];
  currentPath: string;

  // NLP 모드 상태
  isNlpMode: boolean;           // CLOVA 모드 활성화 여부
  nlpPlan: NlpFunction[];       // 실행 계획
  isPlanConfirmMode: boolean;   // 확인 대기 중
  showPlanDetails: boolean;     // 상세보기 토글
  isNlpLoading: boolean;        // API 호출 중
  nlpError: string | null;      // 에러 메시지

  // 로그 모드 상태
  isLogMode: boolean;
  logEntries: string[];
}

6. 사용자 플로우

6-1. CLOVA 모드 진입

사용자: clova [Enter]
터미널: "CLOVA AI 모드 활성화. 'exit'으로 종료하세요."
프롬프트: CLOVA_SHELL > (파란색)

6-2. 자연어 명령 입력

사용자: user 폴더 만들어줘 [Enter]
터미널: "CLOVA에게 요청 중..."
↓ (API 호출)
터미널: [실행 계획 표시]
  ┌─────────────────────────────────────┐
  │ CLOVA가 다음 명령어를 제안합니다:   │
  │                                     │
  │ 1. mkdir user                       │
  │    → user 디렉토리를 생성합니다     │
  │                                     │
  │ [Enter] 실행  [Esc] 취소  [Space] 상세보기 │
  └─────────────────────────────────────┘

6-3. 실행 확인

사용자: [Enter]
터미널: "[CLOVA] 1개 명령어 실행을 서버에 요청합니다..."
↓ (실행)
터미널:
  mkdir user
  user 폴더가 생성되었습니다.

  [CLOVA] 모든 명령어 실행 완료 (1개)

6-4. 복합 명령어 예시

사용자: home으로 이동하고 TEST 폴더 만들어줘 [Enter]
터미널: [실행 계획 표시]
  ┌─────────────────────────────────────┐
  │ CLOVA가 다음 명령어를 제안합니다:   │
  │                                     │
  │ 1. cd /home                         │
  │    → /home 경로로 이동합니다        │
  │ 2. mkdir TEST                       │
  │    → TEST 디렉토리를 생성합니다     │
  │                                     │
  │ [Enter] 실행  [Esc] 취소            │
  └─────────────────────────────────────┘

사용자: [Enter]
터미널:
  cd /home
  /home

  mkdir TEST
  TEST 폴더가 생성되었습니다.

  [CLOVA] 모든 명령어 실행 완료 (2개)

6-5. CLOVA 모드 종료

사용자: exit [Enter]
터미널: "[CLOVA] 자연어 모드가 종료되었습니다."
프롬프트: /home > (초록색)

에러 처리

1. CLOVA API 에러

상황	HTTP 상태	예외 클래스	사용자 메시지
인증 실패	401	NlpCommunicationException	"AI 서버 인증에 실패했습니다. 관리자에게 문의하세요."
Rate Limit	429	NlpRateLimitException	"요청 한도를 초과했습니다. 잠시 후 다시 시도해주세요."
타임아웃	-	NlpTimeoutException	"AI 서버 응답 시간이 초과되었습니다."
연결 실패	-	NlpCommunicationException	"AI 서버에 연결할 수 없습니다."
파싱 실패	-	NlpParseException	"AI 응답 형식이 올바르지 않습니다."
Content Filter	-	NlpParseException	"부적절한 내용이 감지되었습니다."

2. 명령어 실행 에러

실행 중 에러 발생 시:

• 해당 명령어에서 중단
• 이전 성공한 명령어는 롤백하지 않음
• 부분 성공 정보 제공

응답 예시:

{
  "allSuccess": false,
  "results": [
    {
      "command": "cd",
      "args": "/home",
      "output": "/home",
      "success": true
    },
    {
      "command": "mkdir",
      "args": "test",
      "output": "",
      "success": false,
      "errorMessage": "이미 존재하는 디렉토리입니다: test"
    }
  ],
  "successCount": 1,
  "totalCount": 2,
  "errorMessage": "이미 존재하는 디렉토리입니다: test"
}

프론트엔드 출력:

cd /home
/home

mkdir test
[ERROR] 이미 존재하는 디렉토리입니다: test

[CLOVA ERROR] 이미 존재하는 디렉토리입니다: test

3. HttpExceptionFilter

모든 NLP 예외는 HttpExceptionFilter에서 처리되어 일관된 형식으로 반환:

{
  "success": false,
  "data": null,
  "error": {
    "statusCode": 503,
    "message": "AI 서버에 연결할 수 없습니다.",
    "timestamp": "2024-01-15T12:00:00.000Z",
    "path": "/api/nlp/parse"
  }
}

보안 고려사항

1. Function Schema 화이트리스트: 미리 정의된 13개 명령어만 허용
2. 인자 검증: Shell injection, Directory traversal 방지
3. 위험 명령어 추가 검증: rm, exec 등
4. 인자 새니타이징: 특수문자 제거, 길이 제한
5. CLOVA API 인증: Bearer Token 사용
6. Timeout 설정: 10초로 제한하여 무한 대기 방지

환경 변수

# .env 또는 .env.local
CLOVA_API_KEY=your_api_key_here
CLOVA_APP_ID=your_app_id_here
CLOVA_ENDPOINT=https://clovastudio.stream.ntruss.com/v3/chat-completions/HCX-DASH-002

성능 최적화

1. Token 사용량 최소화:
   • availableFiles 로그는 최대 10개만 출력
   • temperature: 0.3으로 일관된 응답 유도
   • maxTokens: 1024 제한
2. 응답 시간 모니터링:
3. const startTime = Date.now(); // ... API 호출 const duration = Date.now() - startTime; this.logger.log(`CLOVA API responded in ${duration}ms`);
4. Context 최적화:
   • recentCommands는 최근 3개만 전송
   • 파일 목록이 너무 많으면 요약

참고 자료

• HyperCLOVA X Function Calling API 문서
• NestJS 공식 문서
• React Hooks 가이드

---