OpenWebUI + Twilio AI 전화비서 + AI 브라우저 에이전트 + Telegram 통합 설치 가이드

보내기:
👤 홍길동에게 "회의 참석 부탁드립니다" 문자 보내줘
👤 010-1234-5678로 "내일 3시에 만나요" 문자 보내줘

답장 자동 전달: 상대방이 답장하면 Telegram으로 자동 전달됩니다.

제한: 1600자 이내, 8개국 국가코드만 허용 (프리미엄 번호 차단)

전화 예약:
👤 내일 오후 3시에 김철수에게 안부 전화 예약해줘
👤 매주 월요일 10시에 김철수에게 전화 예약해줘

SMS 예약:
👤 내일 아침 9시에 홍길동에게 "회의 참석 부탁" 문자 예약해줘

예약 관리:
👤 예약 목록 보여줘
👤 예약 삭제해줘
👤 예약 일시정지해줘

반복 옵션: 매일, 매주, 매월 반복 예약 가능
놓친 예약: 👤 놓친 예약 확인해줘 — 서버 중단 등으로 실행 못한 예약 조회

기본값은 OFF입니다. 채팅에서 켜면 됩니다.

녹음 ON/OFF: 👤 통화 녹음 켜줘 / 👤 통화 녹음 꺼줘
PDF ON/OFF: 👤 PDF 보고서 켜줘 / 👤 PDF 보고서 꺼줘

녹음 동작: 법적 고지 멘트(4개국어) → 통화 녹음 → MP3 저장 → Twilio 원본 삭제 → Telegram 알림
PDF 동작: 통화 종료 3초 후 → 대화 전문 + AI 요약 + 통화 시간 포함 PDF 자동 생성

파일 위치: 녹음 ~/OpenWebUI/twilio-bot/data/recordings/ | PDF ~/OpenWebUI/twilio-bot/data/reports/

.env 기본값 변경 (영구): ENABLE_CALL_RECORDING=true / ENABLE_PDF_REPORT=true

안부전화 후 결과를 관리자가 아닌 다른 연락처에게 전화+문자로 보고할 수 있습니다.

사용법:
👤 김철수에게 전화하고 홍길동에게 결과 보고해줘
👤 김철수에게 안부 확인하고 나한테 알려줘
👤 김철수에게 회의 참석 여부 확인하고 박영희에게 보고해줘

보고 방식 (자동):
① 통화 종료 35초 후 → 보고 대상에게 음성 전화로 결과 요약 전달
② 통화 종료 40초 후 → 보고 대상에게 SMS 문자로 결과 요약 전달
③ 동시에 Telegram으로 관리자에게 항상 알림 (보고 대상과 무관)

※ "나한테 알려줘"라고 하면 관리자 본인 번호로 음성+SMS가 옵니다.
※ 다른 사람을 지정하면 음성+SMS는 그 사람에게, Telegram 알림은 관리자에게 옵니다.

AI의 성격, 말투, 대화 규칙, 타이밍을 수정하려면 ai_config.py 파일 하나만 편집합니다.

복사# ai_config.py 편집
nano ~/OpenWebUI/twilio-bot/ai_config.py

# 수정 후 적용 (재시작)
cd ~/OpenWebUI && docker compose restart twilio-bot

통화 중 AI가 말하는 도중 상대방이 끼어들면, AI가 즉시 멈추고 맞장구친 뒤 새 질문에 집중합니다.

🆕 음성 대기시간 설정 (말이 끝났다고 판단하는 시간)

봇이 말 도중에 성급하게 끊는다면 이 값을 키우세요. 값이 클수록 말을 잠깐 멈추거나 생각해도 안 끊깁니다.

복사# 예: 끼어들기를 덜 민감하게 (소음 환경)
BARGEIN_THRESHOLD = 0.4

# 예: 끼어들기 완전히 끄기
BARGEIN_ENABLED = False

통화 중 0번 키패드를 누르거나 음성으로 "담당자"라고 말하면 관리자(사람) 휴대폰으로 직통 연결됩니다. 각각 독립적으로 켜고 끌 수 있습니다. 조합별 동작:

복사# 예: 0번·음성 모두 끄기 (완전 무인 AI 응대)
OPERATOR_TRANSFER_ENABLED = False
OPERATOR_VOICE_ENABLED    = False

# 예: 음성 키워드에 표현 추가
OPERATOR_VOICE_KEYWORDS = ["담당자", "상담원", "직원", "사장님 바꿔"]

