Cloudflare Workers 텔레그램 봇

Cloudflare Workers + D1 + OpenAI를 활용한 사용자 프로필 기반 텔레그램 봇

📖 이 문서: 기능 소개, 배포 가이드, 사용법 (사용자/운영자용) 🔧 CLAUDE.md: 기술 상세, 코드 패턴, 트러블슈팅 (개발자용)

목차

1. 개요
2. 아키텍처
3. Function Calling
4. 예치금 시스템
5. 도메인 관리
6. 프로젝트 구조
7. 배포 가이드
8. 보안 설정
9. 봇 명령어

---

개요

주요 기능

• OpenAI GPT-4o-mini: 고품질 AI 응답 및 Function Calling 지원
• 사용자 프로필: 대화에서 사용자의 관심사, 목표, 맥락을 추출하여 프로필 구축
• Function Calling (8개): 날씨, 검색, 시간, 계산, 문서 조회, 도메인 관리, 도메인 추천, 예치금 관리
• Context7 연동: 프로그래밍 라이브러리 공식 문서 실시간 조회
• 동적 도구 로딩: 메시지 키워드 기반으로 필요한 도구만 선택하여 토큰 절약
• 도메인 추천: GPT가 창의적 도메인 생성 → 가용성 자동 확인 → 가격과 함께 제안
• 예치금 시스템: 코드 직접 처리, 은행 입금 자동 감지 + 사용자 신고 매칭으로 자동 충전
• Email Worker: SMS → 메일 → 자동 파싱으로 입금 알림 처리
• 무한 컨텍스트: 슬라이딩 윈도우(3개)로 프로필 유지, 무제한 대화 기억
• 개인화 응답: 프로필 기반으로 맞춤형 AI 응답 제공
• 폴백 지원: OpenAI 미설정 시 Workers AI(Llama)로 자동 전환

기술 스택

서비스	용도
Workers	서버리스 런타임
D1	SQLite 데이터베이스
OpenAI	GPT-4o-mini + Function Calling
Context7	라이브러리 문서 조회 API
도메인 관리	코드 직접 처리 → Namecheap API
도메인 추천	GPT + Namecheap API (코드 레벨)
예치금 관리	코드 직접 처리 → D1
Namecheap API	도메인 조회/가용성/가격 백엔드
Email Workers	SMS → 메일 파싱 (입금 알림)
Workers AI	폴백용 (Llama 3.1 8B)

---

아키텍처

메시지 처리 흐름

[사용자 메시지]
       │
       ▼
┌──────────────────┐
│  Cloudflare      │
│  Worker          │
└──────────────────┘
       │
       ▼
┌──────────────────┐
│  OpenAI API      │ ← GPT-4o-mini
│  (Function Call) │   도구 호출 자동 판단
└──────────────────┘
       │
   ┌───┴───┬───────┬───────┬───────┬───────┬───────┬───────┐
   ▼       ▼       ▼       ▼       ▼       ▼       ▼       ▼
[날씨]  [검색]  [시간]  [계산]  [문서]  [도메인] [도메인  [예치금]
   │       │       │       │       │       │      추천]    │
   │       │       │       │       │       │       │       └── Deposit Agent
   │       │       │       │       │       │       └── GPT + Namecheap API
   │       │       │       │       │       └── 코드 직접 처리 → Namecheap API
   │       │       │       │       └── Context7
   └───┬───┴───────┴───────┴───────┴───────────────────────────┘
       ▼
┌──────────────────┐
│  최종 응답 생성   │
└──────────────────┘
       │
       ▼
[D1 저장] → [Telegram 응답]

사용자 프로필 시스템

[사용자 메시지]
       │
       ▼
┌──────────────────┐
│  message_buffer  │ ← 최대 19개 (20개 되면 프로필 업데이트)
└──────────────────┘
       │ 20개 도달
       ▼
┌──────────────────────────────────────────┐
│              통합 프로필 분석              │
│  ┌─────────────────┐  ┌───────────────┐  │
│  │ 기존 요약 3개    │  │ 새 메시지 20개 │  │
│  │ [v1][v2][v3]    │  │ (사용자 발언)  │  │
│  └────────┬────────┘  └───────┬───────┘  │
│           └──────────┬────────┘          │
│                      ↓                    │
│           OpenAI 통합 분석               │
└──────────────────────────────────────────┘
       │
       ▼
┌──────────────────┐
│    summaries     │ ← 최근 3개만 유지 (슬라이딩 윈도우)
│  [v1] [v2] [v3]  │   새 v4 저장, v1 삭제
└──────────────────┘

