③ 브라우저

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

Ubuntu → OpenWebUI + Browser Agent v7 + Telegram 원클릭 설치 | 보안 91항목 · 스트리밍 · 예약

🤖 OpenWebUI 💬 Telegram 🌐 Browser Agent v7 🔒 보안 91항목
Phase2 44 + Browser Agent 21 + Telegram 봇 26
BROWSER AGENT

🌐AI 브라우저 에이전트 v7 설치

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

AI가 웹 브라우저를 직접 조작하여 검색, 스크린샷, 페이지 분석을 수행합니다. 채팅에서 "네이버 뉴스 검색해줘"로 호출합니다.

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

wget https://YOUR-HOST/OpenWebUI/setup-browser-agent-calendar.sh && \
chmod +x setup-browser-agent-calendar.sh && \
./setup-browser-agent-calendar.sh
v7 사용 시: 네이버 검색 API + Tavily 검색을 적용한 setup-v7.sh를 받으셨다면, 위 대신 bash setup-v7.sh로 실행하세요. v7은 검색을 브라우저 긁기에서 공식 API 호출로 바꾸고, 설치 중 검색 API 키 입력 단계(다음 항목)가 추가됩니다.

🔑 검색 API 키 입력 (네이버 + Tavily) — v7 신규

v7부터 정보 조회는 브라우저로 페이지를 긁는 대신 공식 검색 API를 사용합니다. 설치 도중 검색 API 키 설정 (네이버 + Tavily) 단계가 나오면 아래 세 가지를 순서대로 입력합니다. 모두 선택사항이며, Enter만 누르면 건너뜁니다.

순서입력 항목값 예시발급처
NAVER Client IDv3JvSWxxxxxxxxxxdevelopers.naver.com
NAVER Client Secret●●●●●●●●●●위와 동일 (보기 버튼)
TAVILY API Keytvly-xxxxxxxxxxxxapp.tavily.com
입력하는 값은 화면에 가려져 보이며(비밀번호 방식), 입력 후 마스킹된 형태로 한 번 확인합니다. 셋 다 입력하면 한국어 검색(네이버)·해외 검색(Tavily)이 모두 작동하고, 일부만 입력하면 그쪽만 작동합니다.
══ 검색 API 키 설정 (네이버 + Tavily) ══
ℹ️  정보 조회는 브라우저 긁기 대신 공식 검색 API를 사용합니다.
ℹ️    • 네이버 검색 API: 한국어 검색 (무료/일 25,000건)
ℹ️    • Tavily API: 해외/영어 검색 (무료/월 1,000건)
  🟢 NAVER Client ID: ← 네이버 Client ID 붙여넣기
  🟢 NAVER Client Secret: ← 네이버 Client Secret 붙여넣기
  🔵 TAVILY API Key: ← tvly- 로 시작하는 키 붙여넣기

✅  네이버 검색 API 키 저장됨
✅  Tavily API 키 저장됨
위처럼 ✅ 네이버 검색 API 키 저장됨 / ✅ Tavily API 키 저장됨 메시지가 보이면 키가 ~/OpenWebUI/.env에 안전하게 저장된 것입니다(권한 600으로 잠김). 키를 건너뛴 경우 해당 검색 소스만 비활성화되며, 둘 다 건너뛰면 /search가 비활성화되고 기존 브라우징만 동작합니다.

설치 후 Tool 등록

설치 완료 후 OpenWebUI에서 Tool을 등록해야 합니다:

OpenWebUI → WorkspaceTools → AI 브라우저 에이전트 → ⚙️ Valves → BROWSER_AGENT_API_KEY에 키 입력 → 저장

# API Key 확인
grep BROWSER_AGENT_API_KEY ~/OpenWebUI/.env

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

브라우저 에이전트에도 캘린더 조회 + 등록 기능이 포함되어 있습니다. 같은 "AI 브라우저 에이전트" 도구의 밸브에 캘린더용 키를 추가로 입력합니다:

OpenWebUI → Workspace → Tools → AI 브라우저 에이전트 → ⚙️ ValvesOPENWEBUI_API_KEY에 키 입력 → 저장

