Telegram 봇 설치 · 사용법 | OpenWebUI 통합 가이드

PHASE 3

💬Telegram 브릿지 설치 (관리자 전용)

🧭설치 순서 (반드시 이 순서대로)

1OpenWebUI + Twilio 전화봇기반 시스템 · API Key 발급

→

2AI 브라우저 에이전트Browser Agent v7 설치

→

3Telegram 봇마지막에 브릿지 연결

⚠️ 설치 순서를 반드시 지켜주세요. OpenWebUI를 먼저 설치해 API Key를 발급한 뒤, AI 브라우저 에이전트를 설치하고, Telegram 봇은 가장 마지막에 설치합니다. 앞 단계의 결과(API Key·실행 중인 서비스)가 다음 단계 설치에 필요하므로 순서가 바뀌면 설치가 실패할 수 있습니다.

OpenWebUI의 모든 AI 기능을 Telegram에서 그대로 사용합니다. 스트리밍 응답·예약 알림·웹 대시보드·보안 26항목이 포함됩니다.

설치 스크립트 다운로드 + 실행 (원클릭)

wget https://YOUR-HOST/OpenWebUI/setup-telegram-bridge-calendar.sh && \
chmod +x setup-telegram-bridge-calendar.sh && \
./setup-telegram-bridge-calendar.sh

설치 중 입력값 안내

순서	항목	입력 예시	비고
①	Telegram Bot Token	`123456789:ABCdef...`	BotFather에서 발급
②	OpenWebUI API Key	`sk-xxxxx...`	1단계 OpenWebUI에서 발급한 키
③	관리자 User ID	`123456789`	필수 — 미입력 시 진행 불가
④	관리자 PIN (선택)	`임의 6자리`	Enter = 비활성화 · 텔레그램 전용 (전화 봇 PIN과 무관)
⑤	서버 도메인	`https://yourdomain.com`	Enter = Polling 모드

관리자 User ID는 필수입니다. Telegram에서 @userinfobot에게 아무 메시지를 보내면 User ID를 알 수 있습니다. 비관리자는 모든 접근이 차단됩니다.

설치 완료 확인

cd ~/telegram-openwebui-bridge && docker compose ps
# telegram-openwebui-bridge → Up (healthy)

# Health Check
curl -s http://localhost:8444/health

설치 후 Telegram에서 봇을 찾아 /start를 보내면 바로 사용할 수 있습니다.

TG · COMMANDS

⌨️Telegram 명령어 전체 목록

봇에서 사용 가능한 명령어 21개입니다. /를 입력하면 자동완성 목록이 표시됩니다.

기본 대화 / 세션

명령어	설명	비고
`/start`	봇 시작 + 환영 메시지	PIN 인증이 있으면 인증 후 사용 가능
`/help`	상세 도움말	—
`/model`	AI 모델 선택 / 전환	인라인 버튼 목록 표시
`/tools`	Tool 개별 ON/OFF	인라인 버튼으로 토글 — 전체 ON/OFF 포함
`/clear`	대화 기록 초기화	—
`/history`	최근 대화 요약	—
`/status`	OpenWebUI 연결 상태	—
`/whoami`	내 정보 / 권한 확인	—
`/lock`	PIN 잠금 (재인증 필요)	공용 기기 사용 후 잠금 권장

관리자 기능

명령어	설명	예시
`/admin`	관리자 패널 — 인라인 버튼 메뉴	세션·차단·Tool·통계·로그를 버튼 하나로
`/users`	활성 세션 목록	User ID · 모델 · 메시지 수 · Tool 수
`/stats`	상세 통계	메시지·파일·차단·Tool 사용 순위
`/logs [n]`	최근 로그 n줄 조회	`/logs 50` — 기본 30, 최대 100
`/block <id> [분]`	사용자 차단	`/block 123456789 30` — 기본 60분
`/unblock <id>`	차단 해제	`/unblock 123456789`
`/adduser <id>`	허용 사용자 추가	재시작 후에도 유지
`/removeuser <id>`	허용 사용자 제거	자기 자신 제거 불가
`/broadcast <메시지>`	전체 공지 발송	모든 활성 세션에 전송
`/emergency`	🚨 비상 차단 모드 ON/OFF	관리자 외 즉시 전체 차단 토글

예약 기능

