우리가 AI와 상호작용하는 방식은 빠르게 변하고 있습니다. 지금까지의 1~3편이 “질문을 던지면 똑똑하게 글과 문서를 찾아 답해주는 대화형 AI(Chatbot)”에 초점을 맞췄다면, 이번 4편은 “목표를 주면 스스로 판단해 코드를 실행하고, 브라우저를 띄우며, 내 컴퓨터의 프로젝트를 직접 완성하는 실행형 AI(Agent)”로의 도약을 다룹니다.

AI

5 분 소요

SERIES Open WebUI 실무 완벽 가이드 4 / 4 시리즈 전체 보기 →

우리가 AI와 상호작용하는 방식은 빠르게 변하고 있습니다. 지금까지의 1~3편이 “질문을 던지면 똑똑하게 글과 문서를 찾아 답해주는 대화형 AI(Chatbot)”에 초점을 맞췄다면, 이번 4편은 “목표를 주면 스스로 판단해 코드를 실행하고, 브라우저를 띄우며, 내 컴퓨터의 프로젝트를 직접 완성하는 실행형 AI(Agent)”로의 도약을 다룹니다.

Open WebUI 생태계는 이를 지원하기 위해 Native Tool Calling(에이전틱 모드), 격리된 샌드박스 실행 환경인 Open Terminal, 도구 표준인 MCP(Model Context Protocol) 지원, 그리고 로컬 머신 전체를 웹으로 제어하는 Open WebUI Computer (cptr)까지 폭넓은 확장 레이어를 갖추고 있습니다.

시리즈의 대미를 장식하는 이번 편에서는 Open WebUI를 진정한 자립형 에이전트 플랫폼(Autonomous Agent Platform)으로 탈바꿈시키는 핵심 기술을 심층 분석합니다.

1. Native Tool Calling: 진정한 에이전트의 시작

Open WebUI v0.10.0의 가장 중요한 아키텍처 변화는 Native Tool Calling(Agentic Mode)의 기본 활성화입니다.

1
2
3
4
5
6
7
8
9
10

[ 과거: Legacy Prompt Injection ]
User: "오늘 서울 날씨 어때?"
Prompt: "...당신은 [TOOL: weather] 도구가 있습니다. 형식을 맞춰 출력하세요..."
Model: "```call:weather(seoul)```" (텍스트 파싱 오류 잦음, KV 캐시 파괴)

[ 현재: Native Function Calling ]
User: "오늘 서울 날씨 어때?"
API Request: { tools: [ { name: "get_weather", parameters: {...} } ] }
Model API: tool_calls: [{ function: "get_weather", args: { location: "seoul" } }]
Agent Engine: 도구 자동 실행 -> 결과 주입 -> 최종 답변 완성 (연쇄 호출 가능)

1.1 Native 모드의 장점

  1. 자율적 도구 체이닝(Chain of Tools): 사용자가 “웹 검색을 켜라”고 지시하지 않아도, 모델이 스스로 “이 질문은 팩트 확인이 필요하다”고 판단하면 Web Search를 부르고, 메모할 내용이 있으면 Memory 도구를 스스로 호출합니다.
  2. KV 캐시 보존 및 토큰 절약: 프롬프트에 장황한 도구 설명 텍스트를 인젝션하지 않고 API 레벨의 스키마로 전달되므로 캐시 효율이 극대화됩니다.
  3. 내장 시스템 도구 해금: Memory(사용자 선호도 기억), Notes(메모 작성), Knowledge(사내 문서 탐색), Channels(팀 채널 대화) 등의 내장 기능이 네이티브 도구 호출을 통해 유기적으로 엮입니다.

2. Open Terminal: AI에게 격리된 샌드박스 컴퓨터 주기

단순히 텍스트 코드를 보여주는 것을 넘어, “모델이 방금 작성한 파이썬 스크립트를 실제로 실행하고 결과를 시각화하라”는 요구는 실무에서 매우 빈번합니다. 이를 안전하게 구현한 것이 바로 Open Terminal입니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