3개 요약 통합 방식:

• 프로필 업데이트 시 기존 요약 3개 + 새 메시지를 함께 AI에 전달
• AI가 모든 버전을 종합 분석하여 새로운 통합 프로필 생성
• 응답 생성 시에도 3개 요약 모두 컨텍스트로 제공 (최신 버전 우선)

프로필 분석 내용

추출 정보	설명
관심사	사용자가 자주 언급하는 주제
목표	해결하려는 문제, 달성하려는 것
맥락	직업, 상황, 배경 정보
선호도	좋아하는 것, 싫어하는 것
질문 패턴	무엇에 대해 알고 싶어하는지

---

Function Calling

OpenAI Function Calling을 통해 AI가 자동으로 필요한 도구를 호출합니다.

지원 기능

기능	예시 질문	API
날씨	"서울 날씨", "도쿄 날씨 알려줘"	wttr.in
검색	"파이썬이 뭐야", "클라우드플레어란"	Brave Search
시간	"지금 몇 시야", "뉴욕 시간"	내장
계산	"123 * 456", "100의 20%"	내장
문서	"React hooks 사용법", "OpenAI API 예제"	Context7
도메인	"도메인 목록", "anvil.it.com 네임서버", ".com 가격", "google.com whois"	코드 직접 처리 + WHOIS API
도메인 추천	"커피숍 도메인 추천해줘", "스타트업 도메인 아이디어"	GPT + Namecheap
예치금	"잔액 확인", "충전하고 싶어", "10000원 입금했어"	코드 직접 처리

동작 방식

사용자: "서울 날씨 어때?"
           │
           ▼
OpenAI: "get_weather 함수를 호출해야겠다"
           │
           ▼
Worker: wttr.in API 호출 → 날씨 데이터 수신
           │
           ▼
OpenAI: 날씨 데이터를 자연어로 응답 생성
           │
           ▼
응답: "🌤 서울 날씨\n온도: 5°C\n습도: 45%..."

동적 도구 로딩

메시지 키워드를 분석하여 필요한 도구만 선택적으로 로딩합니다. (토큰 40% 절약)

카테고리	도구	감지 패턴
domain	manage_domain, suggest_domains	도메인, 네임서버, whois, .com
deposit	manage_deposit	입금, 충전, 잔액, 계좌
weather	get_weather	날씨, 기온, 비, 눈
search	search_web, lookup_docs	검색, 찾아, 뭐야, 가격
utility	get_current_time, calculate	(항상 포함)

패턴 매칭 없으면 전체 도구 사용 (폴백)

AI Gateway

OpenAI API 호출을 Cloudflare AI Gateway를 통해 프록시하여 지역 제한을 우회합니다.

Gateway ID: telegram-bot
URL: gateway.ai.cloudflare.com/v1/{account_id}/telegram-bot/openai/...

대시보드: Cloudflare Dashboard → AI → AI Gateway → telegram-bot

---

예치금 시스템

은행 계좌 입금 기반 예치금 충전 시스템입니다. 사용자 신고와 은행 SMS 알림을 양방향으로 자동 매칭합니다.

입금 계좌

은행	계좌번호	예금주
하나은행	427-910018-27104	주식회사 아이언클래드

Vault 경로: secret/companies/ironclad-corp @ vault.anvil.it.com

자동 매칭 흐름

[시나리오 1: 사용자가 먼저 신고]

사용자: "홍길동 50000원 입금했어"
       │
       ▼
┌──────────────────┐
│ bank_notifications│ ← 기존 은행 알림 확인
└──────────────────┘
       │
       ├── 매칭 발견 → 즉시 confirmed + 잔액 증가 (대화 중 응답)
       │
       └── 매칭 없음 → pending 상태로 대기 (SMS 도착 시 자동 매칭 + 알림)

[시나리오 2: 은행 SMS가 먼저 도착]

은행 SMS → 메일 전달 → Cloudflare Email Routing → Worker (email handler)
       │
       ▼
┌──────────────────┐
│  SMS 파싱        │ ← 입금자명, 금액, 은행 추출
│ (하나/KB/신한)   │
└──────────────────┘
       │
       ▼
┌──────────────────┐
│ deposit_transactions│ ← 대기중 입금 확인
└──────────────────┘
       │
       ├── 매칭 발견 → confirmed + 잔액 증가 + 사용자에게 Telegram 알림 🎉
       │                                      + 관리자에게 Telegram 알림
       │
       └── 매칭 없음 → bank_notifications에 저장 + 관리자에게 알림 (대기)

지원 기능

