RikyZ90/ShibaClaw

자체 호스팅(Self-hosted) 방식의 보안 우선 AI 에이전트 (내장 웹 UI 포함)

특징 · 빠른 시작 · 보안 · 메모리 · 제공사 · 아키텍처 · 채널 · 문제 해결

🌐 간체 중국어 · 스페인어 · 포르투갈어(BR) · 일본어 · 독일어 · 프랑스어 · 이탈리아어

🚀 새로운 기능 — v1.0.4 (클릭하여 확장)

최신 릴리스 v1.0.4 (2026-10-10):

서브 에이전트 작업 실행(Subagent task execution) — 다단계 작업을 위한 감독 및 롤백 도우미가 포함된 manage-execute-audit (MEA) 실행 기능 추가.
더 유연한 에이전트 워크플로우(More flexible agent workflows) — 선택적 LLM 폴백, 도구 호출 저널(tool-call journal), 옵트인 자체 진화 제어(opt-in self-evolution controls), 데스크톱 및 모바일용 채팅 우선 작업 공간 추가.
신뢰성 수정(Reliability fixes) — 비공개 MEA 진행 상황, 작업 취소, 대화 초기화, 장애 캐싱, 동시 자동화 업데이트 및 크기 조정 중 사이드바 접근성 수정.

전체 릴리스 기록은 CHANGELOG.md를 참조하세요.

ShibaClaw는 사용자의 자체 장치나 서버에서 실행하는 자체 호스팅 AI 에이전트입니다. 내장 웹 UI가 있는 Python 엔진이며, 28개 모델 제공사에 대한 네이티브 SDK 지원과 11개의 채팅 플랫폼 통합(Discord, Telegram, Slack, WhatsApp, Matrix 등)을 갖추고 있습니다. 이 에이전트는 단순성, 보안, 개인정보 보호라는 세 가지 우선순위에 중점을 두고 구축되었으며, 설치 시 CVE 감사, 프롬프트 주입 방지(prompt-injection wrapping), SSRF 보호와 같은 방어 기능들이 외부 연결 장치처럼 붙이는 것이 아니라 핵심 엔진 자체에 내장되어 있습니다.

보안 우선 코어(Security-first core) — 암호화된 자격 증명 금고, 설치 시 CVE 감사, 프롬프트 주입 방지 래핑, SSRF/DNS 리바인딩 가드
3단계 메모리 및 웹 UI 관리자(Three-tier memory & WebUI Manager) — 작동 기억, 의미론적 (FAISS), 절차적 메모리를 갖추고 있으며, 대화형 웹 UI 관리, 실시간 편집, 꿈 일기(dream diary), 안전 격리 기능을 제공합니다.
인간 참여 루프 인터랙티브 UX(Human-in-the-loop interactive UX) — 구조화된 턴 기반 프롬프트(ask_user)

masked vault credentials, progress cards, 그리고 동적 권한 샌드박싱(dynamic permission sandboxing)을 지원하는 28개 이상의 제공업체와 네이티브 SDK를 통해 OpenAI, Anthropic, Gemini, DeepSeek 등 다양한 모델을 사용할 수 있으며, LiteLLM 프록시 계층 없이도 사용 가능합니다. 웹 및 모바일 환경에서는 LAN에서 WebUI를 노출하고 휴대폰에서도 동일한 에이전트를 사용할 수 있습니다. Windows 데스크톱 앱은 시스템 트레이 통합 기능이 있는 네이티브 런처로 제공되며, MCP-ready 기능을 통해 모든 MCP 서버에 연결할 수 있고 도구는 자동으로 등록됩니다.

필수 사항: Docker 또는 pip 경로를 위한 Python 3.12 이상입니다. Windows 자동 설치 프로그램은 필요하지 않으며, 미리 빌드된 데스크톱 앱을 제공합니다.

단 하나의 명령어로 최신 버전을 다운로드하고, 바로가기를 설정하며, UI를 실행할 수 있습니다.

팁: 자신만의 모델을 가져오세요(Bring your own model). 로컬 엔드포인트(Ollama, LM Studio)에 연결하거나 OpenRouter의 무료 API 티어를 사용하여 비용 없이 채팅을 시작할 수 있습니다.

🪟 Windows (PowerShell):

irm https://github.com/RikyZ90/ShibaClaw/releases/latest/download/install.ps1 | iex

🐧 Linux / 🍎 macOS:

curl -fsSL https://github.com/RikyZ90/ShibaClaw/releases/latest/download/install.sh | bash

