나만의 봇 만들기 자습서

1사전 준비 — Node.js, Git 설치 확인

CMD(명령 프롬프트) 또는 PowerShell을 열고 다음 명령어를 입력해 설치 여부를 확인합니다.

1-1. Node.js 확인

node --version
npm --version

버전이 표시되면 설치 완료입니다. (예: v20.10.0)

설치 안 되어 있으면 → https://nodejs.org/ko 에서 LTS 버전 다운로드 후 설치.

1-2. Git 확인

git --version

버전이 나오면 OK. (예: git version 2.49.0)

설치 안 되어 있으면 → https://git-scm.com/download/win

1-3. 코드 에디터 (VS Code 권장)

VS Code 다운로드 → 설치

💡 팁 Git 설치 시 "Git Bash"도 함께 설치됩니다. CMD가 어려우면 Git Bash를 써도 됩니다.

2GitHub 계정 + 레포 만들기

2-1. GitHub 가입 (이미 있으면 건너뛰기)

https://github.com/signup 접속
이메일 → 비밀번호 → 사용자명 입력
이메일 인증 완료

2-2. 새 레포지토리 만들기

로그인 후 우측 상단 + → New repository
레포 이름: 예) my-sikgu-bot (자기 봇 이름)
Public 선택 (Vercel 무료 배포 가능)
"Add a README file" 체크 안 함 (나중에 푸시할 때 충돌 방지)
Create repository 클릭

2-3. Git에 GitHub 계정 등록 (최초 1회)

CMD에서:

git config --global user.name "본인_GitHub_사용자명"
git config --global user.email "본인_이메일@example.com"

3템플릿 클론 + 로컬 실행

3-1. 작업 폴더로 이동

cd C:\projects
mkdir my-bot
cd my-bot

3-2. 참고 레포 클론

git clone https://github.com/sdkparkforbi/cha-interview-bot-liveavatar-my.git .

⚠️ 주의 마지막에 . (점) 있음. 현재 폴더에 클론하라는 뜻.

3-3. 기존 .git 폴더 삭제 (내 레포로 새로 시작)

rmdir /s /q .git
git init -b main

3-4. 의존성 설치

npm install

약 1~3분 걸립니다.

3-5. 로컬 실행

npm run dev

브라우저에서 http://localhost:5173 접속 → 봇이 동작하면 성공!

💡 종료 CMD에서 Ctrl + C → Y 입력

4환경 변수 설정 (.env)

봇이 작동하려면 API 키들이 필요합니다. 프로젝트 루트에 .env 파일을 만드세요.

4-1. .env 파일 생성

VS Code에서 프로젝트 폴더 열기 → 새 파일 .env 생성 → 다음 입력:

# OpenAI API 키 (https://platform.openai.com/api-keys)
OPENAI_API_KEY=sk-proj-...

# (옵션) STT/TTS 서비스 키
# 필요한 경우만 추가

4-2. OpenAI API 키 발급

https://platform.openai.com/api-keys 접속
로그인 (없으면 가입)
Create new secret key 클릭
키 복사 → .env에 붙여넣기
최소 5달러 충전 필요 (Billing → Add payment method)

🚨 절대 주의 .env 파일은 GitHub에 올라가면 안 됩니다!
.gitignore에 .env가 이미 포함되어 있는지 확인하세요.

4-3. .gitignore 확인

type .gitignore | findstr ".env"

.env 또는 .env*가 출력되면 OK.

5수정 + GitHub 푸시

5-1. README 수정 (자기 봇 소개로)

VS Code에서 README.md 열기 → 본인 봇 이름과 설명으로 수정.

5-2. Git에 커밋

git add .
git commit -m "Initial commit: 내 봇 시작"

5-3. GitHub 레포와 연결

git remote add origin https://github.com/본인_사용자명/my-sikgu-bot.git
git push -u origin main

처음에는 GitHub 로그인 창이 뜹니다. 브라우저에서 인증하면 자동 푸시됩니다.

