johnson7788/MultiUserClaw

MultiUserClaw – Hermes Agent 기반 다중 테넌트 AI SaaS 플랫폼

무엇인가요

• 동일한 서버에서 여러 고객을 위한 고립된 AI 어시스턴트(에이전트)를 실행할 수 있는 완전한 웹 기반 SaaS 프레임워크입니다.
• 각 사용자는 고유의 Docker 컨테이너를 가지며, Hermes 기반 AI 에이전트 런타임을 실행합니다. 컨테이너는 필요 시 생성되며, 비활성 상태에서는 일시 중지되며, 수주간 사용하지 않으면 아카이브할 수 있습니다.
• 플랫폼은 미리 준비된 프론트엔드, FastAPI 게이트웨이, PostgreSQL 스토어, 그리고 즉시 사용 가능한 기능들(지식 기반, 스킬 스토어, cron 작업, 다중 채널 봇, API 토큰 등)을 제공합니다.

주요 구성 요소

구성 요소	역할
프론트엔드 (Vite + React)	사용자가 상호작용하는 SPA – 로그인, 채팅, 스킬 스토어, 관리자 페이지.
플랫폼 게이트웨이 (FastAPI)	인증(JWT), Docker 컨테이너 관리, LLM 프록시(API 키 삽입), 할당량 추적, 이전 OpenClaw API와의 호환성 레이어.
Hermes 에이전트 컨테이너 (Python)	실제 AI 에이전트를 실행합니다. 세션, 도구 호출, 스킬, 파일 워크스페이스 등을 처리하는 HTTP + SSE API(포트 18080)를 노출합니다.
PostgreSQL	사용자 계정, 컨테이너 메타데이터, 사용 로그, 할당량을 저장합니다.
Docker Compose	서비스를 오케스트레이션하고 사용자당 별도의 컨테이너를 생성합니다.

메시지 흐름

1. 사용자가 브라우저에 입력 → 프론트엔드가 /api/...로 WebSocket 요청을 보냅니다.
2. 게이트웨이가 JWT를 인증하고 사용자 컨테이너를 찾거나 시작한 후, WebSocket을 해당 컨테이너 내의 Hermes API로 프록시합니다.
3. Hermes가 메시지를 처리하고, 도구나 스킬을 호출할 수 있으며, 언어 모델이 필요할 경우 게이트웨이의 /llm/v1/chat/completions 엔드포인트를 호출합니다.
4. 게이트웨이가 사용자 토큰 할당량을 확인하고, 모델 이름에 따라 적절한 제공자(OpenAI, Anthropic, DashScope 등)를 선택합니다. 제공자의 API 키는 게이트웨이 환경 변수에만 보관되며, 요청을 전달하고 사용량을 기록한 후, 응답을 Hermes → 프론트엔드로 스트리밍합니다.

주요 기능

• 다중 테넌트 격리 – 각 사용자는 독립된 Docker 컨테이너(2 GB RAM, 4 CPU)에서 실행되며, 파일과 채팅 기록을 위한 개인 볼륨을 갖습니다.
• 에이전트 관리 – 생성, 이름 변경, 이모지/아이콘 설정, 세부 정보 보기, 삭제.
• 실시간 채팅 – WebSocket, 마크다운 렌더링, 코드 하이라이팅, 음성 입력, 파일/이미지 업로드.
• cron 작업 – 반복적 또는 단일 작업을 스케줄링, 활성/비활성화, 즉시 실행, 선택적 알림.
• 지식 기반 – 에이전트별 파일 저장소(텍스트, PDF, JSON, 코드)로 미리보기, 다운로드, 삭제 가능.
• 스킬 스토어 – skills.sh에서 스킬 설치, 활성/비활성화, 사용자 업로드 커스텀 스킬 포함.
• 다중 채널 봇 – Telegram, Discord, 이메일, WhatsApp Web, Signal, Slack, iMessage 등 내장 어댑터 제공.
• API 접근 – 토큰 생성, CLI 또는 기타 서비스에서 에이전트 호출, 세션 재사용.
• 다수의 모델 제공자 – OpenAI, Anthropic, DashScope, DeepSeek, AiHubMix, Evolink, OpenRouter 등 수십 가지 LLM을 지원하며, 간단한 모델명 선택기로 선택 가능.
• 대시보드 – 에이전트, 세션, 스킬, 전체 시스템 건강 상태에 대한 요약 통계.
• 보안 – API 키는 사용자 컨테이너에 전달되지 않음; JWT → 컨테이너 토큰 체인; 리소스 제한; 감사 로그.

플랫폼 실행 방법

1. Docker 및 Docker‑Compose 설치.
2. 리포지토리 루트에 .env 파일 생성하고, 적어도 하나의 LLM 제공자 키 추가 (예: OPENAI_API_KEY=sk‑…).
3. 기본 이미지 빌드: python prepare.py && bash build_base_image.sh.
4. Docker Compose로 배포: python deploy_docker.py --rebuild hermes,gateway,frontend (또는 단순히 docker compose up -d).
5. http://localhost:3080에서 UI에 접속, 등록 후 채팅 시작 – 게이트웨이가 자동으로 전용 Hermes 컨테이너를 생성합니다.

일반적인 사용 사례

• 인프라를 처음부터 구축하지 않고도 각 고객에게 맞춤형 AI 어시스턴트를 제공하고자 하는 SaaS 기업.
• 각 팀이 독립된 에이전트와 개인 지식 기반, 스케줄된 작업이 필요한 내부 도구.
• 다중 모델 LLM, 도구 호출, 스킬 확장 기능을 실험하고자 하는 개발자.

제한 사항 / 주의할 점

• 플랫폼은 Docker에 의존하며, 활성 사용자당 하나의 컨테이너를 실행할 수 있는 충분한 CPU/RAM을 갖춘 호스트가 필요합니다.
• 모든 LLM 호출은 게이트웨이를 통해 프록시되므로, 제공자 API 키 제한 및 지연이 모든 사용자에게 영향을 미칩니다.
• 중량 작업에 적합하지 않을 수 있는 기본 리소스 제한(2 GB RAM, 4 CPU)은 조정이 필요할 수 있습니다.
• README에는 많은 배포 스크립트가 포함되어 있지만, 프로덕션 수준의 강화(TLS 종료, 시크릿 관리, 모니터링)는 운영자에게 맡겨져 있습니다.

더 많은 정보 찾기

• 자세한 문서는 README에 링크되어 있습니다(예: channel‑config 위키).
• UI 스크린샷과 로그는 doc/ 폴더에 있습니다.
• deploy_copy/ 디렉터리는 첫 실행 시 새 컨테이너에 복사되는 예제 사전 구성 에이전트(HR, 연구자, 프로그래머)를 포함합니다.

---

위 정보는 리포지토리의 README에서 직접 가져왔으며, 외부 가정은 추가되지 않았습니다.