⚠️ 주의: BROWSER_AGENT_API_KEYLLM_API_KEY가 아니라 OPENWEBUI_API_KEY 칸입니다. 이름이 비슷한 다른 밸브와 헷갈리지 마세요.
캘린더 조회 밸브: OPENWEBUI_API_KEY(여기 키 입력), OPENWEBUI_URL(그대로), CALENDAR_ADMIN_ONLY(관리자만, 켜둠 권장). 채팅에서 "오늘 일정 알려줘"(조회) / "내일 3시 회의 등록해줘"(등록)로 사용합니다.
🔔 알림을 전화·문자로 받으려면 같은 밸브의 알림 3개도 설정합니다: TWILIO_BOT_SECRET(.envAPI_SECRET 값), TWILIO_BOT_URL(그대로), ENABLE_CALL_SMS_REMINDER(켜기/끄기). 값을 안 넣으면 캘린더 기록·화면 알림만 되고 전화·문자는 건너뜁니다.

사용 예시

👤 네이버 뉴스 검색해줘
👤 https://example.com 페이지 내용 요약해줘
👤 오늘 날씨 검색해줘
👤 이 사이트 스크린샷 찍어줘
👤 검색 결과를 파일로 저장해줘
👤 인공지능의 역사 위키피디아에서 찾아줘
👤 양자컴퓨터가 뭔지 설명해줘

🔍 검색 동작 방식 (v7 업데이트)

v7부터 검색은 브라우저로 페이지를 긁지 않고 공식 검색 API로 처리되어 타임아웃·봇차단 없이 빠르고 안정적입니다. 질문 언어에 따라 자동으로 라우팅됩니다.

질문 유형검색 경로예시
한국어 질의
날씨·주가·뉴스·국내정보
네이버 검색 API → (실패 시) Tavily오늘 날씨, 삼성전자 주가
해외/영어 질의
글로벌·영문 정보
Tavily → (실패 시) 네이버latest AI news, OpenAI
한쪽 키만 입력한 경우, 다른 언어의 질의도 입력된 키 쪽으로 폴백되어 처리됩니다.

특정 URL 읽기는 그대로 브라우징: https://... 주소를 직접 주는 작업(페이지 본문 요약 등)은 검색 API가 아니라 기존 브라우저 에이전트가 처리합니다.

멀티 에이전트: 복잡한 조사 작업(/browse/multi)의 browser 노드도 v7부터 먼저 검색 API를 시도하고, 실패 시에만 브라우징으로 폴백합니다.

📁 파일 접근 (ai-share 폴더)

브라우저 에이전트는 ~/ai-share 폴더를 통해 파일 읽기/쓰기가 가능합니다.

경로: ~/ai-share/ (호스트) ↔ /app/data/ (컨테이너)

👤 검색 결과를 파일로 저장해줘~/ai-share/에 저장됨
👤 ai-share에 있는 파일 읽어줘 → 폴더 내 파일 읽기 가능

🧠 메모리/학습 (브라우저 작업 시 자동 기억)

브라우저 에이전트로 웹 검색/탐색을 할 때 대화 내용에서 사용자 정보를 자동 추출하여 기억합니다. 일반 채팅에서는 저장되지 않습니다.

기억되는 경우 (🔧 브라우저 Tool ON):
👤 부산 맛집 검색해줘 → "부산" 위치 정보 자동 저장
👤 Python 관련 기술 블로그 찾아줘 → "Python 관심" 자동 저장

기억 안 되는 경우 (일반 채팅):
👤 나는 부산에 살아 → 브라우저 작업이 아니므로 저장 안 됨

기억 관리:
👤 내 정보 뭐 기억하고 있어? → 저장된 사용자 정보 확인
👤 내 정보 초기화해줘 → 저장된 정보 삭제

저장 위치: ~/OpenWebUI/browser-agent/data/memory.json
저장 시점: 브라우저 검색/탐색 작업 완료 후 자동 저장

🔑 API 키 수동 갱신 (403 에러 시)

브라우저 에이전트에서 "접근 거부" 또는 403 Forbidden 에러가 나오면 API 키가 Valves에 입력되지 않았거나 불일치하는 것입니다.
# 1. 현재 API 키 확인
grep BROWSER_AGENT_API_KEY ~/OpenWebUI/.env

# 2. 출력된 키를 복사 (= 뒤의 긴 문자열)
# 예: BROWSER_AGENT_API_KEY=61bf5a8e...c806