┌───────────────────────────────────────────────────────────────┐
│                    Open WebUI Chat Interface                  │
│                                                               │
│ User: "매출 CSV 데이터를 분석해서 월별 트렌드 차트를 그려줘"  │
│                                                               │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ Model: Open Terminal 도구 호출                            │ │
│ │ > bash -c "python3 analyze.py"                            │ │
│ └─────────────────────────────┬─────────────────────────────┘ │
│                               │                               │
└───────────────────────────────┼───────────────────────────────┘
                                ▼
┌───────────────────────────────────────────────────────────────┐
│              Sandboxed Docker Container (Open Terminal)       │
│  - Isolated Filesystem (/workspace)                           │
│  - Python 3.11, Pandas, Matplotlib, Node.js runtime           │
│  - Port Preview Server (Local Dev Web Server)                 │
└───────────────────────────────────────────────────────────────┘

2.1 핵심 기능

  • 격리된 샌드박스 실행: 호스트 OS에 직접 명령을 내리는 것이 아니라, Docker로 완벽히 격리된 컨테이너 내부에서 셸과 코드를 실행하므로 보안 위협이 없습니다.
  • 인터랙티브 웹 & 아티팩트 프리뷰: 모델이 HTML/JS 대시보드나 간단한 웹 서비스를 만들면, Open Terminal이 로컬 포트를 열어 대화창 내부에 실시간 인터랙티브 iframe 미리보기를 렌더링해 줍니다.
  • 대화형 데이터 분석: CSV, Excel, SQLite 파일을 컨테이너에 업로드하고 모델이 Pandas와 Seaborn을 돌려 차트 이미지를 대화창에 바로 출력합니다.

3. MCP (Model Context Protocol) 생태계 확장

최근 앤트로픽을 필두로 업계 표준으로 자리잡은 MCP(Model Context Protocol)는 데이터베이스, 사내 API, 파일시스템 등의 외부 도구를 LLM에 표준화된 방식으로 연결하는 프로토콜입니다.

Open WebUI는 공식 프록시 도구인 mcpo (MCP-to-OpenAPI Proxy)를 통해 수많은 외부 MCP 서버를 코드 한 줄 수정 없이 그대로 연결합니다.

1
2
3

[ Postgres MCP ] ──┐
[ GitHub MCP   ] ──┼──> [ mcpo Proxy ] ──(OpenAPI Spec)──> [ Open WebUI Tools ]
[ Slack MCP    ] ──┘

3.1 mcpo를 통한 연동 실습

  1. mcpo 실행: 
    1
2

    # GitHub MCP 서버를 OpenAPI 규격으로 프록시 서빙
npx @open-webui/mcpo --mcp "npx -y @modelcontextprotocol/server-github" --port 8001
  2. Open WebUI에 등록:
    • Settings > Admin > Tools > + (Add Tool)에서 http://localhost:8001/openapi.json 등록
    • 이제 모든 대화창에서 AI가 사내 GitHub Issue를 조회하고, PR을 올리거나, PostgreSQL DB를 직접 쿼리할 수 있게 됩니다.

4. Open WebUI Computer (cptr): 내 컴퓨터를 브라우저로

Open Terminal이 대화 도중 실행되는 “일회성 샌드박스 작업실”이라면, Open WebUI Computer (cptr)는 개발자의 실제 로컬 컴퓨터 전체(실제 파일, 터미널, Git 저장소)를 웹 브라우저 탭으로 옮겨놓은 풀스택 에이전트 하네스입니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

┌──────────────────────────────────────────────────────────────┐
│                    Open WebUI Computer (cptr)                │
├────────────────────────┬─────────────────────────────────────┤
│   Workspace Explorer   │          Agent Terminal & IDE       │
│  - /Users/you/project  │  - Real PTY Shell (Your zsh / PATH) │
│  - Git status & diff   │  - Integrated Code Editor           │
│  - Local Port Previews │  - Approval & Plan Mode             │
└────────────────────────┴─────────────────────────────────────┘
                               ▲
                               │ OpenAI-compatible Gateway API
                               │ (cptr/workspace-name)
┌──────────────────────────────┴───────────────────────────────┐
│                      Open WebUI Main Chat                    │
│ "cptr/my-backend 모델을 선택하여 메인 챗에서 코딩 명령 수행" │
└──────────────────────────────────────────────────────────────┘

