코덱스 AI 챗봇 만들기, 업스테이지 API와 웹 검색 붙여 배포

코덱스 AI 챗봇 만들기를 API 키 발급부터 인터넷 배포까지 순서대로 정리했습니다. 한국 회사 업스테이지(Upstage)의 언어 모델 API로 답하고, 최신 정보는 웹 검색 API인 Tavily(태빌리)로 찾아오는 챗GPT 같은 채팅 사이트를 코덱스(Codex)에게 만들게 한 뒤, 깃허브(GitHub)에 올려 버셀(Vercel)로 배포합니다. API 키를 새지 않게 다루는 법과 샜을 때 바꾸는 법도 함께 담았습니다.

코덱스 AI 챗봇 만들기 전에 알아 둘 원리

챗봇은 LLM에 도구를 붙인 것

GPT·제미나이⁠·클로드 같은 LLM(대규모 언어 모델)은 다음에 올 법한 토큰(글 조각)을 확률로 하나씩 골라 문장을 잇는 프로그램입니다. "How are you?"를 들으면 습관처럼 "Fine, thank you, and you?"가 나오는 것과 비슷합니다. 토큰과 학습 원리는 "LLM 원리" 글에서 자세히 다룹니다.

그래서 GPT 모델 혼자서는 오늘 서울 날씨를 모릅니다. 최신 모델도 학습 데이터가 끝나는 시점(지식 컷오프)이 있기 때문입니다. 챗GPT가 날씨나 뉴스에 답하는 건 모델에 검색⁠·계산 같은 외부 도구를 붙여 놨기 때문입니다. GPT(모델)와 챗GPT(모델에 도구와 화면을 붙인 서비스)가 다른 이유가 여기 있습니다. 이번에 만드는 챗봇도 같은 구조입니다. 도구(Tavily)가 최신 정보를 가져오면 LLM(업스테이지 모델)이 그걸 받아 문장으로 만듭니다.

API와 API 키

API는 "이렇게 요청하면 이렇게 응답하겠다"고 서버가 정해 둔 약속입니다. 식당 메뉴판처럼, 정해진 형식으로 주문하면 정해진 결과가 나옵니다. LLM은 연산량이 너무 커서 내 컴퓨터나 배포 서버에서 직접 돌릴 수 없습니다. 그래서 내 챗봇은 질문을 모델 회사 서버로 보내고 답만 받아 옵니다. 코덱스 앱이 인터넷 없이는 돌아가지 않는 것도 같은 이유입니다.

API 키는 누가 요청했고 얼마나 썼는지 가려내는 열쇠입니다. 주민등록번호처럼 나를 증명하는 값이라 키가 새면 남이 내 크레딧으로 요금을 씁니다. 깃허브, 블로그, 댓글, 화면 캡처에 키를 남기지 않고 내 컴퓨터의 메모장에만 적어 둡니다.

MCP와 스킬

MCP(Model Context Protocol)는 AI 모델에게 최신 정보 같은 문맥을 넘겨주도록 정해 둔 연결 규격입니다. 영화 〈매트릭스〉에서 능력을 심어 주자 갑자기 무술을 하고 헬기를 모는 장면처럼, 모델에 없던 능력을 붙여 줍니다. Tavily는 일반 API와 MCP 서버를 모두 제공하는 실시간 웹 검색 서비스입니다.

스킬은 에이전트에게 "이런 방식으로 일하라"고 적어 둔 지침 문서(.md 파일)입니다. 매번 같은 지시를 반복하지 않으려고 파일로 만들어 둡니다. 이번에는 두 가지를 씁니다.

• 디자인 파일: 특정 회사 스타일로 화면을 만들게 하는 문서입니다. 나이키, 테슬라, 애플, 에어비앤비 같은 회사의 색상⁠·글꼴⁠·간격 규칙을 정리한 DESIGN.md 파일 모음(awesome-design-md)이 깃허브에 공개돼 있습니다.
• 카파시 코딩 지침: 안드레이 카파시(Andrej Karpathy)가 짚은 AI 코딩의 흔한 실수를 바탕으로 만든 짧은 지침 파일(andrej-karpathy-skills)입니다. 먼저 생각하고 코딩하라, 단순하게 하라, 필요한 곳만 수술하듯 고쳐라, 목표를 기준으로 실행하라는 네 원칙이 65줄 남짓에 들어 있습니다.