# 3. OpenWebUI에 입력:
#    Workspace → Tools → AI 브라우저 에이전트
#    → ⚙️ (톱니바퀴) → BROWSER_AGENT_API_KEY
#    → 키 붙여넣기 → 저장

# 4. 키를 새로 생성하려면:
NEW_KEY=$(openssl rand -hex 64)
sed -i "s/BROWSER_AGENT_API_KEY=.*/BROWSER_AGENT_API_KEY=$NEW_KEY/" ~/OpenWebUI/.env
cd ~/OpenWebUI && docker compose restart browser-agent
echo "새 키: $NEW_KEY"
# → 출력된 새 키를 Valves에 다시 입력!
BA · USAGE

🌐AI 브라우저 에이전트 기본 사용법

AI가 실제 브라우저를 열어 웹을 탐색하고 결과를 정리합니다. OpenWebUI 채팅창에서 Tool을 켜고 자연어로 요청하면 됩니다.

Tool 활성화 (필수)

OpenWebUI 채팅창 하단 🔧 Tools 버튼 클릭 → AI 브라우저 에이전트 토글 ON

또는 Telegram에서: /tools → AI 브라우저 에이전트 ON

Tool이 OFF 상태면 AI가 직접 답변만 합니다. 실시간 웹 검색·스크린샷 등은 Tool이 켜져 있어야 동작합니다.

기본 요청 방식

명령어 없이 자연어로 요청합니다. AI가 질문 유형을 파악해 적절한 Tool을 선택합니다.

요청 예시AI 동작소요 시간
오늘 서울 날씨 알려줘네이버 날씨 검색 → 요약5~15초
삼성전자 주가 얼마야?네이버 증권 접속 → 현재가5~15초
https://... 요약해줘URL 접속 → 내용 분석10~30초
강남역 맛집 찾아줘네이버지도 검색 → 목록10~25초
양자컴퓨터가 뭐야?위키피디아 검색 → 설명5~15초
⏱️ 응답 시간: 브라우저 에이전트는 실제로 웹 페이지를 열기 때문에 일반 AI 답변(1~3초)보다 느립니다. 복잡한 작업은 30~60초 소요될 수 있습니다.

응답 스트리밍 (실시간 진행상황)

브라우저 에이전트가 작업하는 동안 실시간으로 진행 상황이 표시됩니다.

OpenWebUI 채팅: 단계별 진행 메시지가 스트리밍으로 표시됩니다.
Telegram: 💭 생각 중... → 처리 중 (단계 1) → (최종 답변) 순서로 갱신됩니다.
BA · ADVANCED

고급 기능

📸 스크린샷 캡처

웹 페이지를 JPEG 이미지로 캡처합니다.

요청 예시동작
https://naver.com 스크린샷 찍어줘화면 영역(1280×900) 캡처
https://naver.com 전체 페이지 캡처해줘스크롤 포함 전체 캡처
이 사이트 지금 화면 보여줘: https://...현재 화면 캡처
캡처된 이미지는 base64 JPEG로 반환됩니다. OpenWebUI 채팅에서 인라인 이미지로 표시됩니다.

📊 파일 다운로드 · Excel/CSV 저장

요청 예시저장 위치
https://... 이 PDF 다운로드해줘~/ai-share/ 폴더
코스피 상위 10종목 주가를 엑셀로 저장해줘~/ai-share/result.xlsx
네이버 쇼핑 검색 결과를 CSV로 저장해줘~/ai-share/result.csv
이 표 데이터를 result.xlsx로 저장해줘~/ai-share/result.xlsx
# 저장된 파일 확인
ls -la ~/ai-share/

🔔 가격·재고 모니터링

특정 웹 페이지의 값을 주기적으로 확인하고, 목표값이 감지되면 알림을 보냅니다.

등록 예시:
https://쇼핑몰.com/product 이 상품 5만원 되면 알려줘
https://쇼핑몰.com/product 재고 생기면 알림 줘
https://finance.yahoo.com 삼성전자 80000원 되면 알려줘

목록 확인:
모니터링 목록 보여줘 또는 check_monitors()

설정 항목설명기본값
확인 주기몇 분마다 확인할지60분
목표값이 값이 페이지에 나타나면 트리거없음(변동만 기록)
모니터링 데이터는 ~/OpenWebUI/browser-agent/data/monitors.json에 저장되어 재시작 후에도 유지됩니다.