전화번호 국가코드로 언어를 자동 감지합니다.

외부에서 전화가 걸려오면 AI가 응대한 후 자동으로 관리자에게 보고합니다.

동작 흐름:
외부 전화 수신 → AI 응대 → 대화 기록 추적 → 마지막 대화 60초 후 통화 종료 판단 → 자동 보고

보고 내용 (자동):
① SMS 문자 → 관리자 번호로 80자 요약 발송
② Telegram 알림 → 발신자 이름/번호 + AI 요약
③ PDF 보고서 → 대화 전문 + AI 요약 (ENABLE_PDF_REPORT=true 시)
④ 대시보드 기록 → 통화 기록에 자동 저장

보고 예시 (Telegram):
📞 [수신전화 보고]
👤 발신자: 김철수 (010-1234-5678)
📊 내용: 환불 절차 문의. AI가 환불 정책을 안내함. 추가 서류 필요.

※ 관리자 전화는 보고 대상에서 제외됩니다. 외부 번호만 추적합니다.
※ 연락처에 등록된 번호면 이름이 표시되고, 미등록 번호면 "알 수 없음 + 전화번호"로 표시됩니다.

스팸이나 악의적인 전화번호를 차단할 수 있습니다.

채팅에서:
👤 010-9999-8888 차단해줘
👤 차단 번호 목록 보여줘

API로:

복사curl -X POST http://localhost:5000/block \
     -H "X-API-Secret: $(cat ~/OpenWebUI/secrets/api_secret)" \
     -H "Content-Type: application/json" \
     -d '{"number": "+821099998888"}'

자동 차단: PIN 3회 실패 시 해당 번호가 자동으로 시간제 잠금됩니다.

Telegram 채팅에서도 OpenWebUI와 동일한 전화 기능을 사용할 수 있습니다.

👤 김철수에게 전화해줘
👤 홍길동에게 "회의 참석 부탁" 문자 보내줘
👤 내일 3시에 김철수에게 전화 예약해줘
👤 통화 녹음 켜줘
👤 연락처 보여줘

※ Telegram 브릿지에서 Tool이 활성화되어 있어야 합니다.

설치 시 자동 생성되는 ~/OpenWebUI/.env 파일의 주요 설정값입니다.

복사# .env 파일 확인
cat ~/OpenWebUI/.env

# 값 수정 후 적용
nano ~/OpenWebUI/.env
cd ~/OpenWebUI && docker compose restart twilio-bot

안부전화(발신)는 기본 4분(240초)에 강제 종료됩니다. 변경하려면 숫자 3개만 수정합니다.

복사# 컨테이너 안 파일 수정 (예: 4분 → 6분)
docker exec -it twilio-bot sh -c "
  sed -i 's/time_limit=240/time_limit=360/' /app/twilio_bot.py
  sed -i 's/elapsed >= 240/elapsed >= 360/' /app/twilio_bot.py
  sed -i 's/elapsed >= 210/elapsed >= 330/' /app/twilio_bot.py
"

# 재시작
cd ~/OpenWebUI && docker compose restart twilio-bot

채팅에서 사진, 동영상, 음성 파일을 업로드하고, 저장된 파일을 클릭해서 브라우저로 바로 볼 수 있습니다. 통화 녹음(MP3)과 PDF 보고서도 클릭해서 재생/열기가 가능합니다.

파일 업로드 (브라우저 드래그앤드롭):
브라우저에서 http://localhost:8000/upload 접속 → 파일을 드래그앤드롭으로 업로드
폴더 지정 가능 (예: photos/홍길동) · 파일 크기 제한 없음 · 업로드 완료 시 클릭하면 바로 열림

파일 목록 조회 (채팅에서):
👤 미디어 파일 보여줘 → 전체 목록
👤 녹음 파일 보여줘 → 통화 녹음 목록 (클릭하면 재생)
👤 PDF 보고서 보여줘 → 보고서 목록 (클릭하면 열림)

폴더별 조회:
👤 홍길동 사진 보여줘 → photos/홍길동 폴더 조회

지원 형식:
저장 위치: ~/ai-share/ (터미널에서도 직접 접근 가능)
녹음 파일: ~/OpenWebUI/twilio-bot/data/recordings/ (읽기전용)
PDF 보고서: ~/OpenWebUI/twilio-bot/data/reports/ (읽기전용)

※ 🔧 미디어 관리 Tool이 활성화되어 있어야 합니다.

개요