코덱스는 프로젝트 폴더의 AGENTS.md라는 이름의 파일을 작업 전에 자동으로 읽습니다. 클로드 코드는 CLAUDE.md를 읽습니다. 카파시 지침은 원래 CLAUDE.md 이름으로 배포되니, 코덱스에서 쓰려면 이름을 AGENTS.md로 바꿉니다. 디자인 파일은 자동으로 읽히지 않으니 지시문에 파일 이름을 적어 읽게 합니다.

준비물과 비용

• 코덱스 앱. 설치와 깃허브⁠·버셀 가입은 "바이브 코딩 웹사이트 만들기" 글의 순서를 따릅니다.
• 깃허브 계정, 버셀 계정, VS 코드
• 구글 계정. 업스테이지와 Tavily 가입에 씁니다.
• 메모장. API 키를 적어 둘 곳입니다. 내 컴퓨터에만 둡니다.
• 업스테이지 비용: 쓴 만큼 내는 방식입니다. 2026년 9월 무렵에는 가입하면 10달러어치 무료 크레딧을 줬고, 다 쓰면 10달러, 100달러 단위로 충전했습니다. 지금 신규 크레딧이 있는지는 콘솔에서 확인합니다.
• Tavily 비용: 무료 플랜은 매달 1,000크레딧이고, 기본 검색 한 번에 1크레딧이 듭니다(2026년 10월 공식 문서 기준).

모델 이름도 확인해야 합니다. 업스테이지 공식 문서 기준으로 Solar Pro 3, Solar Pro 2, Solar Mini는 2026년 10월 30일(한국 시간)에 서비스가 완전히 끝납니다. 지금 새로 만든다면 Solar Pro 4처럼 콘솔 모델 목록에 서비스 중으로 나온 모델을 씁니다. 이미 Solar Pro 3로 만들어 둔 챗봇도 그날 전에 모델 값을 바꿔야 답이 계속 나옵니다.

따라 하기 1. 업스테이지 API 키 받기

1. 구글에서 "업스테이지"를 검색해 upstage.ai로 들어갑니다.
   • 확인: 업스테이지 홈페이지가 열린다. 오른쪽 위에서 한국어로 바꿀 수 있다.
2. "Console"(개발자 콘솔) 버튼을 누릅니다.
   • 확인: 업스테이지 모델 목록과 오른쪽 위 로그인 버튼이 보인다.
3. 로그인 버튼을 누르고 가입 화면에서 구글 계정으로 가입합니다.
   • 확인: 콘솔 첫 화면으로 들어간다.
4. 왼쪽 "시작하기"(Get Started)나 대시보드에서 크레딧과 API 키 영역을 확인합니다.
   • 확인: 남은 크레딧 표시와 발급된 API 키가 보인다. 키가 없으면 "Create new key"로 만든다.
5. API 키를 복사해 메모장에 "업스테이지 키:" 뒤에 붙여 넣습니다.
   • 확인: 메모장에 키가 적혀 있다.

따라 하기 2. Tavily API 키 받기

6. 구글에서 "Tavily"를 검색해 tavily.com으로 들어갑니다. MCP 서버 안내 페이지가 먼저 나와도 됩니다. 그 페이지의 코드는 읽지 않아도 되고, 코드는 코덱스가 씁니다.
7. 오른쪽 위의 API 키 받기(Get API Key) 버튼을 누르고 구글 계정으로 가입합니다.
   • 확인: 대시보드에 월 1,000크레딧 무료 안내와 API 키가 보인다.
8. API 키를 눌러 복사하고 메모장에 "Tavily 키:" 뒤에 붙여 넣습니다.
   • 확인: 메모장에 두 키가 이름표와 함께 따로 적혀 있다.

따라 하기 3. 작업 폴더와 코덱스 프로젝트

9. 바탕화면에 chatbot이라는 빈 폴더를 만듭니다.
10. 코덱스 앱을 열고 왼쪽 "프로젝트"에 마우스를 올려 "+"를 누른 뒤 "로컬"(내 컴퓨터에서 사용)을 고르고 "다음"을 누릅니다.
11. chatbot 폴더를 고르고 "프로젝트 만들기"를 누릅니다.
    • 확인: chatbot 프로젝트가 생기고 입력칸이 보인다.