🍪 로그인 세션 저장

로그인이 필요한 사이트에서 쿠키를 저장해두면, 다음 요청 시 자동으로 로그인 상태를 재사용합니다.

네이버에 로그인하고 세션 저장해줘 (세션 이름: naver)
naver 세션 불러와서 내 네이버 메일 확인해줘

API 엔드포인트기능
POST /sessions/{name}/save현재 브라우저 세션(쿠키) 저장
GET /sessions/{name}저장된 세션 불러오기
GET /sessions저장된 세션 목록
보안: 세션 파일은 chmod 600으로 보호됩니다. 타인의 접근이 불가합니다.

📦 일괄 처리 (Batch)

여러 URL이나 작업을 한 번에 처리합니다.

이 5개 사이트 전부 요약해줘:
https://site1.com
https://site2.com
https://site3.com

항목
최대 처리 수10개 (한 번에)
처리 방식순차(기본) 또는 병렬
Rate Limit분당 2회 요청

🧠 메모리 시스템

브라우저 작업 중 사용자 정보를 자동으로 학습합니다.

학습 항목예시저장되는 정보
위치"부산 날씨 검색"location: 부산
관심사"Python 튜토리얼 찾기"interests: [Python, 프로그래밍]
선호도"맛집 검색 후 선택"preferences: {음식: 한식}

메모리 관리 명령:
내 기억 뭐가 있어? — 저장된 정보 전체 확인
내 위치 정보 삭제해줘 — 특정 항목 삭제
내 정보 전부 초기화해줘 — 전체 삭제

저장 위치: ~/OpenWebUI/browser-agent/data/memory.json
BA · API

🔌API 레퍼런스

브라우저 에이전트는 REST API로 직접 호출할 수 있습니다. 기본 주소: http://localhost:8001

인증

모든 API 요청에 Authorization 헤더가 필요합니다.
Authorization: Bearer {BROWSER_AGENT_API_KEY}
# API Key 확인
grep BROWSER_AGENT_API_KEY ~/OpenWebUI/.env

전체 엔드포인트 목록

메서드경로기능
GET/health서버 상태 확인
POST/browse단일 브라우저 작업 (기본)
POST/browse/streamSSE 스트리밍 실시간 진행
POST/browse/batch일괄 처리 (최대 10개)
POST/browse/multitab멀티탭 병렬 처리
POST/browse/multiMulti-Agent 처리
POST/screenshot스크린샷 캡처 (base64 JPEG)
GET/history작업 히스토리 (최대 100건)
DELETE/history히스토리 초기화
GET/tasks실행 중인 작업 목록
POST/tasks/{id}/cancel작업 즉시 취소
GET/POST/DELETE/sessions/{name}로그인 세션 관리
GET/POST/DELETE/monitors모니터링 등록·조회·삭제
POST/monitors/{id}/check모니터 즉시 확인
GET/pool/status브라우저 풀 상태
GET/proxy/status프록시 설정 확인
GET/POST/memory사용자 메모리 조회·수정
GET/filesai-share 파일 목록
GET/metrics서버 메트릭

주요 API 사용 예시

# 헬스 체크
curl http://localhost:8001/health

# 브라우저 작업
curl -X POST http://localhost:8001/browse   -H "Authorization: Bearer $KEY"   -H "Content-Type: application/json"   -d '{"task":"오늘 날씨 알려줘"}'

# 스크린샷
curl -X POST http://localhost:8001/screenshot   -H "Authorization: Bearer $KEY"   -H "Content-Type: application/json"   -d '{"url":"https://naver.com","full_page":false}'

# 작업 히스토리
curl http://localhost:8001/history?limit=10   -H "Authorization: Bearer $KEY"

# 모니터링 등록
curl -X POST http://localhost:8001/monitors   -H "Authorization: Bearer $KEY"   -H "Content-Type: application/json"   -d '{"url":"https://...","keyword":"가격","target_value":"50000","interval_minutes":60}'

OpenWebUI Tool 목록 (채팅에서 호출 가능)