💡 매번 푸시할 때 수정 후에는 다음 3줄만 반복하면 됩니다.

git add .
git commit -m "수정 내용"
git push

6Vercel 배포

GitHub에 푸시한 코드를 Vercel이 자동으로 웹사이트로 배포해줍니다.

6-1. Vercel 가입

https://vercel.com/signup 접속
"Continue with GitHub" 선택 (GitHub로 가입)
권한 승인

6-2. 프로젝트 배포

대시보드에서 Add New → Project
본인 GitHub 레포 (my-sikgu-bot) 선택 → Import
Framework Preset: Vite 자동 인식
Environment Variables 펼치기 → 키 추가:
- Name: OPENAI_API_KEY
- Value: sk-proj-... (본인 키)
Deploy 클릭

6-3. 완료!

1~3분 후 https://my-sikgu-bot.vercel.app 같은 URL이 생성됩니다.

💡 자동 재배포 앞으로 GitHub에 푸시할 때마다 Vercel이 자동 재배포합니다.

7카카오 SDK 설정 (공유 기능)

카카오톡으로 봇을 친구에게 공유할 수 있게 하는 단계입니다.

7-1. Kakao Developers 가입

https://developers.kakao.com/ 접속
카카오 계정으로 로그인
내 애플리케이션 → 애플리케이션 추가하기
앱 이름 입력 (예: "식구") → 생성

7-2. JavaScript 키 복사

앱 선택 → 요약 정보 → JavaScript 키 복사

7-3. 사이트 도메인 등록

좌측 플랫폼 → Web 플랫폼 등록
사이트 도메인에 Vercel URL 입력:
```
https://my-sikgu-bot.vercel.app
```

7-4. 코드에 키 반영

VS Code에서 index.html 열기 → Kakao 키 부분 찾기 → 본인 키로 교체:

// 기존
Kakao.init('7684413809de4ce53d7f61071bcd56fd');

// 본인 키로 교체
Kakao.init('본인의_JavaScript_키');

저장 후 다시 푸시:

git add .
git commit -m "Update Kakao SDK key"
git push

8RAG 데이터 수정 — 나만의 지식 넣기

봇이 답변할 때 참조하는 지식 데이터를 본인 봇 주제에 맞게 바꿉니다.

8-1. RAG 데이터 위치

server/
├── new_chunks.jsonl              ← 지식 청크 (수정 대상)
├── detailed_chunks_2026-05-05.jsonl
└── add_to_rag.js                 ← 청크 추가 스크립트

8-2. 청크 형식 이해

JSONL 형식 (한 줄당 하나의 JSON). 예시:

{"id": "food-001", "section": "한식", "question": "김치찌개 추천", "answer": "1인 가구라면 작은 뚝배기에 두부, 김치, 참치를 넣고 끓이세요. 10분이면 완성."}
{"id": "food-002", "section": "양식", "question": "파스타 간단 레시피", "answer": "면 삶는 동안 마늘 + 올리브유 + 페퍼론치노 볶고, 면수 한 국자 + 면 투입. 5분 완성."}

8-3. 본인 봇용 청크 만들기

VS Code에서 server/new_chunks.jsonl 열기
기존 청크 삭제
본인 봇 주제 청크 50~100개 작성
저장

8-4. 청크 작성 팁

question: 사용자가 물어볼 만한 자연어 질문
answer: 짧고 구체적 (2~5줄)
section: 카테고리 (예: "노후", "주거", "반려동물")
너무 길면 안 됨 (1청크 = 300~500자)

8-5. RAG 임베딩 재생성

cd server
node add_to_rag.js new_chunks.jsonl

완료되면 임베딩 파일이 업데이트됩니다.

💡 AI로 청크 만들기 ChatGPT/Claude에 다음 프롬프트 입력:
"1인 가구 식사 봇에 쓸 RAG 청크 50개를 JSONL 형식으로 만들어줘. 형식: {"id":"...","section":"...","question":"...","answer":"..."}"