12. 모델을 고릅니다. 처음 만드는 작업이니 GPT-6 아스트라나 GPT-5.6 솔처럼 쓸 수 있는 상위 모델을 고릅니다. 둘 다 이 정도 코드는 충분히 씁니다.

따라 하기 4. 스킬 파일 두 개 넣기

디자인 파일

13. 구글에서 "awesome design md"를 검색해 VoltAgent가 만든 awesome-design-md 저장소로 들어갑니다.
    • 확인: 바이낸스, 에어비앤비, 나이키, IBM, 애플 같은 회사 이름 목록이 보인다.
14. 원하는 회사를 눌러 그 회사의 DESIGN.md를 엽니다. 예시는 에어비앤비입니다.
    • 확인: 색상, 글꼴, 버튼 모양 같은 규칙이 영어로 적힌 문서가 보인다.
15. 다운로드 버튼으로 .md 파일을 받습니다. 처음이면 가입하라는 안내가 나올 수 있고, 구글 계정으로 가입하면 됩니다.
    • 확인: 다운로드 폴더에 .md 파일이 생긴다. 더블클릭하면 VS 코드로 열려 "에어비앤비 스타일로, 색상과 글꼴은 이렇게" 같은 지침이 보인다.
16. 그 파일을 chatbot 폴더에 복사해 넣고 이름을 디자인.md로 바꿉니다.
    • 확인: chatbot 폴더 안에 디자인.md가 있다.

카파시 코딩 지침

17. 구글에서 "andrej karpathy skills"를 검색해 깃허브의 andrej-karpathy-skills 저장소로 들어갑니다.
18. 파일 목록에서 CLAUDE.md를 눌러 내용을 봅니다.
    • 확인: 네 가지 원칙이 적힌 짧은 지침 문서다.
19. 오른쪽 위 다운로드(Download raw file) 버튼으로 파일을 받습니다.
    • 확인: 다운로드 폴더에 CLAUDE.md가 생긴다.
20. 그 파일을 chatbot 폴더에 복사해 넣고 이름을 AGENTS.md로 바꿉니다. 끝의 s를 빠뜨리면 코덱스가 읽지 않습니다.
    • 확인: 폴더 안 파일 이름이 정확히 AGENTS.md다. 클로드 코드를 쓴다면 CLAUDE.md 이름 그대로 둔다.

따라 하기 5. 지시문으로 챗봇 만들기

21. 아래 지시문을 복사해 코덱스 입력칸에 붙여 넣습니다. "모아 AI"는 예시 이름이니 "모두의 AI"처럼 원하는 이름으로 바꿉니다.

업스테이지 API로 "모아 AI"라는 이름의 간단한 AI 채팅 웹사이트를 만들어 줘.
- 나중에 버셀로 배포할 수 있게 Next.js로 개발해 줘.
- 사용자가 질문하면 업스테이지 LLM API를 호출해 답하게 해 줘. 모델은 지금 서비스 중인 Solar Pro 4를 써 줘.
- 최신 정보가 필요한 질문은 Tavily 웹 검색 결과를 참고해 답하게 해 줘.
- 채팅 화면은 챗GPT처럼 간단하게 만들고, 폴더의 디자인.md를 따라 디자인해 줘.
- API 키는 .env.local 파일에만 저장하고 코드에 직접 쓰지 마. .env.local은 깃에 올라가지 않게 해 줘.
- 업스테이지 API 키: (메모장의 업스테이지 키)
- Tavily API 키: (메모장의 Tavily 키)
- 구현이 끝나면 크롬에서 바로 열어 볼 수 있게 실행해 줘.

22. 괄호 두 곳을 메모장의 내 키로 바꿉니다.
    • 주의: 키를 지시문에 붙이면 코덱스 대화 기록에도 남습니다. 대화 화면을 캡처해 공유하지 않습니다. 더 조심하고 싶다면 키 두 줄을 빼고 보낸 뒤, 코덱스가 만든 .env.local 파일을 VS 코드로 열어 직접 키를 적어 넣어도 됩니다.
23. 엔터를 누르고 작업이 끝날 때까지 기다립니다. 한 사례에서는 약 13분 44초가 걸렸습니다.
    • 확인: 개발이 끝났다는 안내와 함께 localhost:3000 같은 링크가 나온다.