명령어	설명	예시
`/remind <시간> <내용>`	예약 설정	`/remind 매일 09:00 날씨 알려줘`
`/reminders`	내 예약 목록	ID · 시간 · 내용 표시
`/cancel <ID>`	예약 취소	`/cancel sch_ab12cd`

📅 캘린더 (조회·등록·수정·삭제)

텔레그램에서 캘린더를 조회·등록·수정·삭제할 수 있습니다.

조회: "오늘 일정 알려줘"
등록: "내일 3시 회의 등록해줘, 알림 30분 전"
상세: "12월 25일 2시 치과 등록, 설명은 정기검진, 알림 1시간 전"
🆕 수정: "12월 25일 회의를 오후 5시로 바꿔줘" (알림도 새 시각으로 자동 재예약)
🆕 삭제: "12월 25일 회의 삭제해줘" (걸려 있던 알림도 자동 취소)

텔레그램 브릿지는 OpenWebUI에 등록된 모든 도구를 자동 활성화하므로, 캘린더 도구(메인 스크립트가 자동 등록)가 있고 밸브에 키가 입력돼 있으면 별도 설정 없이 바로 작동합니다.

전제: 메인 스크립트(start-openwebui-hardened-admin-only.sh)로 캘린더 도구를 먼저 설치하고, 채팅에서 키를 한 번 입력해 둬야 합니다.

🔔 알림을 전화·문자로 받으려면

텔레그램으로 등록한 일정도 알림 시각에 관리자에게 전화+문자가 오게 할 수 있습니다. 텔레그램은 채팅 캘린더 도구를 그대로 쓰므로, 채팅 도구 밸브 하나만 설정하면 텔레그램도 자동 적용됩니다.

OpenWebUI → 워크스페이스 → 도구 → "캘린더 (조회·등록·수정·삭제)" → ⚙️ 밸브
TWILIO_BOT_SECRET 에 ~/OpenWebUI/.env 의 API_SECRET 값 입력

이 값을 넣지 않으면 캘린더 기록·화면 알림은 되지만 전화·문자 알림은 건너뜁니다. 봇이 꺼져 있던 사이 지난 알림은 전화가 오지 않습니다(자동 폐기).

TG · DASHBOARD

🖥️Telegram 봇 관리 대시보드

Telegram 봇 전용 관리 대시보드입니다. 브라우저 웹 UI와 Telegram 명령어 두 가지 방법으로 사용합니다.

대시보드 종류 비교

방법	접속 방법	기능 커버리지
웹 UI	SSH 터널 → 브라우저	6개 탭 전체 — 실시간 모니터링
Telegram 명령어	봇에 명령어 입력	90% — 대부분의 기능 즉시 사용 가능

📱 Telegram으로 대시보드 사용 (추천)

/admin을 입력하면 인라인 버튼 메뉴가 표시됩니다.

웹 대시보드 탭	Telegram 명령어	비고
📊 개요	`/admin` · `/stats` · `/status`	15초 자동 갱신 → Telegram에서는 수동
👥 세션	`/users` · `/admin` → 세션 목록 버튼	동일
👤 사용자	`/adduser` · `/removeuser` · `/block` · `/unblock`	동일
🔧 Tool	`/tools` → 개별 ON/OFF 버튼	동일
📋 로그	`/logs [n]` · `/admin` → 최근 로그	자동 새로고침은 웹에서만
📢 공지	`/broadcast <메시지>`	동일

🌐 웹 대시보드 접속 (SSH 터널)

대시보드는 로컬 전용(127.0.0.1:8445)으로 바인딩되어 외부에서 직접 접근할 수 없습니다.
외부에서 접속하려면 SSH 포트 포워딩(터널)을 사용합니다.

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

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

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

http://localhost:8445/dashboard

3단계: 토큰 입력 (팝업)

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

한 번 입력한 토큰은 브라우저에 자동 저장됩니다. Telegram /admin → 웹 대시보드 URL 버튼을 누르면 SSH 터널 명령어와 토큰 앞부분을 Telegram에서 바로 확인할 수 있습니다.

웹 대시보드 탭별 기능