OpenWebUI 내장 캘린더(0.9.0 이상)의 일정을, 채팅·전화·텔레그램·브라우저 에이전트에서 모두 조회하고 새로 등록할 수 있습니다. 캘린더 도구는 설치 시 자동 등록됩니다 (9번째 도구 "캘린더 (조회·등록·수정·삭제)").

🔑 키는 한 번만 입력 → 모든 채널이 공유합니다.

🆕 일정 등록 — 말로 캘린더에 넣기

이제 조회뿐 아니라 일정 등록도 됩니다. 날짜·시간·제목은 물론 장소·설명·알림 시간까지 한 번에 기록됩니다.

• 전화: "내일 오후 3시에 회의 등록해줘. 설명은 분기보고 자료 준비. 알림은 30분 전에."
• 채팅/텔레그램: 같은 문장을 채팅으로 입력

항목	말하는 법	예
날짜·시간	"내일 3시", "12월 25일 오후 2시"	필수
제목	"회의", "치과 예약"	필수
장소	"강남역에서", "장소는 3층 회의실"	선택
설명	"설명은 ~~", "내용은 ~~"	선택
알림	"알림 30분 전", "1시간 전에 알림"	선택(기본 10분)

🆕 일정 수정·삭제 — 등록한 일정 바꾸기·지우기

이제 등록한 일정을 수정하거나 삭제할 수 있습니다. 날짜와 제목으로 대상을 찾습니다.

• 수정: "12월 25일 회의를 오후 5시로 바꿔줘" (시간·날짜·제목·장소 중 바꿀 것만 말하면 됩니다)
• 삭제: "12월 25일 회의 삭제해줘"

바꾸는 것	말하는 법
시간	"~회의를 4시로 바꿔줘"
날짜	"~회의를 26일로 옮겨줘"
제목	"~회의 제목을 임원회의로 바꿔줘"
장소	"~회의 장소를 5층으로 바꿔줘"

🔔 알림을 전화·문자로 받기

캘린더에 저장되는 알림은 기본적으로 OpenWebUI 화면 팝업/브라우저 알림으로 옵니다(OpenWebUI를 켜둬야 보임). 여기에 더해, 알림 시각에 관리자에게 실제 전화 + 문자가 오도록 예약할 수 있습니다.

• 일정 등록 시 알림 시간을 말하면(예: "30분 전"), 그 시각에 본인에게 전화와 SMS가 옵니다.
• 전화로 등록하면 바로 작동합니다(추가 설정 불필요).
• 채팅·텔레그램·브라우저로 등록할 때 전화·문자 알림까지 받으려면 아래 밸브 설정이 필요합니다.

도구 밸브	넣는 값
TWILIO_BOT_SECRET	~/OpenWebUI/.env 의 API_SECRET 값
ENABLE_CALL_SMS_REMINDER	켜기(기본) / 끄기

복사# .env 에서 API_SECRET 값 확인 (이 값을 밸브에 붙여넣기)
grep API_SECRET ~/OpenWebUI/.env

설정 순서 (한 번만)

1. OpenWebUI 관리자 로그인 → 설정 → 계정 → API 키 발급
   키 형식: sk-... 권장. eyJ...(JWT 토큰)도 작동하지만 만료가 있어 권장하지 않습니다.
2. 좌측 캘린더(Calendar)에 오늘 일정 등록
3. 워크스페이스 → 도구 → "캘린더 (조회·등록·수정·삭제)" → ⚙️ 밸브 → OPENWEBUI_API_KEY에 키 입력 → 저장
   🔔 전화·문자 알림까지 쓰려면 같은 밸브의 TWILIO_BOT_SECRET에 .env의 API_SECRET 값도 넣어 주세요.
4. 채팅에서 "오늘 일정 알려줘"를 한 번 실행
   ⚠️ 이 단계가 핵심입니다. 이때 키가 공유 폴더에 저장되어 전화 봇도 캘린더를 읽을 수 있게 됩니다.
5. 이제 전화로 "오늘 일정 알려줘"(조회) 또는 "내일 3시 회의 등록해줘"(등록)

채널별 캘린더 접근 방식

채널	접근 방식	키 입력 위치
채팅	"캘린더 (조회·등록·수정·삭제)" 도구 직접 호출 (조회+등록)	그 도구의 밸브
전화	"오늘 일정"/"등록해줘" 키워드 감지 → 공유 키로 조회·등록	(채팅 키 공유받음)
텔레그램	모든 도구 자동 활성화 → 캘린더 자동 포함	(채팅 키 공유받음)
브라우저 에이전트	"AI 브라우저 에이전트" 도구의 메서드 (조회+등록)	그 도구의 밸브에 별도 입력