기능	설명	권한
잔액 조회	현재 예치금 잔액 확인	모든 사용자
계좌 안내	입금 계좌 정보 표시	모든 사용자
입금 신고	입금자명 + 금액으로 충전 요청	모든 사용자
거래 내역	최근 거래 내역 조회	모든 사용자
입금 취소	대기중 입금 취소 (번호 없으면 최근 pending 자동 선택)	모든 사용자
대기 목록	미처리 입금 목록 조회	관리자 전용
수동 확인	입금 수동 확정 처리	관리자 전용
입금 거절	입금 요청 거절	관리자 전용

사용법 예시

# 잔액 확인
"잔액" → "현재 잔액: 10,000원"

# 계좌 안내
"입금할게요" → 계좌 정보 안내

# 입금 신고 (자연어 금액 인식 지원)
"홍길동 5000원 입금했어" → 즉시 처리
"홍길동 만원 입금" → 10,000원으로 인식
"홍길동 5천원" → 5,000원으로 인식

# 거래 내역
"거래 내역" → "#5: 입금 10원 ✓ (01/17)"

# 간편 취소
"취소해줘" → 가장 최근 pending 자동 취소

특징:

• 🔢 자연어 금액: "만원", "5천원", "삼만오천원" 등 자동 변환
• ⚡ 즉시 실행: 입금자명+금액 있으면 확인 없이 바로 처리
• 📋 동시 요청: 기존 pending 있어도 새 입금 신고 가능
• 🗑️ 간편 취소: 거래번호 없이 "취소해줘"만으로 최근 pending 취소

자동 알림 시스템

자동 매칭 성공 시 사용자와 관리자 모두에게 Telegram 알림이 전송됩니다.

이벤트	사용자 알림	관리자 알림
자동 매칭 성공	✅ 입금액 + 현재 잔액	✅ 입금 정보 + 매칭 완료
매칭 대기 (SMS만)	-	⏳ 입금 정보 + 대기 상태

사용자가 받는 메시지 예시:

✅ 입금 확인 완료!

입금액: 7원
현재 잔액: 7원

감사합니다! 🎉

Cloudflare Email Routing

SMS를 메일로 전달받아 Worker에서 직접 처리합니다.

흐름:

은행 SMS → 메일 전달 → Cloudflare Email Routing → Worker (email handler)
                                                      ↓
                                              SMS 파싱 → DB 저장 → 자동 매칭
                                                      ↓
                                              매칭 성공 → 사용자/관리자 Telegram 알림

설정 방법:

1. Cloudflare Dashboard → Email → Email Routing → Routes
2. 수신 주소 설정 (예: deposit@your-domain.com)
3. Worker로 라우팅: telegram-summary-bot

지원 은행 SMS 패턴:

• 하나은행 (Web발신): [Web발신] 하나,01/16, 23:30 427******27104 입금5원 황병하
• 하나은행 (기존): [하나은행] 01/16 14:30 입금 50,000원 홍길동 잔액 1,234,567원
• KB국민: [KB] 입금 50,000원 01/16 14:30 홍길동
• 신한: [신한] 01/16 입금 50,000원 홍길동

---

도메인 관리

코드 직접 처리 방식의 도메인 관리 기능입니다. 메인 AI가 action 파라미터로 작업을 지정하고, 코드에서 Namecheap API를 호출합니다.

지원 기능

기능	설명	권한
도메인 목록	내 도메인 목록 조회	소유자
도메인 정보	도메인 상세 정보 (만료일 등)	소유자
네임서버 조회	현재 네임서버 확인	누구나
네임서버 변경	네임서버 설정 변경	소유자
가격 조회	TLD/ccSLD 등록 가격 (원화)	누구나
WHOIS 조회	공개 WHOIS 정보 (RDAP)	누구나
가용성 확인	도메인 등록 가능 여부	누구나
도메인 등록	새 도메인 등록 (예치금 차감)	사용자

가격 조회

Namecheap 가격 + 13% 마진, 매일 환율 업데이트

사용자: ".com 가격"
봇: ".com 도메인 등록 가격은 20,000원입니다."

사용자: "it.com 가격"
봇: "it.com 도메인 등록 가격은 55,000원입니다."

지원 TLD: com, net, org, io, me, info, biz, it.com, uk.com 등

WHOIS 조회

자체 WHOIS API 서버(Vercel)를 통해 TCP 43 포트로 직접 쿼리

사용자: "google.com whois"
봇: 등록일, 만료일, 네임서버, 등록기관 정보 표시