탭	기능
📊 개요	활성 세션·허용 사용자·차단 수·메시지 수·파일 업로드·가동시간 카드 (15초 자동 갱신) + OpenWebUI 연결 상태
👥 세션	활성 세션 목록 (User ID·모델·메시지·Tool·마지막 활동) — 행에서 바로 차단 가능
👤 사용자	허용 사용자 추가/제거 · 차단 목록 관리 · 차단 해제
🔧 Tool	등록된 Tool 목록 · 세션별 사용 현황 · 전체 ON/OFF
📋 로그	줄 수 지정(최대 500) · 10초 자동 새로고침 토글
📢 공지	모든 활성 사용자에게 메시지 전송

TG · STREAMING

⚡스트리밍 응답

AI 답변이 완성되기를 기다리지 않고 글자가 생성되는 즉시 Telegram 메시지에 표시됩니다. 긴 답변도 첫 글자가 1~2초 내에 보입니다.

동작 방식

① 메시지 전송 → 즉시 💭 생각 중... 메시지 표시
② 스트리밍 수신 → 1초마다 메시지가 편집되며 글자가 쌓임 (▌ 커서 표시)
③ 완료 → 플레이스홀더 삭제 후 최종 포맷된 메시지 전송

예시:
💭 생각 중...
인공지능의 역사는 ▌
인공지능의 역사는 1950년대부터 시작됩니다. 앨런 튜링이 ▌
→ (최종 완성 메시지)

설계 제한

항목	값	이유
메시지 편집 간격	1초	Telegram API 분당 20회 편집 제한
최소 변화량	8글자	불필요한 편집 요청 방지
스트리밍 타임아웃	180초	타임아웃 전까지 받은 내용 부분 전달

Multi-Agent(브라우저 에이전트)를 사용하는 경우는 결과를 한 번에 전송합니다. 스트리밍은 일반 OpenWebUI 채팅에만 적용됩니다.

TG · SCHEDULE

⏰예약 기능

정해진 시간에 AI가 직접 질문을 수행하고 결과를 Telegram으로 전송합니다. 단순 알림이 아니라 AI가 그 시점에 실제로 응답합니다.

지원 형식

유형	예약 명령어 예시	설명
N분 후	`/remind 30분 후 회의 준비 알림`	30분 뒤 1회 실행
N시간 후	`/remind 2시간 후 약 먹기`	2시간 뒤 1회 실행
내일 특정 시간	`/remind 내일 오전 9시 날씨 알려줘`	내일 09:00 1회 실행
내일 HH:MM	`/remind 내일 14:00 미팅 준비해줘`	내일 14:00 1회 실행
매일 반복	`/remind 매일 09:00 오늘 날씨 알려줘`	매일 09:00 반복
매주 반복	`/remind 매주 월요일 09:00 주간 업무 정리해줘`	매주 월요일 09:00 반복
매주 (요일 약자)	`/remind 매주 금 18:00 이번 주 마무리 보고`	매주 금요일 18:00 반복

시간 표현 지원

표현	예시
HH:MM	`09:00` · `14:30`
오전/오후 N시	`오전 9시` · `오후 3시`
오전/오후 N시 M분	`오전 8시 30분`
요일 (전체/약자)	`월요일` · `화` · `수요일` · `목` … `일`

예약 관리

목록 확인: /reminders → ID · 시간 · 내용 표시

취소: /cancel sch_ab12cd

알림 수신 예시:

⏰ [예약 알림 — 매일]
📌 오늘 날씨 알려줘

오늘 서울 날씨는 맑음, 최고 23°C
미세먼지 좋음, 자외선 지수 높음...

예약 목록은 ~/telegram-openwebui-bridge/data/schedules.json에 저장되어 봇을 재시작해도 유지됩니다. 스케줄러는 30초마다 목록을 확인합니다.

실용 예약 예시

🌤️

아침 날씨 브리핑

/remind 매일 07:30 오늘 날씨와 미세먼지 알려줘

📰

뉴스 요약

/remind 매일 08:00 오늘 주요 뉴스 5개 요약해줘

📋

주간 업무 정리

/remind 매주 월 09:00 이번 주 할 일 목록 정리해줘

💰

환율 확인

/remind 매일 09:00 오늘 달러 환율 알려줘

🏃

운동 알림

/remind 매일 18:00 오늘 운동 루틴 알려줘

📈

주식 종가

/remind 매주 금 16:00 삼성전자 주가 알려줘

TG · SECURITY

🔒Telegram 봇 보안 (26항목) — 전체 #65~90