따라 하기 6. 내 컴퓨터에서 확인하기

24. 완료 안내의 링크를 크롬에서 엽니다.
    • 확인: 챗GPT와 비슷한 채팅 화면이 열리고, 디자인 파일의 색상이 쓰여 있다. 필요 없는 문구가 보이면 코덱스에게 지워 달라고 하면 된다.
25. 입력칸에 아래 문장을 넣고 보냅니다.

오늘 한국 주요 경제 뉴스 요약해 줘.

26. 답을 확인합니다.
    • 확인: 오늘 날짜 기준 뉴스 몇 가지를 요약한 답이 나온다.
27. Tavily 대시보드를 새로고침합니다.
    • 확인: 사용한 크레딧이 늘어 있다. 한 사례에서는 질문 하나에 검색 5번, 5크레딧이 쓰였다.
28. 업스테이지 콘솔 오른쪽 위 계정 메뉴에서 조직 관리(Manage Organization) > Usage로 들어갑니다.
    • 확인: 날짜⁠·모델별 사용 내역에 방금 쓴 모델이 찍혀 있다.

따라 하기 7. 코드를 깃허브에 올리기

버셀은 깃허브에 있는 코드를 가져가 배포하므로 먼저 올립니다.

29. 깃허브에서 "New"를 누르고 저장소 이름 chatbot, 공개 범위 "Private"(비공개)로 "Create repository"를 누릅니다.
30. 저장소 주소를 복사해 코덱스 입력칸에 붙여 넣고, 이어서 아래 문장을 입력합니다.

지금까지 작성한 코드 여기에 올려 주세요.

31. 모델을 GPT-5.6 테라처럼 가벼운 모델로 바꾸고 보냅니다. 올리기에는 좋은 모델이 필요 없습니다.
    • 확인: 1분 남짓 뒤 업로드가 끝났다는 답이 나온다.
32. 깃허브 저장소를 새로고침합니다.
    • 확인: 코드 파일이 올라와 있고, .env.local 파일은 목록에 없다.
33. 코덱스 답에 "API 키는 업로드하지 않았다"는 내용이 있는지 봅니다.
    • 확인: 키가 올라가지 않았다. 키가 든 파일이 저장소에 보이면 그 키는 새로 발급받아 바꾼다(아래 "따라 하기 9").

따라 하기 8. 버셀에 배포하기

배포된 챗봇은 내 컴퓨터의 .env.local을 볼 수 없습니다. 그래서 키는 버셀의 환경 변수(Environment Variables, 코드 밖에 따로 보관하는 설정값)에 직접 넣습니다.

34. 코덱스 입력칸에 아래처럼 묻습니다.

버셀에 배포할 건데 API 키는 어떻게 입력해?

35. 답에 나온 환경 변수 이름과 값의 종류를 메모장에 적어 둡니다.
    • 확인: 넣어야 할 변수 이름을 안다. 업스테이지 키, Tavily 키, 업스테이지 모델 이름처럼 세 개일 수도, 두 개일 수도 있다. 개수는 코드마다 다르니 코덱스 안내를 따른다.
36. 버셀 대시보드 오른쪽 위 "Add New" > "Project"를 누릅니다.
    • 확인: 방금 올린 chatbot 저장소가 목록에 보인다.
37. chatbot 옆의 "Import"를 누릅니다.
    • 확인: Next.js로 자동 설정되고, "Deploy" 버튼 위에 "Environment Variables" 영역이 보인다.
38. "Environment Variables"를 펼치고, 코덱스가 알려 준 이름마다 값을 넣습니다. 키 값은 메모장에서, 모델 값은 코덱스가 알려 준 값을 그대로 복사해 씁니다.
    • 확인: 변수 이름과 값이 빠짐없이 들어가 있다.
39. "Deploy"를 누르고 기다립니다. 중간에 노란 경고가 보여도 끝날 때까지 둡니다.
    • 확인: "Congratulations" 화면이 나온다.
40. 화면의 미리보기나 주소를 눌러 배포된 챗봇을 엽니다.
41. "안녕하세요"를 보내 봅니다.
    • 확인: 업스테이지 모델이 만든 인사가 돌아온다.
42. 아래 문장을 보내 봅니다.

