`), si bien qu'un attaquant ne peut ni fermer prématurément la balise ni injecter de fausses instructions système via la sortie de l'outil —— la limite est imprévisible par session.
> [!TIP]
> Ce mécanisme d'encapsulation est aussi disponible séparément sous la forme de [Muzzle](https://github.com/RikyZ90/Muzzle), une bibliothèque Python sans dépendance que vous pouvez intégrer à n'importe quel framework d'agents (LangChain, LlamaIndex, CrewAI, AutoGen ou une boucle personnalisée).
## Système de Mémoire
ShibaClaw utilise une architecture mémoire à trois niveaux :
1. **Mémoire de travail** (par session) —— contexte défilant avec résumé automatique et troncature consciente des tokens
2. **Mémoire sémantique** (entre sessions) —— magasin vectoriel FAISS + sentence-transformers avec extraction automatique de faits et recherche sémantique
3. **Mémoire procédurale** (compétences et automatisations) —— flux de travail appris enregistrés comme compétences réutilisables, plus des planifications de type cron
L'apprentissage proactif extrait et stocke automatiquement des faits utiles, l'auto-compaction empêche le débordement du contexte, et les sessions sont stockées en JSONL en ajout seul pour un journalisme rapide et favorable au cache.
## MCP et Intégrations
ShibaClaw parle le Model Context Protocol, il peut donc se connecter à n'importe quel serveur compatible MCP —— Google Drive, Slack, GitHub, PostgreSQL et plus —— sans modifier le code central. Configurez les serveurs depuis le panneau Paramètres.
Pour les outils SaaS populaires (Gmail, Google Drive, Slack, GitHub, Outlook...), ShibaClaw s'intègre avec [Klavis](https://klavis.ai) : une seule clé API vous donne des connexions OAuth en un clic au lieu d'enregistrer manuellement une app OAuth auprès de chaque fournisseur. Les apps connectées sont auto-enregistrées comme serveurs MCP dans la session active.
## Fournisseurs Pris en Charge
ShibaClaw utilise des SDK natifs —— sans proxy LiteLLM —— et résout le fournisseur à partir du modèle sélectionné ou d'un ID de modèle préfixé par le fournisseur. Tous les catalogues de fournisseurs configurés sont fusionnés en une liste recherchable dans la WebUI.
**Clé API**
| Fournisseur | Variable d'environnement |
|---|---|
| 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` |
¹ Définir `GEMINI_API_KEY` suffit —— l'endpoint compatible OpenAI est pré-configuré.
**Passerelle / proxy** —— OpenRouter, AiHubMix, SiliconFlow, VolcEngine, BytePlus, auto-détectés par préfixe de clé ou `api_base`.
**Local** —— Ollama, LM Studio, llama.cpp, vLLM, ou n'importe quel endpoint compatible OpenAI.
> [!NOTE]
> Dans Docker, `localhost` pointe à l'intérieur du conteneur. Pour atteindre un serveur local sur l'hôte (LM Studio, Ollama), utilisez `http://host.docker.internal:PORT` sur Windows/macOS ou `http://172.17.0.1:PORT` sur Linux natif.
**OAuth**
| Fournisseur | Flux | Configuration |
|----------|------|-------|
| OpenRouter | Flux PKCE navigateur, stocke la clé API renvoyée dans la config du fournisseur | Paramètres WebUI |
| GitHub Copilot | Flux device, rafraîchissement automatique du jeton | `shibaclaw provider login github-copilot` ou Paramètres WebUI |
| OpenAI Codex | Flux PKCE navigateur | `shibaclaw provider login openai-codex` ou Paramètres WebUI |
| Google Gemini CLI | Flux PKCE navigateur, nécessite les variables d'environnement `SHIBACLAW_GEMINI_OAUTH_CLIENT_ID` et `SHIBACLAW_GEMINI_OAUTH_CLIENT_SECRET`. **Note :** Intégration tierce non officielle ; Google peut appliquer des restrictions de compte. Utilisez un compte séparé si cela vous préoccupe. | Paramètres WebUI |
Pour OpenRouter, le callback réutilise par défaut l'URL et le port actuels de la WebUI, donc `http://localhost:3000` n'est pas un port OAuth dédié. Si vous exposez la WebUI derrière un proxy inverse ou avez besoin d'une origine de callback publique différente, définissez `SHIBACLAW_OPENROUTER_CALLBACK_BASE_URL=https://your-public-webui-host` avant de démarrer le serveur.
### 💡 Pro Tip : Modèles économiques et premium
ShibaClaw fonctionne de manière exceptionnelle même sans dépenser en API :
- **Modèles gratuits/ouverts :** nous recommandons d'utiliser **OpenRouter** pour accéder à des modèles gratuits puissants comme `nvidia/nemotron-3-super-120b-a12b:free` ou `gemma-4-31b-it:free`.
- **Premium illimité :** si vous utilisez l'intégration OAuth **GitHub Copilot**, vous obtenez l'accès à des modèles premium comme `raptor` (`oswe-vscode-prime`) à coût zéro, vous donnant des requêtes illimitées.
***
## 📊 Comment ShibaClaw se compare (Sécurité d'abord)
> [!NOTE]
> Le callback OAuth d'OpenRouter réutilise l'URL et le port actuels de la WebUI. Derrière un proxy inverse, définissez `SHIBACLAW_OPENROUTER_CALLBACK_BASE_URL` avant de démarrer le serveur.
Pour une utilisation à coût zéro, tant le niveau gratuit d'OpenRouter (ex. `nvidia/nemotron-3-super-120b-a12b:free`) que l'intégration OAuth GitHub Copilot (accès illimité à des modèles comme `raptor`) fonctionnent bien sans clé API payante.
## Architecture
**Docker Compose**
| Service | Rôle | Port par défaut |
|---|---|---|
| `shibaclaw-gateway` | Boucle centrale de l'agent, bus de messages, intégrations de canaux | 19999 (HTTP) · 19998 (WS) |
| `shibaclaw-web` | WebUI (Starlette + WebSocket), service d'automatisation | 3000 |
Les deux partagent le volume `~/.shibaclaw/` (config, workspace, mémoire, jobs d'automatisation, cache média). `shibaclaw web` seul exécute agent + WebUI + automatisations dans un seul processus, sans conteneur passerelle.
**Stack** —— Uvicorn/Starlette (ASGI), WebSocket natif, frontend JS vanilla + Marked.js + Highlight.js, sessions JSONL en ajout seul.
**Utilisation des ressources** —— ~120 Mo au repos / ~350 Mo en pic par composant (passerelle, WebUI). Docker Compose plafonne chaque conteneur à 512 Mo / 256 Mo réservés ; les sorties d'outils sont diffusées avec des tampons bornés afin que les commandes longues ne fassent pas exploser la mémoire.
## Référence CLI
```bash
shibaclaw web # Démarre la WebUI (agent + automatisations en processus)
shibaclaw gateway # Démarre uniquement la passerelle (pour le split Docker)
shibaclaw onboard # Assistant de configuration initiale en CLI
shibaclaw agent -m "Hello" # Message unique via le terminal
shibaclaw agent # REPL interactive avec historique
shibaclaw status # Fournisseur, workspace, healthcheck OAuth
shibaclaw print-token # Affiche le jeton d'auth WebUI
shibaclaw channels status # Liste les canaux activés
shibaclaw provider login # Connexion OAuth (github-copilot, openai-codex)
shibaclaw desktop # Lance l'app de bureau Windows
```
## Canaux
| Canal | Type | Notes |
|---|---|---|
| WebUI | Intégré | Interface principale, accès complet aux fonctionnalités |
| Discord | Bot | Rich embeds, commandes slash, pièces jointes |
| Telegram | Bot | Claviers inline, médias, markup de réponse |
| WhatsApp | Plugin | Via WhatsApp Web |
| Slack | Bot | Block kit, threads, mentions d'app |
| DingTalk | Bot | Messagerie d'entreprise |
| Feishu/Lark | Bot | Cartes riches, éléments interactifs |
| QQ | Bot | Messages de groupe et privés |
| WeCom | Bot | Communication en entreprise |
| Matrix | Bot | Décentralisé, chiffrement E2E |
| MoChat | Bot | Écosystème WeChat |
Chaque canal est configuré indépendamment dans les Paramètres WebUI et prend en charge le rechargement à chaud lors des changements de configuration.
## Système de Plugins
ShibaClaw découvre les plugins via les points d'entrée Python :
- **Plugins de canal** —— implémentent `BaseChannel`, découvrables via `shibaclaw.integrations`
- **Plugins TTS** —— implémentent `BaseTTS`, découvrables via `shibaclaw.tts`
Intégrés : `shibaclaw-channel-whatsapp` (WhatsApp Web) et `shibaclaw-tts-supertonic` (synthèse vocale ONNX gratuite et hors ligne, 31 langues). Installez ou supprimez des plugins depuis Paramètres WebUI > Plugins, avec rechargement à chaud et épinglage de version. Pour en créer un, voir [`docs/PLUGINS_DEVELOPMENT_GUIDE.md`](./docs/PLUGINS_DEVELOPMENT_GUIDE.md).
## Synthèse Vocale (TTS)
Le moteur Supertonic intégré fonctionne hors ligne sur ONNX (sans dépendance PyTorch, CPU uniquement), prend en charge 31 langues avec des profils vocaux `F1`/`M1` et une vitesse ajustable, et lit via un widget intégré au navigateur. Activez-le dans Paramètres WebUI > TTS.
## Automatisation et Planification
Les tâches en arrière-plan s'exécutent selon des planifications de type cron ou des déclencheurs d'événements (messages, webhooks, événements système), dans des sessions isolées qui ne polluent pas l'historique de chat. Gérez, surveillez et consultez les journaux depuis le panneau Automatisations ; les jobs persistent après redémarrage via le stockage JSONL.
## Base de Connaissances (RAG)
Génération augmentée par récupération locale et axée sur la confidentialité : organisez les documents en collections nommées (PDF, CSV, HTML, TXT, Markdown), téléversez par glisser-déposer et recherchez avec un index FAISS sur les embeddings `all-MiniLM-L6-v2`. L'agent peut appeler `knowledge_search` pendant la conversation, ou cibler une collection spécifique avec `@kb:name`. C'est une dépendance optionnelle —— installez avec `pip install shibaclaw[rag]`.
## Dépannage
| Problème | Essayez |
|---|---|
| Vérification d'état générale | `shibaclaw status` |
| Journaux de conteneur | `docker logs shibaclaw-gateway` / `docker logs shibaclaw-web` |
| WebUI ne se connecte pas | Vérifiez le jeton avec `shibaclaw print-token`, validez la liaison de port |
| Erreurs de fournisseur | `shibaclaw status` affiche la clé API et l'état OAuth |
| Échec de connexion après mise à jour depuis v0.9.5 | Exécutez `shibaclaw reset-admin` |
| Politique de sécurité | [`SECURITY.md`](./SECURITY.md) |
---
Voir CONTRIBUTING.md pour contribuer et CHANGELOG.md pour l'historique des versions.