기존 18항목에서 8개 추가하여 총 26항목으로 강화되었습니다.

기존 보안 (18항목)

#	항목	설명
1	화이트리스트 접근 제어	허용된 Telegram User ID만 접근 — 비관리자 전면 차단
2	Rate Limiting	분당 30회 제한 + 3회 실패 시 점진적 차단 (10→30→60→120분)
3	Webhook 서명 검증	Telegram Secret Token으로 요청 위조 방지
4	PIN 인증 + 영구 저장	6자리 PIN 인증 · 기기 신뢰 등록 → 재시작 후에도 PIN 불필요
5	입력 길이 제한	4096자 제한 + null byte 제거 + XSS 방어
6	민감정보 로그 마스킹	API Key · Bearer 토큰 · 전화번호 자동 마스킹
7	non-root 컨테이너	UID 1001 botuser · /sbin/nologin 셸
8	cap_drop + read_only	모든 Linux 권한 제거 · 루트 파일시스템 읽기 전용
9	파일 업로드 제한	20MB 상한 · Path Traversal 방어 · 파일명 정규화
10	세션 타임아웃	30분 비활동 시 세션 초기화 · 세션 수 100개 상한
11	Docker Secrets	Bot Token · API Key · Webhook Secret 파일 분리 저장
12	.env chmod 600	소유자만 읽기/쓰기 · 자동 백업 생성
13	Model/Tool ID 검증	정규식 화이트리스트 패턴 + 128자 길이 제한
14	네트워크 격리	Docker 내부 네트워크 · 포트 127.0.0.1 바인딩
15	로그 로테이션	10MB × 3파일 자동 순환
16	Health Check 자동 복구	30초 간격 · Restarting 감지 시 권한 자동 복구
17	허용 사용자 영구 저장	/app/data/allowed_users.json · chmod 600
18	MAX_SESSIONS DoS 방어	세션 100개 초과 시 가장 오래된 세션 자동 제거

신규 보안 8항목

#	항목	설명
19	🆕 Replay Attack 방어	update_id를 deque(10000건)에 캐싱 — 중복 요청 즉시 무시
20	🆕 Prompt Injection 방어	9개 패턴 정규식 감지 ("ignore previous", jailbreak, system 태그 등) → 차단 + 감사 기록
21	🆕 파일 Magic Bytes 검증	업로드 파일 실제 바이트 확인 — 확장자 위조 방지 (PDF·JPEG·PNG·GIF 등 8종)
22	🆕 AI 응답 민감정보 필터링	API Key·JWT·전화번호를 응답 전송 전 자동 마스킹
23	🆕 구조화된 감사 로그	/app/logs/audit.log에 JSON 형식 기록 (timestamp·event·user_id·ok·detail)
24	🆕 비상 차단 모드	/emergency 명령으로 즉시 토글 — 관리자 외 모든 세션 강제 종료
25	🆕 대시보드 Brute-force 방지	토큰 5회 실패 시 해당 IP 15분 잠금 · timing-safe 비교(hmac.compare_digest)
26	🆕 Seccomp 프로파일	Python 봇 허용 syscall 화이트리스트 — 나머지는 SCMP_ACT_ERRNO 차단

TG · USAGE

📱Telegram 봇 기본 사용법

처음 봇을 사용할 때 따라야 하는 단계입니다. 관리자 User ID가 등록된 계정만 접근 가능합니다.

처음 시작하기

1. 봇 찾기 — Telegram 검색창에서 본인이 만든 봇 이름 검색 (BotFather에서 설정한 이름)

2. /start 전송

/start

PIN 인증이 설정돼 있으면 6자리 PIN 입력 요청이 나타납니다.

3. 환영 메시지 확인 — 봇이 현재 모델·Tool 상태를 안내합니다.

4. 바로 대화 시작 — 명령어 없이 일반 문장을 보내면 AI가 답변합니다.

안녕, 뭘 도와줄 수 있어?

필수 초기 설정

설정	명령어	설명
모델 선택	`/model`	사용할 AI 모델 선택 (인라인 버튼)
Tool 활성화	`/tools`	브라우저 에이전트 등 Tool 켜기/끄기
상태 확인	`/status`	OpenWebUI 연결 및 모델 상태 확인
내 정보	`/whoami`	내 User ID · 권한 · 세션 정보 확인