9VRoid 아바타 만들기

봇의 3D 캐릭터를 본인 봇 페르소나에 맞게 새로 만듭니다.

9-1. VRoid Studio 다운로드

https://vroid.com/en/studio 접속
Windows / Mac 버전 다운로드 (무료)
설치 후 실행

9-2. 캐릭터 만들기

New → 기본 캐릭터 선택 (남성/여성)
좌측 메뉴에서 외형 커스터마이즈:
- Face: 얼굴형, 눈, 코, 입
- Hair: 헤어스타일, 색상
- Body: 체형
- Outfit: 의상 (한복, 정장, 캐주얼)
- Accessories: 안경, 모자 등
본인 봇 페르소나에 맞게 디자인
- 식구 → 따뜻한 앞치마 캐릭터
- 상도 → 한복 + 정장 (시대 혼합)
- 토닥이 → 보들보들 핑크 캐릭터

9-3. VRM으로 Export

상단 메뉴 Camera/Exporter → Export
Export as VRM 선택
VRM 버전: VRM 0.0 또는 VRM 1.0
저장 위치 선택, 파일명: avatar.vrm

9-4. 프로젝트에 적용

기존 public/avatar.vrm 파일 삭제
새로 만든 avatar.vrm을 public/ 폴더에 복사
로컬에서 확인:
```
npm run dev
```

OK면 푸시:

git add public/avatar.vrm
git commit -m "Update avatar"
git push

⚠️ 파일 크기 주의 VRM 파일이 너무 크면 (50MB+) GitHub 푸시 시 거부될 수 있음.
VRoid Studio에서 텍스처 압축 옵션을 활용하세요.

10AI 코딩 도구로 페르소나 변경

봇의 말투, 성격, 대화 스타일을 AI 도구로 한 번에 바꿀 수 있습니다.

10-1. 페르소나 설정 위치 찾기

일반적으로 src/App.jsx 또는 api/chat.js에 시스템 프롬프트가 있습니다.

// 예시 (src/App.jsx 내)
const SYSTEM_PROMPT = `
당신은 차의과학대 신입생 전공 상담 챗봇입니다.
친절하고 전문적으로 답변하세요.
`;

10-2. 방법 ①: Claude Code (CLI)

Claude Code 설치:

npm install -g @anthropic-ai/claude-code

프로젝트 폴더에서:
```
claude
```

프롬프트:

"이 봇을 '식구' 페르소나로 바꿔줘.
1인 가구의 식사 동반자, 친근한 친구 톤,
음식 사진 받으면 영양 분석 + 짧은 식사 대화 하도록."

Claude가 파일 자동 수정 → Yes 승인

10-3. 방법 ②: ChatGPT Codex

ChatGPT 접속
관련 파일 (예: App.jsx) 내용 복사 → 채팅창에 붙여넣기

프롬프트:

"이 코드의 시스템 프롬프트를 '식구' 봇 페르소나로 바꿔줘.
1인 가구 식사 동반자, 친근한 톤."

수정된 코드 받기 → VS Code에서 교체

10-4. 방법 ③: Google Gemini

Gemini 접속
같은 방식으로 코드 붙여넣기 + 프롬프트

10-5. 변경 후 테스트

npm run dev

봇과 대화해서 페르소나가 바뀌었는지 확인 → OK면 푸시

💡 효과적인 프롬프트 예시

"이 봇의 페르소나를 다음으로 바꿔줘:

이름: 식구
나이: 30살, 1인 가구 친구
톤: 친근한 반말, 가끔 존댓말
특기: 영양 분석 + 정서적 동반
말투 예시: '오 김치찌개! 든든하게 먹어~'

관련 파일 모두 수정하고, 인사말도 바꿔줘."

11완성! 봇 공유하기

11-1. 최종 체크리스트

항목	확인
GitHub 푸시 완료	✅
Vercel 배포 성공	✅
카카오 SDK 키 본인 것	✅
RAG 데이터 본인 봇 주제	✅
VRM 아바타 교체	✅
페르소나 시스템 프롬프트 변경	✅