• WHOIS API: https://whois-api-eight.vercel.app
• 지원 TLD: com, net, org, io, co, me, kr, jp, cn, uk, de, fr 등 40+ TLD
• ccSLD 미지원: it.com, uk.com, us.com 등 사설 레지스트리는 WHOIS 비공개

도메인 등록

예치금에서 자동 차감되는 도메인 등록 기능입니다.

[잔액 충분한 경우]
사용자: "example123.com 등록해줘"

봇: 📋 도메인 등록 확인

• 도메인: example123.com
• 가격: 15,000원 (예치금에서 차감)
• 현재 잔액: 50,000원 ✓
• 등록 기간: 1년

📌 등록자 정보
서비스 기본 정보로 등록됩니다.
(WHOIS Guard가 적용되어 개인정보는 비공개)

⚠️ 주의사항
도메인 등록 후에는 취소 및 환불이 불가능합니다.

등록을 진행하시려면 '확인'이라고 입력해주세요.

사용자: "확인"

봇: ✅ example123.com 등록이 완료되었습니다!
예치금 15,000원 차감, 현재 잔액: 35,000원

[잔액 부족한 경우]
사용자: "premium-domain.io 등록해줘"

봇: 📋 도메인 등록 확인

• 도메인: premium-domain.io
• 가격: 45,000원
• 현재 잔액: 10,000원 ⚠️ 부족
• 부족 금액: 35,000원

💳 입금 계좌
하나은행 427-910018-27104 (주식회사 아이언클래드)
입금 후 '홍길동 35000원 입금' 형식으로 알려주세요.

특징:

• 🔍 가용성 자동 확인 후 가격 안내
• 💰 현재 잔액 실시간 표시
• ⚠️ 등록 전 취소/환불 불가 안내
• 💳 잔액 부족 시 입금 계좌 자동 안내
• 📝 등록 즉시 소유 도메인으로 자동 등록
• 🔒 WHOIS Guard 자동 적용 (개인정보 보호)

등록자 정보:

• 현재: 서비스 기본 정보로 등록 (WHOIS Guard 적용)
• 추후: 사용자 본인 정보로 등록 옵션 추가 예정

도메인 추천

AI가 키워드를 기반으로 창의적인 도메인 이름을 생성하고, 가용성을 자동 확인하여 등록 가능한 도메인만 제안합니다.

사용자: "커피숍 도메인 추천해줘"

봇: 🎯 커피숍 관련 도메인:

✅ 등록 가능:
1. coffeenest.com - 15,000원/년
2. brewlab.io - 45,000원/년
3. beanspot.co - 32,000원/년
4. roasthub.net - 18,000원/년

❌ 이미 등록됨:
- coffee.com
- brew.io
- bean.com

💎 프리미엄 도메인:
- coffeehouse.com (별도 문의)

등록하시려면 번호나 도메인명을 말씀해주세요.

특징:

• 🎨 창의적 이름: 트렌디한 접미사 (hub, lab, spot, nest, base, cloud, stack, flow)
• 🔍 자동 가용성 확인: 15개 아이디어 생성 후 일괄 확인
• 💰 가격 표시: 등록 가능한 도메인만 원화 가격 안내
• 💎 프리미엄 분류: 일반/프리미엄 도메인 구분 표시

---

프로젝트 구조

telegram-bot-workers/
├── src/
│   ├── index.ts           # 메인 Worker
│   ├── types.ts           # 타입 정의
│   ├── security.ts        # Webhook 보안 검증
│   ├── telegram.ts        # Telegram API 유틸
│   ├── summary-service.ts # 프로필 분석 서비스
│   ├── openai-service.ts  # OpenAI + Function Calling
│   ├── deposit-agent.ts   # 예치금 에이전트 (Assistants API)
│   ├── n8n-service.ts     # n8n 연동 (선택)
│   └── commands.ts        # 봇 명령어 핸들러
├── schema.sql             # D1 스키마
├── wrangler.toml          # Wrangler 설정
├── n8n-workflow-example.json  # n8n 워크플로우 예시
├── package.json
├── tsconfig.json
└── README.md

---

배포 가이드

1. 프로젝트 설정

cd telegram-bot-workers
npm install

2. D1 데이터베이스

현재 설정:

[[d1_databases]]
binding = "DB"
database_name = "telegram-conversations"
database_id = "c285bb5b-888b-405d-b36f-475ae5aed20e"

스키마:

• users - 사용자 정보
• message_buffer - 메시지 임시 저장
• summaries - 프로필 저장
• user_deposits - 예치금 계정
• deposit_transactions - 예치금 거래 내역
• bank_notifications - 은행 입금 알림 (SMS 파싱)

3. Secrets 설정