Tool 활성화는 대화 전에 꼭 하세요. /tools를 입력하면 등록된 Tool 목록이 나타나고, 각 버튼을 눌러 개별 ON/OFF 할 수 있습니다. 브라우저 에이전트 Tool이 켜져 있어야 웹 검색·스크린샷 등이 동작합니다.

대화 관리

명령어	설명	사용 시점
`/clear`	대화 기록 초기화	새 주제로 전환할 때
`/history`	최근 대화 요약 보기	이전 대화 내용 확인할 때
`/model`	AI 모델 전환	다른 성격의 AI가 필요할 때
`/lock`	PIN 잠금 (재인증 필요)	공용 기기 잠시 자리 비울 때
`/help`	전체 명령어 도움말	명령어 목록이 필요할 때

TG · AI

🤖AI 대화 활용법

명령어 없이 자연어로 대화합니다. AI가 문맥을 기억하므로 이전 대화를 이어서 질문할 수 있습니다.

기본 대화 예시

💬 일반 질문

오늘 점심 뭐 먹을까?
파이썬으로 피보나치 수열 짜줘
영어 이메일 초안 작성해줘
이 문장 번역해줘: Hello world

📝 문서 작업

이 내용 요약해줘: [텍스트 붙여넣기]
블로그 포스트 작성해줘
회의록 정리해줘
이 코드 버그 찾아줘: [코드]

대화 흐름 예시 (멀티턴)

사용자: 파이썬 데코레이터가 뭐야?
봇: 데코레이터는 함수를 감싸는 함수입니다... (설명)

사용자: 예제 코드도 보여줘 ← 앞 문맥 유지됨
봇: ```python @decorator def func(): ... ```

사용자: @classmethod랑 뭐가 달라? ← 계속 이어짐
봇: @classmethod는...

대화가 길어지면 /clear로 초기화하세요. 세션은 30분 비활동 시 자동 초기화됩니다.

모델별 특성

모델	특징	추천 용도
llama-3.3-70b (기본)	빠르고 균형 잡힌 성능	일상 대화, 번역, 요약
llama-3.1-70b	안정적인 응답	코드 작성, 문서 작업
gemma-2-27b	Google 모델, 정확한 사실	사실 확인, 분석
mixtral-8x7b	다국어 강점	외국어 번역, 다국어 문서

/model 입력 → 인라인 버튼에서 선택하면 즉시 전환됩니다. 모델은 세션에 저장되어 재시작 후에도 유지됩니다.

TG · FILES

📎파일 & 음성 처리

PDF, 이미지, 음성 파일을 Telegram에서 직접 전송하면 AI가 분석합니다.

📄 PDF 분석

방법: PDF 파일을 채팅창에 드래그 앤 드롭 또는 📎 → File 선택

전송 방법	AI 동작
PDF만 전송	자동으로 내용 요약
PDF + 텍스트	텍스트 지시에 따라 분석

예시 질문:
[PDF 전송] 이 계약서에서 중요한 조항 정리해줘
[PDF 전송] 3페이지 내용 번역해줘
[PDF 전송] 요약본 만들어줘

제한: 최대 20MB · PDF·JPEG·PNG·GIF·WEBP·TXT·MD·CSV 지원

🖼️ 이미지 분석

이미지를 전송하면 AI가 내용을 설명하거나 질문에 답합니다.

[이미지 전송] 이 사진에 뭐가 있어?
[이미지 전송] 이 그래프 분석해줘
[이미지 전송] OCR 해줘 — 텍스트 추출
[이미지 전송] 이 오류 메시지 해결법 알려줘

🎤 음성 메시지 (STT)

Telegram 음성 메시지(마이크 버튼)를 보내면 텍스트로 변환 후 AI가 답변합니다.

동작 흐름:
🎤 음성 녹음 전송 → Whisper STT 변환 → AI 응답

활용 예:

상황	활용법
운전 중	손 쓰기 어려울 때 음성으로 질문
긴 문장 입력	타이핑 대신 말로 입력
외국어 발음 확인	말하면 텍스트 + 교정

음성 파일(OGG·MP3·WAV)도 전송 가능합니다. 5분 이상 녹음도 처리됩니다.

TG · TOOLS

🔧Tool 활용 — AI 브라우저 에이전트