4.1 초간단 구동

Python 3.10+ 환경에서 단 한 줄로 구동됩니다.

1

uvx cptr@latest run

브라우저에서 접속하면 내 실제 하드디스크의 폴더를 작업 공간(Workspace)으로 열 수 있으며, 에이전트가 코드를 수정하면 가상 환경이 아닌 내 디스크의 실제 파일이 변경되고 실제 Git 브랜치에 커밋됩니다.

4.2 Open WebUI와의 환상적인 결합

cptr의 강력함은 Open WebUI와의 연동에서 빛을 발합니다.

  • cptr 게이트웨이는 각 작업 공간을 OpenAI 호환 모델(cptr/<workspace-name>) 형태로 외부에 노출합니다.
  • Open WebUI의 Settings > Admin > Connections에 http://localhost:8000을 등록하면, 모델 선택 드롭다운에 내 로컬 프로젝트가 모델로 등장합니다.
  • 즉, 회사 데스크톱이나 홈 서버에 cptr을 띄워두고, 카페나 모바일 폰에서 Open WebUI에 접속해 “우리 백엔드 프로젝트 버그 잡아서 커밋해 줘”라고 명령을 내릴 수 있습니다.

5. 3가지 에이전트 도구 비교 및 활용 가이드

도구 성격 권장 사용 시나리오
Open WebUI (Core) 중앙 제어 플랫폼 팀 협업, 사내 RAG 포털, 다중 모델 라우팅, 사용자 권한 관리
Open Terminal 격리 샌드박스 셸 대화 도중 간단한 파이썬 스크립트 실행, 데이터 분석, 일회성 웹 프리뷰
Open WebUI Computer 호스트 머신 에이전트 실제 대규모 소스코드 개발, Git 브랜치 관리, 모바일 원격 개발 제어

4부작 시리즈를 마치며

지금까지 총 4편에 걸쳐 Open WebUI의 진정한 가치를 탐구했습니다.

  1. 1편 [아키텍처 & 배포]: SQLite의 한계를 넘어 PostgreSQL, Redis, S3로 무중단 고가용성 인프라를 구축했습니다.
  2. 2편 [성능 & 비용 최적화]: Task Model 분리, KV Cache 보존, Context Compaction으로 반응 속도를 극대화하고 API 비용을 최소화했습니다.
  3. 3편 [엔터프라이즈 RAG]: PGVector, Tika/Docling 오프로딩과 가상 파일시스템 탐색(ENABLE_KB_EXEC), 웹 검색으로 환각 없는 사내 지식 허브를 완성했습니다.
  4. 4편 [차세대 에이전트]: Native Tool Calling, Open Terminal 샌드박스, MCP 연동, 그리고 Open WebUI Computer를 결합해 실제 일을 해내는 자립형 AI 에이전트를 완성했습니다.

Open WebUI는 단순한 웹 UI가 아닙니다. 기업과 개인에게 데이터 주권(Sovereign AI)을 보장하면서도, 가장 최신의 LLM 및 에이전트 기술을 자유자재로 오케스트레이션할 수 있는 강력한 오픈소스 AI 운영체제입니다. 본 시리즈가 여러분만의 탄탄한 프라이빗 AI 인프라를 구축하는 데 든든한 길잡이가 되기를 바랍니다.

// reading compass

이 글과 이어지는 경로

시리즈, 카테고리, 태그 겹침, 최신도를 점수화해 가까운 글일수록 중심에 배치합니다.

hover nodes or cards · click a node to pin
Next reads 0

    댓글남기기

    참고

    Wiki

    멱등성(Idempotency), 재시도해도 안전한 API 만들기

    같은 요청을 여러 번 보내도 결과가 한 번 보낸 것과 똑같이 유지되는 성질을 멱등성(idempotency)이라고 한다. 말로만 들으면 당연한 얘기 같은데, 막상 네트워크가 불안정한 환경에서 API를 설계하다 보면 은근히 신경 써야 하는 부분이다. 클라이언트가 응답을 못 받아서 같은...

    1 분 소요