오늘 한국 주요 경제 뉴스 세 개 알려 주세요

43. 답을 확인합니다.
    • 확인: 최신 기사를 바탕으로 한 답이 나온다. Tavily가 검색하고 업스테이지 모델이 문장을 만든 결과다. 화면 디자인도 디자인 파일대로 나와 있다.

따라 하기 9. API 키가 샌 것 같을 때 바꾸기

크레딧이 쓴 적 없이 줄어들면 키가 샜을 수 있습니다. 옛 키를 지우고 새 키로 바꿉니다.

44. 업스테이지 콘솔 오른쪽 위 계정 메뉴에서 조직 관리로 들어가 API 키 목록을 엽니다.
45. 샌 키 옆의 휴지통 버튼을 눌러 지웁니다.
    • 확인: 그 키가 목록에서 사라진다. 이 순간부터 옛 키로는 아무도 쓸 수 없다.
46. "Create new key"를 눌러 새 키를 만들고 복사해, 메모장의 옛 키를 새 키로 바꿔 적습니다.
47. 버셀에서 chatbot 프로젝트를 열고 Settings > Environment Variables로 들어갑니다.
    • 확인: 입력해 둔 변수 목록이 보인다.
48. 바꿀 변수 오른쪽의 더보기(점 세 개) 버튼 > "Edit"를 누르고 새 키를 넣은 뒤 "Save"를 누릅니다.
    • 확인: 값이 저장된다.
49. "Deployments"에서 가장 최근 배포의 더보기 버튼 > "Redeploy"를 누릅니다. 버셀 공식 문서 기준으로 환경 변수를 바꾸면 새로 배포한 뒤부터 적용됩니다.
    • 확인: 재배포가 끝난 뒤 챗봇이 새 키로 답한다.

Tavily 키가 샜다면 Tavily 대시보드에서 같은 방식으로 키를 지우고 새로 만든 뒤 47~49단계를 반복합니다.

코덱스 챗봇이 막힐 때

• 답이 안 나오거나 키 오류가 난다: 버셀 환경 변수의 이름이나 값이 코덱스 안내와 다를 가능성이 큽니다. 코덱스에게 "API 키는 어떻게 입력해?"를 다시 묻고 이름을 한 글자씩 맞춥니다. 고친 뒤에는 재배포합니다.
• 2026년 10월 30일 이후 갑자기 답이 멈췄다: Solar Pro 3 같은 종료 모델을 쓰고 있을 수 있습니다. 버셀의 모델 환경 변수를 Solar Pro 4처럼 서비스 중인 모델로 바꾸고 재배포합니다. 정확한 모델 값은 코덱스에게 "업스테이지 최신 모델로 바꿔 줘"라고 시키면 알려 줍니다.
• 깃허브에 키가 없다: 정상입니다. 키는 일부러 올리지 않고 버셀 환경 변수에 직접 넣습니다.
• 배포 중 경고가 뜬다: 끝날 때까지 기다린 뒤 결과 화면을 봅니다. 실패로 끝나면 빌드 기록의 빨간 오류 줄을 코덱스에 붙여 넣고 고쳐 달라고 합니다.
• 코덱스가 지침 파일을 안 따르는 것 같다: 파일 이름을 봅니다. 코덱스는 AGENTS.md, 클로드 코드는 CLAUDE.md를 읽습니다. 디자인 파일은 지시문에 이름을 적어야 읽습니다.

마지막 점검

• 업스테이지 키와 Tavily 키를 받아 메모장에 이름표와 함께 따로 적어 두었다.
• chatbot 폴더가 코덱스 프로젝트로 등록됐고, 안에 디자인.md와 AGENTS.md가 있다.
• 내 컴퓨터에서 "오늘 한국 주요 경제 뉴스 요약해 줘."에 최신 답이 나왔다.
• 깃허브 비공개 저장소에 코드가 올라갔고, 키는 올라가지 않았다.
• 버셀에 환경 변수를 넣고 배포했으며, 배포 주소에서 인사와 최신 뉴스 질문에 모두 답이 나온다.

여기에 회사 자료를 근거로 답하는 기능(RAG)과 구글 로그인, 대화 기록 저장을 붙이는 순서는 "RAG 챗봇 만들기" 글에서 이어집니다.