참고: Windows에서는 최신 GitHub 릴리스에서 미리 빌드된 데스크톱 앱을 다운로드합니다(Python 불필요). 데스크톱/시작 메뉴 바로가기 및 '앱 및 기능'을 통한 깔끔한 제거가 가능합니다. Linux/macOS의 경우, 스크립트가 격리된 가상 환경에 pip으로 설치됩니다.

curl -fsSL https://raw.githubusercontent.com/RikyZ90/ShibaClaw/main/docker-compose.yml -o docker-compose.yml
docker compose up -d # Docker Hub에서 가져옴
docker exec -it shibaclaw-gateway shibaclaw print-token

http://localhost:3000을 열고, 토큰을 붙여넣은 후 온보딩 마법사를 따르세요. 휴대폰에서도 접근하려면 shibaclaw-web을 LAN에 노출하세요(예: 리버스 프록시를 통해).

pip install shibaclaw
shibaclaw web --with-gateway # WebUI + 에이전트 엔진을 :3000에서 시작합니다

http://localhost:3000을 열고 온보딩 마법사를 따르거나, 동일한 설정을 CLI 버전으로 사용하려면 shibaclaw onboard를 실행하세요.

원래는 앱 접착제(app glue)나 외부 프록시를 통해 분산되어 있던 방어 기능들이 ShibaClaw 코어에 기본적으로 탑재됩니다.

팁 (Tip)

이러한 래핑 메커니즘은 Muzzle이라는 독립형으로도 사용할 수 있습니다. Muzzle은 의존성이 없는(zero-dependency) Python 라이브러리이며, 어떤 에이전트 프레임워크(LangChain, LlamaIndex, CrewAI, AutoGen 또는 사용자 정의 루프)에도 쉽게 통합할 수 있습니다.

ShibaClaw는 3단계 메모리 아키텍처를 사용합니다:

작업 기억 (Working memory) (세션별) — 자동 요약 및 토큰 인식 절단(token-aware truncation)이 적용되는 순환 컨텍스트(rolling context)
의미론적 기억 (Semantic memory) (세션 간) — 자동 사실 추출 및 의미 검색을 지원하는 FAISS + sentence-transformers 벡터 저장소
절차적 기억 (Procedural memory) (스킬 및 자동화) — 재사용 가능한 스킬로 저장된 학습 워크플로우와 cron과 유사한 스케줄링 기능

사전 예방적 학습(Proactive learning)은 유용한 사실을 자동으로 추출하고 저장하며, 자동 압축(auto-compaction)은 컨텍스트가 넘치는 것을 방지합니다. 또한 세션은 빠르고 캐시 친화적인 로깅을 위해 추가 전용 JSONL 형식으로 저장됩니다.

ShibaClaw는 Model Context Protocol을 지원하므로, 핵심 코드를 변경할 필요 없이 모든 MCP-compliant 서버(Google Drive, Slack, GitHub, PostgreSQL 등)에 연결할 수 있습니다. 서버는 설정 패널에서 구성합니다.

Gmail, Google Drive, Slack, GitHub, Outlook과 같은 인기 SaaS 도구의 경우, ShibaClaw는 Klavis와 통합됩니다. 이를 통해 각 제공업체마다 OAuth 앱을 수동으로 등록하는 대신 하나의 API 키로 원클릭 OAuth 연결을 얻을 수 있습니다. 연결된 앱은 활성 세션에서 MCP 서버로 자동 등록됩니다.

ShibaClaw는 네이티브 SDK를 사용하며 LiteLLM 프록시가 필요 없고, 선택된 모델 또는 제공자 접두사가 붙은 모델 ID에서 제공자를 해결합니다. 구성된 모든 제공자 카탈로그는 WebUI의 검색 가능한 목록 하나로 병합됩니다.

API 키

Gateway / proxy — OpenRouter, AiHubMix, SiliconFlow, VolcEngine, BytePlus (키 접두사 또는 api_base로 자동 감지)

.Local — Ollama, LM Studio, llama.cpp, vLLM 또는 모든 OpenAI와 호환되는 엔드포인트.

참고
Docker에서 localhost는 컨테이너 내부를 가리킵니다. 호스트의 로컬 서버(LM Studio, Ollama)에 연결하려면 Windows/macOS에서는 http://host.docker.internal:PORT를, 네이티브 Linux에서는 http://172.17.0.1:PORT를 사용하십시오.

OAuth

OpenRouter의 경우 콜백이 기본적으로 현재 WebUI URL 및 포트를 재사용하므로 http://localhost:3000은 전용 OAuth 전용 포트가 아닙니다. 만약 WebUI를 리버스 프록시 뒤에 노출하거나 다른 공개 콜백 출처가 필요하다면, 서버 시작 전에 SHIBACLAW_OPENROUTER_CALLBACK_BASE_URL=https://your-public-webui-host를 설정하십시오.