11-2. 친구에게 공유

Vercel URL을 카카오톡으로 보내거나, QR 코드로 공유:

URL: https://본인-봇-이름.vercel.app
QR 생성: qr-code-generator.com

11-3. 개선 사이클

친구 피드백 수집
VS Code에서 수정
git push → Vercel 자동 재배포
반복!

🎉 축하합니다! 이제 본인만의 AI 친구 봇이 인터넷에 살아 있습니다. 🤖

📚 추가 학습 자료

🆘 자주 겪는 문제

Q1: `npm install` 실패

node_modules, package-lock.json 삭제 후 재시도
Node.js 버전 확인 (LTS 권장)

Q2: Vercel 배포 실패

환경 변수 OPENAI_API_KEY 설정 확인
빌드 로그 확인 (Vercel 대시보드)

Q3: 봇이 응답 안 함

OpenAI API 키 잔액 확인 (Billing)
브라우저 콘솔(F12) 에러 메시지 확인

Q4: 카톡 인앱 브라우저에서 마이크 안 됨

의도된 동작 — 인앱 브라우저는 WebRTC 미지원
코드에 이미 외부 브라우저(Chrome/Safari) 리다이렉트 구현됨

Q5: VRM 파일 너무 큼

VRoid Studio에서 텍스처 압축
또는 Git LFS 사용: git lfs track "*.vrm"

🛠️ 나만의 봇 만들기 자습서

1사전 준비 — Node.js, Git 설치 확인

1-1. Node.js 확인

1-2. Git 확인

1-3. 코드 에디터 (VS Code 권장)

2GitHub 계정 + 레포 만들기

2-1. GitHub 가입 (이미 있으면 건너뛰기)

2-2. 새 레포지토리 만들기

2-3. Git에 GitHub 계정 등록 (최초 1회)

3템플릿 클론 + 로컬 실행

3-1. 작업 폴더로 이동

3-2. 참고 레포 클론

3-3. 기존 .git 폴더 삭제 (내 레포로 새로 시작)

3-4. 의존성 설치

3-5. 로컬 실행

4환경 변수 설정 (.env)

4-1. .env 파일 생성

4-2. OpenAI API 키 발급

4-3. .gitignore 확인

5수정 + GitHub 푸시

5-1. README 수정 (자기 봇 소개로)

5-2. Git에 커밋

5-3. GitHub 레포와 연결

6Vercel 배포

6-1. Vercel 가입

6-2. 프로젝트 배포

6-3. 완료!

7카카오 SDK 설정 (공유 기능)

7-1. Kakao Developers 가입

7-2. JavaScript 키 복사

7-3. 사이트 도메인 등록

7-4. 코드에 키 반영

8RAG 데이터 수정 — 나만의 지식 넣기

8-1. RAG 데이터 위치

8-2. 청크 형식 이해

8-3. 본인 봇용 청크 만들기

8-4. 청크 작성 팁

8-5. RAG 임베딩 재생성

9VRoid 아바타 만들기

9-1. VRoid Studio 다운로드

9-2. 캐릭터 만들기

9-3. VRM으로 Export

9-4. 프로젝트에 적용

10AI 코딩 도구로 페르소나 변경

10-1. 페르소나 설정 위치 찾기

10-2. 방법 ①: Claude Code (CLI)

10-3. 방법 ②: ChatGPT Codex

10-4. 방법 ③: Google Gemini

10-5. 변경 후 테스트

11완성! 봇 공유하기

11-1. 최종 체크리스트

11-2. 친구에게 공유

11-3. 개선 사이클

📚 추가 학습 자료

🆘 자주 겪는 문제

Q1: npm install 실패

Q2: Vercel 배포 실패

Q3: 봇이 응답 안 함

Q4: 카톡 인앱 브라우저에서 마이크 안 됨

Q5: VRM 파일 너무 큼

Q1: `npm install` 실패