Tool을 활성화하면 AI가 인터넷을 검색하거나 웹 페이지를 조작할 수 있습니다. /tools에서 켜고 끌 수 있습니다.

Tool 활성화 방법

/tools

인라인 버튼 목록이 나타납니다. 각 Tool 이름을 눌러 ON/OFF 토글합니다.
🟢 ON → 해당 Tool 사용 가능 | ⚫ OFF → 비활성

Tool은 세션에 저장됩니다. /clear로 대화를 초기화해도 Tool 설정은 유지됩니다.

🌐 웹 검색 · 브라우저 조작

요청 예시	동작
`오늘 날씨 알려줘`	네이버 날씨 검색 → 요약 전달
`삼성전자 주가 알려줘`	네이버 증권 검색 → 현재가·등락률
`오늘 주요 뉴스 5개 요약해줘`	네이버 뉴스 검색 → 헤드라인 요약
`달러 환율 알려줘`	실시간 환율 검색 → 답변
`이 URL 내용 요약해줘: https://...`	페이지 접속 → 내용 요약
`네이버 쇼핑에서 아이폰 최저가 찾아줘`	쇼핑 검색 → 최저가 비교

📚 위키피디아 검색 (백과사전)

요청 예시	검색 순서
`양자컴퓨터가 뭔지 설명해줘`	위키(한국어) → 위키(영어) → 네이버
`나폴레옹의 역사 알려줘`	위키(한국어) → 위키(영어) → 네이버
`상대성이론 쉽게 설명해줘`	위키(한국어) → 위키(영어) → 네이버

질문이 역사·개념·정의·인물을 묻는 경우 위키피디아를 우선 검색합니다. 날씨·주가·뉴스 같은 실시간 정보는 네이버를 우선 검색합니다.

📸 스크린샷 캡처

https://example.com 스크린샷 찍어줘
이 사이트 캡처해줘: https://...

AI가 해당 URL에 접속해서 JPEG 이미지로 캡처 후 전달합니다. 전체 페이지 캡처해줘라고 하면 스크롤이 있는 긴 페이지도 전체 캡처합니다.

🗺️ 지도 검색

강남역 맛집 찾아줘
서울시청 근처 카페 알려줘
카카오맵에서 홍대 술집 검색해줘

네이버지도(기본) 또는 카카오맵으로 검색해서 이름·주소·별점·영업시간을 알려줍니다.

📊 파일 다운로드 · Excel 저장

요청 예시	동작
`이 PDF 다운로드해줘: https://...`	~/ai-share 폴더에 저장
`코스피 상위 10종목 엑셀로 저장해줘`	웹 검색 → xlsx 파일로 저장
`검색 결과를 CSV로 내보내줘`	테이블 → csv 파일로 저장

🔔 가격·재고 모니터링

특정 상품이나 지표를 주기적으로 확인하고 목표 값이 되면 알림을 보냅니다.

이 상품 5만원 되면 알려줘: https://...
재고 생기면 알림 줘: https://...
환율 1200원 되면 알려줘

check_monitors() → 현재 모니터링 목록 확인

모니터링 목록은 서버에 저장됩니다. 봇 재시작 후에도 유지됩니다.

TG · ADMIN

👑관리자 기능 사용법

관리자로 등록된 Telegram 계정만 사용 가능합니다. /admin을 입력하면 인라인 버튼 메뉴가 표시됩니다.

/admin 패널

/admin

버튼 메뉴가 나타납니다:

버튼	기능
📊 현황	활성 세션 수·메시지 수·가동시간 요약
👥 세션 목록	현재 접속 중인 사용자 목록
🚫 차단 목록	차단된 사용자 목록 + 해제 버튼
🔧 Tool 전체 ON	모든 사용자 Tool 일괄 활성화
🔧 Tool 전체 OFF	모든 사용자 Tool 일괄 비활성화
📋 최근 로그	최근 로그 20줄 조회
🖥️ 웹 대시보드	SSH 터널 접속 방법 안내

사용자 관리

명령어	예시	설명
`/adduser <id>`	`/adduser 123456789`	허용 사용자 추가 (재시작 후에도 유지)
`/removeuser <id>`	`/removeuser 123456789`	허용 사용자 제거
`/block <id> [분]`	`/block 123456789 60`	지정 시간(분) 동안 차단 (기본 60분)
`/unblock <id>`	`/unblock 123456789`	차단 즉시 해제
`/users`	—	활성 세션 목록 (ID·모델·메시지 수)

