`) eingehüllt, sodass ein Angreifer den Tag nicht vorzeitig schließen oder über die Tool-Ausgabe falsche Systemanweisungen injizieren kann —— die Grenze ist pro Sitzung unberechenbar.
> [!TIP]
> Dieser Wrapping-Mechanismus ist auch eigenständig als [Muzzle](https://github.com/RikyZ90/Muzzle) verfügbar, einer abhängigkeitsfreien Python-Bibliothek, die du in jedes Agenten-Framework (LangChain, LlamaIndex, CrewAI, AutoGen oder eine eigene Schleife) einhängen kannst.
## Speichersystem
ShibaClaw verwendet eine dreistufige Speicherarchitektur:
1. **Working-Speicher** (pro Sitzung) —— rollierender Kontext mit automatischer Zusammenfassung und token-bewusstem Abschneiden
2. **Semantic-Speicher** (übergreifend) —— FAISS + sentence-transformers Vektorstore mit automatischer Faktenextraktion und semantischer Suche
3. **Procedural-Speicher** (Skills & Automationen) —— gelernte Workflows als wiederverwendbare Skills gespeichert, plus cron-artige Zeitpläne
Proaktives Lernen extrahiert und speichert nützliche Fakten automatisch, Auto-Kompaktierung verhindert das Überlaufen des Kontexts, und Sitzungen werden als nur-anhängendes JSONL für schnelles, cache-freundliches Logging gespeichert.
## MCP & Integrationen
ShibaClaw spricht das Model Context Protocol und kann sich daher ohne Kerncode-Änderungen mit jedem MCP-kompatiblen Server verbinden —— Google Drive, Slack, GitHub, PostgreSQL und mehr. Server werden über das Einstellungspanel konfiguriert.
Für beliebte SaaS-Tools (Gmail, Google Drive, Slack, GitHub, Outlook...) integriert sich ShibaClaw mit [Klavis](https://klavis.ai): ein API-Schlüssel liefert OAuth-Verbindungen mit einem Klick, statt für jeden Anbieter manuell eine OAuth-App zu registrieren. Verbundene Apps werden in der aktiven Sitzung automatisch als MCP-Server registriert.
## Unterstützte Anbieter
ShibaClaw verwendet native SDKs —— kein LiteLLM-Proxy —— und löst den Anbieter aus dem ausgewählten Modell oder einer anbieterpräfixierten Modell-ID auf. Alle konfigurierten Anbieterkataloge werden in der WebUI zu einer durchsuchbaren Liste zusammengeführt.
**API-Schlüssel**
| Anbieter | Umgebungsvariable |
|---|---|
| OpenAI | `OPENAI_API_KEY` |
| Anthropic | `ANTHROPIC_API_KEY` |
| DeepSeek | `DEEPSEEK_API_KEY` |
| Google Gemini | `GEMINI_API_KEY`¹ |
| Groq | `GROQ_API_KEY` |
| Moonshot | `MOONSHOT_API_KEY` |
| MiniMax | `MINIMAX_API_KEY` |
| Zhipu AI | `ZAI_API_KEY` |
| DashScope | `DASHSCOPE_API_KEY` |
¹ `GEMINI_API_KEY` zu setzen genügt —— der OpenAI-kompatible Endpunkt ist vorkonfiguriert.
**Gateway / Proxy** —— OpenRouter, AiHubMix, SiliconFlow, VolcEngine, BytePlus, automatisch erkannt über Key-Präfix oder `api_base`.
**Lokal** —— Ollama, LM Studio, llama.cpp, vLLM oder ein beliebiger OpenAI-kompatibler Endpunkt.
> [!NOTE]
> In Docker zeigt `localhost` in den Container hinein. Um einen lokalen Server auf dem Host (LM Studio, Ollama) zu erreichen, verwende unter Windows/macOS `http://host.docker.internal:PORT` bzw. unter nativem Linux `http://172.17.0.1:PORT`.
**OAuth**
| Anbieter | Ablauf | Einrichtung |
|----------|------|-------|
| OpenRouter | PKCE-Browser-Flow, speichert zurückgegebenen API-Schlüssel in der Provider-Konfiguration | WebUI-Einstellungen |
| GitHub Copilot | Device-Flow, automatische Token-Auffrischung | `shibaclaw provider login github-copilot` oder WebUI-Einstellungen |
| OpenAI Codex | PKCE-Browser-Flow | `shibaclaw provider login openai-codex` oder WebUI-Einstellungen |
| Google Gemini CLI | PKCE-Browser-Flow, benötigt die Umgebungsvariablen `SHIBACLAW_GEMINI_OAUTH_CLIENT_ID` und `SHIBACLAW_GEMINI_OAUTH_CLIENT_SECRET`. **Hinweis:** Inoffizielle Drittanbieter-Integration; Google kann Kontobeschränkungen anwenden. Bei Bedenken ein separates Konto verwenden. | WebUI-Einstellungen |
Für OpenRouter verwendet der Callback standardmäßig die aktuelle WebUI-URL und den Port, daher ist `http://localhost:3000` kein dedizierter OAuth-Port. Wenn du die WebUI hinter einem Reverse-Proxy bereitstellst oder einen anderen öffentlichen Callback-Ursprung benötigst, setze vor dem Serverstart `SHIBACLAW_OPENROUTER_CALLBACK_BASE_URL=https://your-public-webui-host`.
### 💡 Profi-Tipp: Kostengünstige & Premium-Modelle
ShibaClaw funktioniert auch ohne teure API-Nutzung hervorragend:
- **Kostenlose/offene Modelle:** Wir empfehlen **OpenRouter**, um leistungsstarke kostenlose Modelle wie `nvidia/nemotron-3-super-120b-a12b:free` oder `gemma-4-31b-it:free` zu nutzen.
- **Unbegrenzte Premium:** Mit der **GitHub Copilot**-OAuth-Integration erhältst du Zugriff auf Premium-Modelle wie `raptor` (`oswe-vscode-prime`) zu null zusätzlichen Kosten, was dir effektiv unbegrenzte Anfragen gibt.
***
## 📊 Wie ShibaClaw im Vergleich abschneidet (Sicherheit zuerst)
> [!NOTE]
> Der OpenRouter-OAuth-Callback verwendet die aktuelle WebUI-URL und den Port. Hinter einem Reverse-Proxy setze vor dem Serverstart `SHIBACLAW_OPENROUTER_CALLBACK_BASE_URL`.
Für die kostenlose Nutzung funktionieren sowohl OpenRouters Free-Tier (z. B. `nvidia/nemotron-3-super-120b-a12b:free`) als auch die GitHub-Copilot-OAuth-Integration (unbegrenzter Zugriff auf Modelle wie `raptor`) ohne kostenpflichtigen API-Schlüssel gut.
## Architektur
**Docker Compose**
| Dienst | Rolle | Standardport |
|---|---|---|
| `shibaclaw-gateway` | Kern-Agenten-Loop, Message-Bus, Kanal-Integrationen | 19999 (HTTP) · 19998 (WS) |
| `shibaclaw-web` | WebUI (Starlette + WebSocket), Automatisierungsdienst | 3000 |
Beide teilen sich das Volume `~/.shibaclaw/` (Config, Workspace, Speicher, Automatisierungsjobs, Medien-Cache). `shibaclaw web` allein führt Agent + WebUI + Automatisierungen in einem Prozess aus, kein Gateway-Container nötig.
**Stack** —— Uvicorn/Starlette (ASGI), natives WebSocket, Vanilla-JS + Marked.js + Highlight.js Frontend, JSONL nur-anhängende Sitzungen.
**Ressourcenverbrauch** —— ~120 MB im Leerlauf / ~350 MB Spitze pro Komponente (Gateway, WebUI). Docker Compose begrenzt jeden Container auf 512 MB / 256 MB Reservierung; Tool-Ausgaben streamen mit begrenzten Puffern, sodass langlaufende Befehle den Speicher nicht sprengen.
## CLI-Referenz
```bash
shibaclaw web # WebUI starten (Agent + Automatisierungen im Prozess)
shibaclaw gateway # Nur Gateway starten (für Docker-Split)
shibaclaw onboard # CLI-basiertes Erstsetup-Wizard
shibaclaw agent -m "Hello" # Einmalige Nachricht via Terminal
shibaclaw agent # Interaktive REPL mit Verlauf
shibaclaw status # Provider-, Workspace-, OAuth-Healthcheck
shibaclaw print-token # WebUI-Auth-Token anzeigen
shibaclaw channels status # Aktivierte Kanäle auflisten
shibaclaw provider login # OAuth-Login (github-copilot, openai-codex)
shibaclaw desktop # Windows-Desktop-App starten
```
## Kanäle
| Kanal | Typ | Hinweise |
|---|---|---|
| WebUI | Integriert | Hauptoberfläche, voller Funktionszugriff |
| Discord | Bot | Rich Embeds, Slash-Befehle, Anhänge |
| Telegram | Bot | Inline-Tastaturen, Medien, Reply-Markup |
| WhatsApp | Plugin | über WhatsApp Web |
| Slack | Bot | Block kit, Threads, App-Erwähnungen |
| DingTalk | Bot | Enterprise-Messaging |
| Feishu/Lark | Bot | Rich Cards, interaktive Elemente |
| QQ | Bot | Gruppen- & Privatnachrichten |
| WeCom | Bot | Workplace-Kommunikation |
| Matrix | Bot | Dezentral, E2E-Verschlüsselung |
| MoChat | Bot | WeChat-Ökosystem |
Jeder Kanal wird in den WebUI-Einstellungen unabhängig konfiguriert und unterstützt Hot-Reload bei Konfigurationsänderungen.
## Plugin-System
ShibaClaw entdeckt Plugins über Python-Entry-Points:
- **Kanal-Plugins** —— implementieren `BaseChannel`, über `shibaclaw.integrations` auffindbar
- **TTS-Plugins** —— implementieren `BaseTTS`, über `shibaclaw.tts` auffindbar
Eingebaut: `shibaclaw-channel-whatsapp` (WhatsApp Web) und `shibaclaw-tts-supertonic` (kostenlose, offline ONNX-Sprachsynthese, 31 Sprachen). Plugins über WebUI-Einstellungen > Plugins installieren oder entfernen, mit Hot-Reload und Versions-Pinning. Zum Eigenbau siehe [`docs/PLUGINS_DEVELOPMENT_GUIDE.md`](./docs/PLUGINS_DEVELOPMENT_GUIDE.md).
## Text-zu-Sprache
Die eingebaute Supertonic-Engine läuft offline auf ONNX (keine PyTorch-Abhängigkeit, nur CPU), unterstützt 31 Sprachen mit `F1`/`M1`-Stimmprofilen und einstellbarer Geschwindigkeit und spielt über ein In-Browser-Widget ab. In WebUI-Einstellungen > TTS aktivieren.
## Automatisierung & Zeitplanung
Hintergrundaufgaben laufen nach cron-artigen Zeitplänen oder Ereignis-Triggern (Nachrichten, Webhooks, Systemereignisse) in isolierten Sitzungen, die den Chatverlauf nicht verschmutzen. Verwalte, überwache und sieh Logs über das Automatisierungs-Panel ein; Jobs bleiben über JSONL-Speicher über Neustarts hinweg erhalten.
## Wissensdatenbank (RAG)
Lokale, datenschutzorientierte Retrieval-Augmented Generation: Dokumente in benannten Sammlungen organisieren (PDF, CSV, HTML, TXT, Markdown), per Drag-and-Drop hochladen und mit einem FAISS-Index über `all-MiniLM-L6-v2`-Embeddings suchen. Der Agent kann `knowledge_search` im Gespräch aufrufen oder mit `@kb:name` eine bestimmte Sammlung ansprechen. Es ist eine optionale Abhängigkeit —— installiere mit `pip install shibaclaw[rag]`.
## Fehlerbehebung
| Problem | Versuch |
|---|---|
| Allgemeiner Statuscheck | `shibaclaw status` |
| Container-Logs | `docker logs shibaclaw-gateway` / `docker logs shibaclaw-web` |
| WebUI verbindet nicht | Token mit `shibaclaw print-token` prüfen, Port-Bindung verifizieren |
| Provider-Fehler | `shibaclaw status` zeigt API-Schlüssel und OAuth-Status |
| Login fehlgeschlagen nach Upgrade von v0.9.5 | `shibaclaw reset-admin` ausführen |
| Sicherheitsrichtlinie | [`SECURITY.md`](./SECURITY.md) |
---
Siehe CONTRIBUTING.md zum Mitwirken und CHANGELOG.md für die Versionshistorie.