ShibaClaw는 비용이 많이 드는 API 사용 없이도 탁월하게 작동합니다:

무료/오픈 모델: 강력한 무료 모델(예: nvidia/nemotron-3-super-120b-a12b:free 또는 gemma-4-31b-it:free)에 액세스하려면 OpenRouter를 사용하는 것을 강력히 권장합니다.

.무제한 프리미엄: GitHub Copilot OAuth 통합을 사용하면 추가 비용 없이 raptor (oswe-vscode-prime)와 같은 프리미엄 모델에 액세스할 수 있어 사실상 무제한 요청이 가능합니다.

참고
OpenRouter의 OAuth 콜백은 현재 WebUI URL 및 포트를 재사용합니다. 리버스 프록시 뒤에 있는 경우, 서버 시작 전에 SHIBACLAW_OPENROUTER_CALLBACK_BASE_URL을 설정하십시오.

무료 사용을 위해서는 OpenRouter의 무료 티어(예: nvidia/nemotron-3-super-120b-a12b:free)와 GitHub Copilot OAuth 통합(모델 raptor 등에 무제한 액세스) 모두 유료 API 키 없이 잘 작동합니다.

Docker Compose

두 서비스 모두 ~/.shibaclaw/ 볼륨을 공유합니다(설정, 작업 공간, 메모리, 자동화 작업, 미디어 캐시). shibaclaw web만 단독으로 실행하면 에이전트 + WebUI + 자동화를 단일 프로세스에서 처리하므로 게이트웨이 컨테이너가 필요하지 않습니다.

스택 — Uvicorn/Starlette (ASGI), 네이티브 WebSocket, 바닐라 JS + Marked.js + Highlight.js 프론트엔드, JSONL 추가 전용 세션.

리소스 사용량 — 구성 요소별로 유휴 상태 시 약 120 MB / 최대 350 MB입니다(게이트웨이, WebUI). Docker Compose는 각 컨테이너를 512 MB / 256 MB로 제한하며, 도구 출력 스트림은 경계가 지정된 버퍼를 사용하므로 장시간 실행되는 명령이 메모리를 과도하게 소모하는 것을 방지합니다.

shibaclaw web # WebUI 시작 (에이전트 + 자동화 인-프로세스)
shibaclaw gateway # 게이트웨이만 시작 (Docker 분리용)
shibaclaw onboard # CLI 기반 최초 설정 마법사
...

ShibaClaw는 Python 엔트리 포인트를 통해 플러그인을 검색합니다:

채널 플러그인 — BaseChannel 구현, shibaclaw.integrations을 통해 검색 가능
TTS 플러그인 — BaseTTS 구현, shibaclaw.tts를 통해 검색 가능

내장된 기능으로는 shibaclaw-channel-whatsapp(WhatsApp Web)와 shibaclaw-tts-supertonic(무료, 오프라인 ONNX 음성 합성, 31개 언어)이 있습니다. 플러그인은 WebUI 설정 > Plugins에서 설치하거나 제거할 수 있으며, 핫 리로드 및 버전 고정(version pinning)을 지원합니다. 자체 플러그인을 구축하려면 docs/PLUGINS_DEVELOPMENT_GUIDE.md를 참조하세요.

내장된 Supertonic 엔진은 ONNX로 오프라인에서 실행되며 (PyTorch 종속성 없음, CPU 전용), F1을 통해 31개 언어를 지원하고 /M1 음성 프로필 및 조정 가능한 속도를 지원하며, 인-브라우저 위젯을 통해 재생합니다. WebUI 설정 > TTS에서 활성화할 수 있습니다.

백그라운드 작업은 cron과 유사한 스케줄 또는 이벤트 트리거(메시지, 웹훅, 시스템 이벤트)로 실행되며, 채팅 기록을 오염시키지 않는 격리된 세션에서 작동합니다. 자동화(Automations) 패널에서 작업을 관리하고 모니터링하며 로그를 볼 수 있습니다. 작업은 JSONL 저장소를 통해 재시작 시에도 지속됩니다.

로컬이며 개인 정보 보호에 중점을 둔 검색 증강 생성(RAG): 문서를 이름이 지정된 컬렉션(PDF, CSV, HTML, TXT, Markdown)으로 정리하고 드래그 앤 드롭 방식으로 업로드한 다음, all-MiniLM-L6-v2 임베딩을 사용하는 FAISS 인덱스로 검색합니다. 에이전트는 대화 중에 knowledge_search를 호출할 수 있으며, 또는 @kb:name으로 특정 컬렉션을 지정할 수 있습니다. 이는 선택적 종속성이므로 pip install shibaclaw[rag]로 설치하십시오.