Tool 함수설명사용 예시
browse(task, url)일반 웹 작업 (실제 함수명: browse)"네이버 뉴스 검색해줘"
search_naver(keyword)네이버 키워드 검색"파이썬 튜토리얼 검색"
search_naver(keyword)네이버 전용 검색"네이버에서 찾아줘"
search_wikipedia(keyword)위키피디아 검색"위키에서 블랙홀 찾아줘"
take_screenshot(url)스크린샷 캡처"이 사이트 캡처해줘"
search_map(keyword, service)지도 검색"강남역 맛집 찾아줘"
download_file(url)파일 다운로드"이 PDF 저장해줘"
export_to_excel(task, filename)Excel/CSV 저장"결과 엑셀로 저장"
monitor_price(url, keyword)가격·재고 모니터링"5만원 되면 알려줘"
check_monitors()모니터링 목록 조회"모니터링 목록 보여줘"
check_weather(city)날씨 확인"서울 날씨 알려줘"
check_price(product)상품 가격 검색"아이폰 가격 찾아줘"
check_stock(symbol)주가 확인"삼성전자 주가"
check_exchange_rate(currency)환율 확인"달러 환율 알려줘"
check_sports(sport)스포츠 결과"오늘 야구 결과 알려줘"
check_news(keyword)뉴스 검색"AI 관련 뉴스 알려줘"
compare_sites(url1, url2)두 사이트 비교"두 사이트 가격 비교해줘"
open_and_summarize(url)URL 열어서 요약"이 링크 요약해줘"
summarize_youtube(url)유튜브 영상 요약"이 유튜브 요약해줘"
read_file(filename)ai-share 파일 읽기"저장된 파일 읽어줘"
save_file(filename, content)파일 저장"이 내용 파일로 저장해줘"
get_memory()메모리 전체 조회"내 정보 뭐 기억해?"
clear_memory()메모리 전체 초기화"내 정보 전부 삭제해줘"
multi_agent_browse(task)Multi-Agent 복합 작업"복잡한 리서치 작업"
BA · FIX

🔧문제 해결 & 유지보수

자주 발생하는 오류

오류원인해결 방법
403 ForbiddenAPI Key 불일치Valves에서 BROWSER_AGENT_API_KEY 재입력
응답 없음 (60초 이상)복잡한 작업·네트워크 지연더 구체적인 요청으로 재시도
Tool이 보이지 않음Tool 미등록아래 수동 등록 명령어 실행
컨테이너가 재시작됨메모리 부족·Python 오류docker logs browser-agent로 확인
브라우저 실행 실패WSL2 커널 문제PowerShell에서 wsl --update

자주 쓰는 유지보수 명령어

# 상태 확인
docker ps | grep browser-agent
curl http://localhost:8001/health

# 실시간 로그
docker logs browser-agent -f --tail=50

# 재시작
cd ~/OpenWebUI && docker compose restart browser-agent

# Tool 수동 재등록
OWUI_KEY=$(grep "^OPENWEBUI_API_KEY=" ~/OpenWebUI/.env | cut -d= -f2-)
TOOL_FILE="$HOME/OpenWebUI/browser-agent/openwebui_tool.py"
curl -s -X POST http://localhost:3000/api/v1/tools/create   -H "Authorization: Bearer ${OWUI_KEY}"   -H "Content-Type: application/json"   -d "{"id":"ai_browser_agent","name":"AI 브라우저 에이전트",
       "content":$(python3 -c "import json; print(json.dumps(open('$TOOL_FILE').read()))"),
       "meta":{"description":"Browser Use + Groq 기반 AI 브라우저 에이전트"}}"

# 메모리 초기화
rm ~/OpenWebUI/browser-agent/data/memory.json

# ai-share 파일 정리
ls -la ~/ai-share/
rm ~/ai-share/old_file.csv

⚙️ 환경변수 설정 (.env)

변수기본값설명
BROWSER_AGENT_API_KEY자동 생성인증 키 (변경 시 Valves도 재입력)
GROQ_API_KEY필수 입력Multi-Agent LLM 키
MAX_CONCURRENT3동시 브라우저 작업 수
TASK_TIMEOUT180단일 작업 타임아웃(초)
BROWSER_POOL_SIZE0브라우저 풀 크기 (0=비활성)
BROWSER_PROXY빈값프록시 서버 (예: http://user:pass@host:port)
ENABLE_REQUEST_SIGNINGfalseHMAC 요청 서명 활성화
# 환경변수 수정 후 재시작
nano ~/OpenWebUI/.env
cd ~/OpenWebUI && docker compose restart browser-agent