kvyb/opentulpa

채팅을 통해 브리핑하고, 장비를 갖추고, 업무를 위임할 수 있는 셀프 호스팅(Self-hosted) 디지털 AI 에이전트 및 직원입니다.

지속적인 메모리 (Persistent memory), 내구성 있는 워크플로우 상태 (Durable workflow state), 그리고 네이티브 Telegram 및 Instagram 편지함 처리 기능을 제공합니다. 귀하의 인프라에서 실행됩니다.

빠른 시작 (Quick Start) ·
위임 (Delegate) ·
작동 방식 (How It Works) ·
배포 (Deploy) ·
쿡북 (Cookbook)

OpenAI 호환 제공업체를 대상으로 합니다 · Composio를 통한 앱 통합 · 외부 데이터베이스 불필요

OpenTulpa는 반복되는 업무를 위해 구축된 **셀프 호스팅 에이전트 런타임 (Self-hosted agent runtime)**입니다. 채팅을 통해 브리핑(목표, 도구, 자료, 에스컬레이션 규칙)을 하면 세션이 바뀌어도 계속해서 작업을 수행합니다: 기술을 저장하고, 예약된 루틴을 실행하며, Telegram 및 Instagram에서 들어오는 고객 DM을 처리하고, 그 결과를 귀하의 시스템에 다시 기록합니다.

첫날에는 개인 운영자(Personal operator)로서 작동하며, 업무가 반복되는 순간 내구성 있는 워크플로우 직원(Workflow employee)이 됩니다. 대부분의 "AI 에이전트"는 세션 사이에 업무 내용을 잊어버립니다. OpenTulpa는 그 반대로 설계되었습니다: 한 번만 브리핑하면, 귀하가 소유하고 검사할 수 있는 런타임에서 계속해서 작업을 수행합니다.

일반적인 에이전트 앱	OpenTulpa
컨텍스트 (Context)	세션 제한적 (Session-bound)
설정 (Setup)	매번 프롬프트 입력
...

Telegram에서 본인의 에이전트로부터 답변을 받기 위한 최소 요구 사항:

• @BotFather로부터 받은 Telegram 봇 토큰
• OpenAI 호환 API 키
• bash 및 curl이 설치된 macOS 또는 Linux

git clone https://github.com/kvyb/opentulpa.git
cd opentulpa
./start.sh

이 스크립트는 Python 3.12와 함께 uv를 사용하며, 누락된 필수 값을 요청하고, 앱을 시작하고, Cloudflare 터널을 열고, Telegram 웹훅(Webhook)을 동기화합니다. 그 다음 Telegram에서 봇에게 메시지를 보내세요.

Composio는 첫 실행 시 선택 사항입니다. Google Sheets, Gmail, Slack, Instagram 또는 기타 앱 커넥터가 필요한 경우 나중에 추가하세요.

누락된 경우 부트스트랩 (Bootstraps) (Astral의 설치 프로그램을 통해) → uv ~/.local/bin/uv

Python 의존성 동기화 (Syncs Python deps) uv sync와 함께 (Python 3.12) → 프로젝트 .venv/

Chromium 설치 Playwright를 통해 → ~/.cache/ms-playwright/

(--no-browser-use 옵션으로 건너뛰기 가능)

설치 누락된 경우 Telegram 터널을 위해 설치 → Homebrew (macOS) 또는 cloudflared .deb (Linux) (sudo dpkg를 통해 설치) (--no-cloudflared 옵션으로 건너뛰기 가능)

생성 .env.example로부터 .env를 생성하며, 누락된 값에 대해 입력을 요청함

앱 실행 127.0.0.1:8000에서 실행하며, Cloudflare 터널을 열고 Telegram을 웹훅 (webhook)으로 연결함

sudo는 Linux에서 cloudflared .deb를 설치할 때만 사용되며, Python 의존성 (deps)에는 절대 사용되지 않습니다. 삭제하려면: 리포지토리를 삭제하고, Playwright의 브라우저 캐시를 비우며, 패키지 관리자를 통해 cloudflared를 제거하세요.

Docker 또는 Railway를 선호하시나요? 배포 (Deployment) 섹션을 참조하세요.

연구 (Research) 주제, 파일 및 링크를 조사하고 인용을 포함한 보고서와 요약본을 생성합니다.
작성, 실행 및 디버깅 (Write, execute, and debug) 샌드박스 (sandboxed) 작업 공간에서 Python/shell 스크립트를 작성, 실행 및 디버깅하며, 실패 시 자동으로 재시도합니다.
모니터링 (Monitor) 대시보드, 경쟁사, 편지함 또는 에러 신호를 모니터링하며, 예외 (exceptions) 상황 발생 시에만 알림을 보냅니다.
예약된 루틴 (Scheduled routines) 당신이 잠든 동안 실행됩니다. 예를 들어, 오전 7시에 대시보드를 스크랩하고 밤사이 발생한 에러를 요약하여 상위 3개를 DM으로 보내주는 브리핑 기능이 있습니다.
기억 (Remember) 단일 채팅 내에서뿐만 아니라, 세션 전반에 걸쳐 선호도, 결정 사항 및 프로젝트 문맥 (context)을 기억합니다.

자격 확인 (Qualify) Telegram Business 또는 Instagram에서 인바운드 리드 (inbound leads)의 자격을 확인합니다.
답변 (Answer) 신뢰할 수 있는 자료만을 바탕으로 가격 및 서비스 질문에 답변합니다.
수집 (Collect) 여러 메시지에 걸쳐 예약 또는 접수 필드 (fields)를 수집하며, 오타나 순서 변경을 허용합니다.
예약, 업데이트 또는 취소 (Book, update, or cancel) 허용된 수정 시간 내에 기록을 처리하며, Google Sheets, Calendar 또는 Composio와 연결된 모든 시스템에 기록합니다.
에스컬레이션 (Escalate) 워크플로 (workflow) 범위를 벗어나는 모든 사항은 추측하는 대신 당신에게 전달합니다.