가짜 일정 방지 (폴백 안전장치)

캘린더 조회가 실패하면 AI가 지어낸 가짜 일정 대신, 원인을 정확히 음성 안내합니다:

• 키 미설정 → "캘린더 키가 설정되지 않았습니다…"
• 연결 실패 → "캘린더 서버에 연결하지 못했습니다…"
• 키 만료(JWT) → "키가 만료되었을 수 있으니 새 키로 다시 설정해 주세요"

복사# docker-compose.yml의 open-webui 서비스 environment에 자동 포함됨:
#   - UVICORN_WORKERS=4

# 수동 확인
docker exec openwebui-open-webui-1 sh -c 'cat /proc/1/environ | tr "\0" "\n" | grep UVICORN_WORKERS'

두 가지 운영 모드

모드	모르는 번호가 전화하면	캘린더·명령
개인용 (admin-only)	즉시 차단	관리자만
고객 상담용 (customer-support)	AI가 일반 상담 응대	관리자만 (고객은 접근 불가)

관리자 번호 vs 연락처 — 헷갈리지 마세요

구분	무엇	방향
관리자 번호	설치 시 입력한 내 번호	봇에게 전화 거는 권한
연락처	채팅에서 저장한 "김철수…"	봇이 전화 거는 대상

🆕 상담원(사람) 연결 — 0번 / 음성

고객 상담 모드에서 외부인이 AI와 대화하다가 사람(관리자)과 통화하고 싶을 때 두 가지 방법이 있습니다:

방법	동작	설정
키패드 0번	0번 누르면 관리자 휴대폰으로 직통 연결	OPERATOR_TRANSFER_ENABLED
음성	"담당자 바꿔줘" 등을 말하면 연결	OPERATOR_VOICE_ENABLED

채팅창에서 자연어로 질문합니다.

👤 통화 기록 보여줘
👤 최근 통화 목록 알려줘
👤 녹음 파일 목록 보여줘
👤 PDF 보고서 목록 보여줘

※ 전화 어시스턴트·통화 녹음 관리·PDF 보고서 관리 Tool이 활성화되어 있어야 합니다.

복사# 단축 명령어 등록 (최초 1회)
echo 'alias dashboard="docker exec twilio-bot curl -s http://127.0.0.1:5000/dashboard > /tmp/dashboard.html && explorer.exe \"$(wslpath -w /tmp/dashboard.html)\""' >> ~/.bashrc
source ~/.bashrc

# 이후부터 이것만 입력
dashboard

대시보드는 토큰 기반 인증을 사용합니다. 잘못된 토큰을 5회 입력하면 해당 IP가 15분 잠금됩니다.

복사# 서버에서 토큰 확인
grep INTERNAL_API_SECRET ~/telegram-openwebui-bridge/.env

한 번 입력 후 브라우저에 자동 저장됩니다. Telegram에서는 /admin → 웹 대시보드 버튼으로 토큰 앞부분을 확인할 수 있습니다.

1단계: PC/Mac 터미널에서 SSH 터널 연결

복사ssh -L 8445:localhost:8445 user@서버IP

2단계: Windows 브라우저에서 접속

복사http://localhost:8445/dashboard

WSL2 환경에서는 127.0.0.1:8445가 WSL2 내부 루프백이라 Windows 브라우저에서 직접 접근이 안 됩니다.
PowerShell(관리자)에서 포트포워딩을 설정하면 SSH 터널 없이 접속 가능합니다.

PowerShell (관리자)에서 실행:

복사# WSL2 IP 확인 후 포트포워딩 설정
$wslIP = (wsl hostname -I).Trim().Split()[0]
netsh interface portproxy add v4tov4 listenport=8445 listenaddress=127.0.0.1 connectport=8445 connectaddress=$wslIP

# 설정 확인
netsh interface portproxy show all

이후 Windows 브라우저에서:

복사http://localhost:8445/dashboard

docker-compose.yml의 포트 바인딩을 0.0.0.0으로 변경하면 Windows 브라우저에서 바로 접속 가능합니다.

복사cd ~/telegram-openwebui-bridge
sed -i 's/127.0.0.1:8445:8445/0.0.0.0:8445:8445/g' docker-compose.yml
docker compose restart

이후 Windows 브라우저에서 http://localhost:8445/dashboard 접속.

대시보드의 대부분 기능은 Telegram 명령어로 대체 가능합니다.