User ID 확인 방법: Telegram에서 @userinfobot에게 메시지를 보내면 User ID를 알 수 있습니다.

공지 & 로그

📢 전체 공지 보내기

/broadcast 서버 점검 예정입니다

현재 활성 세션의 모든 사용자에게 메시지를 전송합니다.

📋 로그 조회

/logs — 최근 30줄
/logs 50 — 최근 50줄
/logs 100 — 최근 100줄 (최대)

통계 & 상태 확인

/stats — 상세 통계 (메시지·파일·차단·Tool 사용 현황)
/status — OpenWebUI 연결 상태 + 모델 목록

출력 예시:

📊 봇 통계
총 메시지: 1,234
파일 업로드: 56
차단된 사용자: 3
가동 시간: 7일 3시간
Tool 사용 TOP: browse_web(234) search_web(123)

🚨 비상 차단 모드

/emergency — 비상 차단 모드 즉시 ON/OFF

ON 시: 관리자 외 모든 사용자의 메시지가 즉시 차단됩니다.
OFF 시: 다시 정상 운영으로 복귀합니다.

해킹 의심, 비정상 트래픽, 긴급 점검 시 사용합니다.

TG · TIPS

💡실용 팁 & FAQ

⚡ 자주 쓰는 패턴 모음

상황	입력 예시
빠른 번역	`번역: I'll be there in 5 minutes`
코드 리뷰	`이 코드 리뷰해줘: [코드 붙여넣기]`
긴 문서 요약	`요약: [텍스트 붙여넣기]`
아이디어 브레인스토밍	`앱 이름 10개 추천해줘: 헬스케어 앱`
이메일 작성	`미팅 요청 영어 이메일 써줘`
계산 · 환산	`100달러가 지금 원화로 얼마야?`

📅 예약 활용 예시

예약 명령어	효과
`/remind 매일 07:30 오늘 날씨 알려줘`	매일 아침 날씨 브리핑
`/remind 매일 09:00 오늘 뉴스 5개 요약해줘`	매일 아침 뉴스 요약
`/remind 매주 월 09:00 이번 주 할 일 정리해줘`	주간 업무 플래너
`/remind 30분 후 회의 준비 알림`	30분 후 1회 알림
`/remind 매일 오후 6시 오늘 업무 회고해줘`	매일 저녁 회고

❓ FAQ

Q. 봇이 응답이 없어요
/status로 OpenWebUI 연결을 확인하세요. 연결 실패면 서버에서 docker ps로 컨테이너 상태를 확인합니다.

Q. "권한이 없습니다" 오류가 나와요
본인의 Telegram User ID가 관리자 목록에 없는 겁니다. 서버에서 grep ADMIN ~/telegram-openwebui-bridge/.env로 등록된 ID를 확인하세요.

Q. 웹 검색이 안 돼요
/tools에서 브라우저 에이전트 Tool이 켜져 있는지 확인하세요. browser-agent 컨테이너도 실행 중인지 확인합니다: docker ps | grep browser

Q. 답변이 너무 느려요
브라우저 에이전트 Tool을 사용하는 경우 웹 크롤링 시간이 추가됩니다 (평균 10~30초). Tool을 끄면 순수 AI 답변만 나옵니다 (1~3초).

Q. 세션이 자주 초기화돼요
30분 비활동 시 세션이 자동 초기화됩니다. /history로 이전 대화 내용을 확인할 수 있습니다.

Q. PIN을 잊어버렸어요
서버에서 grep ADMIN_PIN ~/telegram-openwebui-bridge/.env로 확인하거나, PIN 없이 재설치하세요.

🔑 유용한 서버 명령어

# 봇 상태 확인
docker ps | grep telegram

# 실시간 로그 보기
docker logs telegram-openwebui-bridge -f --tail=50

# 봇 재시작
cd ~/telegram-openwebui-bridge && docker compose restart

# 봇 완전 중지
cd ~/telegram-openwebui-bridge && docker compose down

# 관리자 User ID 확인
grep ADMIN ~/telegram-openwebui-bridge/.env

# 예약 목록 확인 (서버에서)
cat ~/telegram-openwebui-bridge/data/schedules.json | python3 -m json.tool

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