최상의 워크플로는 좁고 운영 중심적입니다.

업무, 도구, 자료, 필수 필드 및 에스컬레이션 경계를 명확하게 정의할수록, 결과물은 더욱 직원(employee)과 같아집니다.

채팅에 붙여넣는 예시 브리프(brief):
"내 세차장으로 들어오는 Telegram Business 메시지를 처리해줘. 첨부된 시트에서 가격 정보를 답변하고, 이름 / 전화번호 / 차량 / 날짜 / 시간을 수집한 뒤, 완료된 예약은 이 Google Sheet에 기록해줘. 이 워크플로우(workflow)를 벗어나는 모든 내용은 나에게 전달해줘. 활성화하기 전에 워크플로우를 확인해줘."

프롬프트가 나타나면 이를 설정하거나, .env 파일에 추가하세요.

:

OPENAI_COMPATIBLE_API_KEY=...
TELEGRAM_BOT_TOKEN=...
TELEGRAM_ALLOWED_USERNAMES=your_handle
...

배포된 웹/API 사용 시 Telegram은 선택 사항입니다. Railway/대시보드 배포는 OPENTULPA_WEB_TOKEN, OPENAI_COMPATIBLE_API_KEY, 그리고 OPENTULPA_DATA_ROOT만으로 시작할 수 있습니다. Telegram 채팅을 활성화할 때 나중에 Telegram 환경 변수(env vars)를 추가하세요.

범용 우선 대시보드 배포의 경우, OPENTULPA_OWNER_CUSTOMER_ID를 사용하면 허용된 단일 Telegram 사용자 이름으로부터 오는 첫 번째 메시지가 해당 사용자의 숫자형 Telegram ID를 범용 소유자(generic owner) 범위에 바인딩(bind)합니다.

Composio 사용을 강력히 권장합니다. 이를 통해 커스텀 통합 코드를 작성하지 않고도 Google Workspace, Slack, Notion, Linear, HubSpot, Gmail, Instagram 등의 앱 커넥터(app connectors)를 사용할 수 있습니다.

브라우저 작업이 많은 경우에는 Browser Use Cloud를 권장합니다. BROWSER_USE_API_KEY를 사용하면 OpenTulpa가 여전히 브라우저 워커 루프(browser worker loop)를 제어하지만, 실시간 소유자 핸드오프(handoff) URL, 유지되는 브라우저 프로필, 프록시(proxying) 및 관리형 브라우저 인프라를 위해 Browser Use Cloud에서 호스팅되는 세션에서 실행됩니다.

그 다음 Telegram에서 봇에게 메시지를 보내세요. 상태 확인(Health check): http://127.0.0.1:8000/healthz.

OpenTulpa는 OpenAI 호환 프록시, OpenRouter, Groq, 로컬 vLLM 및 유사한 런타임(runtimes)과 같은 OpenAI 호환 제공업체를 대상으로 합니다. 특정 모델, 멀티모달(multimodal) 및 도구 호출(tool-calling) 동작은 선택한 제공업체와 모델에 따라 달라집니다. 기본값은 opentulpa.config.yaml에 정의되어 있습니다.

수신 메시지 또는 이벤트
|
지속 가능한 컨텍스트(durable context) 로드: 워크플로우 상태, 파일, 메모리, 체크포인트
...

핵심 구성 요소: 웹훅(webhooks)을 위한 FastAPI, 오케스트레이션(orchestration)을 위한 LangGraph, 체크포인트(checkpoints) 및 워크플로우 상태(workflow state)를 위한 SQLite, 메모리(memory)를 위한 Mem0 + embedded Qdrant, 서드파티 커넥터(third-party connectors)를 위한 Composio, 그리고 브라우저 자동화(browser automation)를 위한 Playwright. 별도의 외부 데이터베이스는 필요하지 않습니다.

런타임(runtime)은 모델과 도구(tools)를 중심으로 모듈화되어 있습니다. OpenAI 호환 모델 제공자(model provider)를 가져오거나, Composio 기반의 커넥터를 사용하거나, 워크플로우에서 커스텀 액션(custom actions)이 필요한 곳에 직접 LangGraph 도구 정의를 추가할 수 있습니다.

설계 단계부터 검사 가능하도록 구축되었습니다. 직원이 수행하는 모든 작업은 .opentulpa/ 디렉토리 아래에 저장됩니다.

(.opentulpa/ 내에는 체크포인트(checkpoints), 컨텍스트(context), 로그(logs), 데이터베이스(databases), 지식 팩(knowledge packs)이 포함되며, tulpa_stuff/ 내에는 생성된 아티팩트(artifacts)가 저장됩니다.) 이를 백업하거나, 볼륨(volume)으로 마운트하거나, 직접 읽을 수 있습니다. 항상 무엇이 일어나고 있는지 알 수 있습니다.

문서	읽어야 하는 이유
아키텍처 (Architecture)	런타임 레이아웃(runtime layout), 요청 흐름(request flows), 안전 제어(safety controls), 확장 지점(extension points)
...
설명을 반복하는 것을 멈추고, 위임(delegating)을 시작하세요.

당신의 첫 번째 셀프 호스팅(self-hosted) 디지털 직원을 실행해 보세요.

MIT 라이선스