# Bot Token (BotFather에서 발급)
wrangler secret put BOT_TOKEN

# Webhook Secret
wrangler secret put WEBHOOK_SECRET

# OpenAI API Key (필수)
wrangler secret put OPENAI_API_KEY

# Brave Search API Key
wrangler secret put BRAVE_API_KEY

# Deposit API Secret (namecheap-api 연동용)
wrangler secret put DEPOSIT_API_SECRET

# namecheap-api 래퍼 인증 키 (도메인 추천용)
wrangler secret put NAMECHEAP_API_KEY

Vault 연동 (선택)

API 키는 HashiCorp Vault에서 중앙 관리됩니다.

# Vault에서 OpenAI API 키 조회
vault kv get secret/openai

# 저장된 정보
# - api_key: OpenAI API 키
# - email: kappa.inouter@gmail.com (계정 관리용)

# Vault에서 키 가져와서 Worker에 설정
OPENAI_KEY=$(vault kv get -field=api_key secret/openai)
echo $OPENAI_KEY | wrangler secret put OPENAI_API_KEY

참고: Vault 서버: https://vault.anvil.it.com

4. 배포

wrangler deploy

5. Webhook 설정

curl https://telegram-summary-bot.kappa-d8e.workers.dev/setup-webhook
curl https://telegram-summary-bot.kappa-d8e.workers.dev/webhook-info

6. CLI 테스트 (선택)

# .env 파일 생성 (최초 1회)
echo 'WEBHOOK_SECRET=...' > .env  # Vault: secret/telegram-bot

# 대화형 모드
npm run chat

# 단일 메시지 모드
npm run chat "안녕"

---

보안 설정

Webhook 보안 검증

검증 항목	설명
Secret Token	X-Telegram-Bot-Api-Secret-Token 헤더 검증
Timing-safe 비교	타이밍 공격 방지
Timestamp	60초 이내 메시지만 처리
Rate Limiting	30req/분/사용자

API 키 관리

키	저장 위치	비고
BOT_TOKEN	Wrangler Secret	BotFather 발급
WEBHOOK_SECRET	Wrangler Secret	자동 생성
OPENAI_API_KEY	Wrangler Secret + Vault	kappa.inouter@gmail.com

Vault 경로: secret/openai @ vault.anvil.it.com

---

봇 명령어

사용자 명령어

명령어	설명
/start	봇 시작, 기능 소개
/help	도움말
/profile	내 프로필 보기
/reset	대화 초기화 (확인 필요)
/reset-confirm	초기화 확인 (실제 삭제)

개발자 명령어 (숨김)

명령어	설명
/context	현재 컨텍스트 상태 (버퍼 수, 프로필 버전)
/stats	대화 통계
/debug	디버그 정보

---

설정값

wrangler.toml:

name = "telegram-summary-bot"
main = "src/index.ts"
compatibility_date = "2024-01-01"

[ai]
binding = "AI"

[vars]
SUMMARY_THRESHOLD = "20"
MAX_SUMMARIES_PER_USER = "3"
N8N_WEBHOOK_URL = "https://n8n.anvil.it.com"
DOMAIN_OWNER_ID = "821596605"
DEPOSIT_AGENT_ID = "asst_XMoVGU7ZwRpUPI6PHGvRNm8E"
DEPOSIT_ADMIN_ID = "821596605"

[[d1_databases]]
binding = "DB"
database_name = "telegram-conversations"
database_id = "c285bb5b-888b-405d-b36f-475ae5aed20e"

---

비용 예측

월간 예상 비용

사용량	D1	OpenAI	Workers	총
1만 메시지	$0	~$0.20	$0	~$0.20
10만 메시지	$0	~$2.00	$0	~$2.00
100만 메시지	$0	~$20.00	~$0.30	~$20.30

GPT-4o-mini: 입력 $0.15/1M, 출력 $0.60/1M 토큰

---

API 엔드포인트

경로	메서드	설명
/	GET	서비스 정보
/health	GET	헬스 체크
/webhook-info	GET	Webhook 상태
/setup-webhook	GET	Webhook 설정
/webhook	POST	Telegram Webhook
/api/bank-notification	POST	입금 알림 API (레거시, Email Routing으로 대체)
/api/deposit/balance	GET	예치금 잔액 조회 (namecheap-api용)
/api/deposit/deduct	POST	예치금 차감 (namecheap-api용)

---

참고

• OpenAI API
• Cloudflare D1
• Cloudflare Workers
• Telegram Bot API
• Context7 API

---

소스 코드

Gitea: https://gitea.anvil.it.com/kaffa/telegram-bot-workers