`), por lo que un atacante no puede cerrar prematuramente la etiqueta ni inyectar instrucciones de sistema falsas a través de la salida de la herramienta —— el límite es impredecible por sesión.
> [!TIP]
> Este mecanismo de encapsulado también está disponible de forma independiente como [Muzzle](https://github.com/RikyZ90/Muzzle), una biblioteca Python sin dependencias que puedes integrar en cualquier framework de agentes (LangChain, LlamaIndex, CrewAI, AutoGen o un bucle personalizado).
## Sistema de Memoria
ShibaClaw utiliza una arquitectura de memoria de tres niveles:
1. **Memoria de trabajo** (por sesión) —— contexto rodante con resumen automático y truncado consciente de tokens
2. **Memoria semántica** (entre sesiones) —— almacén vectorial FAISS + sentence-transformers con extracción automática de hechos y búsqueda semántica
3. **Memoria procedimental** (habilidades y automatizaciones) —— flujos de trabajo aprendidos guardados como habilidades reutilizables, además de programaciones tipo cron
El aprendizaje proactivo extrae y almacena hechos útiles automáticamente, la auto-compactación evita el desbordamiento del contexto, y las sesiones se guardan como JSONL de solo anexo para un registro rápido y amigable con la caché.
## MCP e Integraciones
ShibaClaw habla el Model Context Protocol, por lo que puede conectarse a cualquier servidor compatible con MCP —— Google Drive, Slack, GitHub, PostgreSQL y más —— sin cambiar el código central. Configura los servidores desde el panel de Ajustes.
Para herramientas SaaS populares (Gmail, Google Drive, Slack, GitHub, Outlook...), ShibaClaw se integra con [Klavis](https://klavis.ai): una sola API key te da conexiones OAuth de un clic en lugar de registrar manualmente una app OAuth con cada proveedor. Las apps conectadas se registran automáticamente como servidores MCP en la sesión activa.
## Proveedores Soportados
ShibaClaw usa SDK nativos —— sin proxy LiteLLM —— y resuelve el proveedor desde el modelo seleccionado o un ID de modelo con prefijo de proveedor. Todos los catálogos de proveedores configurados se fusionan en una lista buscable en la WebUI.
**Clave API**
| Proveedor | Variable de entorno |
|---|---|
| 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` |
¹ Configurar `GEMINI_API_KEY` es suficiente —— el endpoint compatible con OpenAI viene preconfigurado.
**Pasarela / proxy** —— OpenRouter, AiHubMix, SiliconFlow, VolcEngine, BytePlus, auto-detectados por prefijo de clave o `api_base`.
**Local** —— Ollama, LM Studio, llama.cpp, vLLM, o cualquier endpoint compatible con OpenAI.
> [!NOTE]
> En Docker, `localhost` apunta dentro del contenedor. Para acceder a un servidor local en el host (LM Studio, Ollama), usa `http://host.docker.internal:PORT` en Windows/macOS o `http://172.17.0.1:PORT` en Linux nativo.
**OAuth**
| Proveedor | Flujo | Configuración |
|----------|------|-------|
| OpenRouter | Flujo PKCE en navegador, guarda la API key devuelta en la config del proveedor | Ajustes WebUI |
| GitHub Copilot | Flujo de dispositivo, refresco automático de token | `shibaclaw provider login github-copilot` o Ajustes WebUI |
| OpenAI Codex | Flujo PKCE en navegador | `shibaclaw provider login openai-codex` o Ajustes WebUI |
| Google Gemini CLI | Flujo PKCE en navegador, requiere las variables `SHIBACLAW_GEMINI_OAUTH_CLIENT_ID` y `SHIBACLAW_GEMINI_OAUTH_CLIENT_SECRET`. **Nota:** Integración de terceros no oficial; Google puede aplicar restricciones de cuenta. Usa una cuenta separada si es un problema. | Ajustes WebUI |
Para OpenRouter, la callback reutiliza por defecto la URL y puerto actuales de la WebUI, por lo que `http://localhost:3000` no es un puerto exclusivo de OAuth. Si expones la WebUI detrás de un proxy inverso o necesitas un origen de callback público distinto, define `SHIBACLAW_OPENROUTER_CALLBACK_BASE_URL=https://your-public-webui-host` antes de iniciar el servidor.
### 💡 Pro Tip: Modelos Económicos y Premium
ShibaClaw rinde excepcionalmente bien incluso sin gastar en API:
- **Modelos gratuitos/abiertos:** Recomendamos usar **OpenRouter** para acceder a modelos gratuitos potentes como `nvidia/nemotron-3-super-120b-a12b:free` o `gemma-4-31b-it:free`.
- **Premium ilimitado:** Si usas la integración OAuth de **GitHub Copilot**, obtienes acceso a modelos premium como `raptor` (`oswe-vscode-prime`) a costo cero, dándote solicitudes ilimitadas.
***
## 📊 Cómo se compara ShibaClaw (Seguridad Primero)
> [!NOTE]
> La callback OAuth de OpenRouter reutiliza la URL y puerto actuales de la WebUI. Detrás de un proxy inverso, define `SHIBACLAW_OPENROUTER_CALLBACK_BASE_URL` antes de iniciar el servidor.
Para uso a costo cero, tanto el nivel gratuito de OpenRouter (ej. `nvidia/nemotron-3-super-120b-a12b:free`) como la integración OAuth de GitHub Copilot (acceso ilimitado a modelos como `raptor`) funcionan bien sin una API key de pago.
## Arquitectura
**Docker Compose**
| Servicio | Rol | Puerto por defecto |
|---|---|---|
| `shibaclaw-gateway` | Bucle central del agente, bus de mensajes, integraciones de canales | 19999 (HTTP) · 19998 (WS) |
| `shibaclaw-web` | WebUI (Starlette + WebSocket), servicio de automatizaciones | 3000 |
Ambos comparten el volumen `~/.shibaclaw/` (config, workspace, memoria, trabajos de automatización, caché de medios). `shibaclaw web` por sí solo ejecuta agente + WebUI + automatizaciones en un solo proceso, sin contenedor gateway.
**Stack** —— Uvicorn/Starlette (ASGI), WebSocket nativo, frontend JS vanilla + Marked.js + Highlight.js, sesiones JSONL de solo anexo.
**Uso de recursos** —— ~120 MB en reposo / ~350 MB pico por componente (gateway, WebUI). Docker Compose limita cada contenedor a 512 MB / 256 MB reservados; la salida de herramientas se transmite con buffers acotados para que comandos largos no saturen la memoria.
## Referencia CLI
```bash
shibaclaw web # Inicia la WebUI (agente + automatizaciones en proceso)
shibaclaw gateway # Inicia solo el gateway (para split Docker)
shibaclaw onboard # Asistente de configuración inicial en CLI
shibaclaw agent -m "Hello" # Mensaje único vía terminal
shibaclaw agent # REPL interactivo con historial
shibaclaw status # Proveedor, workspace, chequeo de salud OAuth
shibaclaw print-token # Muestra el token de autenticación WebUI
shibaclaw channels status # Lista los canales habilitados
shibaclaw provider login # Login OAuth (github-copilot, openai-codex)
shibaclaw desktop # Lanza la app de escritorio Windows
```
## Canales
| Canal | Tipo | Notas |
|---|---|---|
| WebUI | Integrado | Interfaz principal, acceso completo |
| Discord | Bot | Embeds ricos, comandos slash, adjuntos |
| Telegram | Bot | Teclados en línea, medios, markup de respuesta |
| WhatsApp | Plugin | Vía WhatsApp Web |
| Slack | Bot | Block kit, hilos, menciones de app |
| DingTalk | Bot | Mensajería empresarial |
| Feishu/Lark | Bot | Tarjetas ricas, elementos interactivos |
| QQ | Bot | Mensajes de grupo y privados |
| WeCom | Bot | Comunicación laboral |
| Matrix | Bot | Descentralizado, cifrado E2E |
| MoChat | Bot | Ecosistema WeChat |
Cada canal se configura de forma independiente en Ajustes WebUI y soporta recarga en caliente ante cambios de configuración.
## Sistema de Plugins
ShibaClaw descubre plugins vía puntos de entrada de Python:
- **Plugins de canal** —— implementan `BaseChannel`, descubribles vía `shibaclaw.integrations`
- **Plugins TTS** —— implementan `BaseTTS`, descubribles vía `shibaclaw.tts`
Integrados: `shibaclaw-channel-whatsapp` (WhatsApp Web) y `shibaclaw-tts-supertonic` (síntesis de voz ONNX gratuita y offline, 31 idiomas). Instala o elimina plugins desde Ajustes WebUI > Plugins, con recarga en caliente y fijación de versión. Para crear el tuyo, consulta [`docs/PLUGINS_DEVELOPMENT_GUIDE.md`](./docs/PLUGINS_DEVELOPMENT_GUIDE.md).
## Texto a Voz
El motor Supertonic integrado se ejecuta offline sobre ONNX (sin dependencia de PyTorch, solo CPU), soporta 31 idiomas con perfiles de voz `F1`/`M1` y velocidad ajustable, y se reproduce mediante un widget en el navegador. Habilítalo en Ajustes WebUI > TTS.
## Automatización y Programación
Las tareas en segundo plano se ejecutan en programaciones tipo cron o disparadores de eventos (mensajes, webhooks, eventos del sistema), en sesiones aisladas que no contaminan el historial de chat. Gestiona, monitorea y consulta registros desde el panel de Automatizaciones; los trabajos persisten entre reinicios vía almacenamiento JSONL.
## Base de Conocimiento (RAG)
Generación aumentada por recuperación local y con prioridad en la privacidad: organiza documentos en colecciones con nombre (PDF, CSV, HTML, TXT, Markdown), sube por arrastrar y soltar, y busca con un índice FAISS sobre embeddings `all-MiniLM-L6-v2`. El agente puede llamar a `knowledge_search` durante la conversación, o apuntar a una colección específica con `@kb:name`. Es una dependencia opcional —— instala con `pip install shibaclaw[rag]`.
## Solución de Problemas
| Problema | Prueba |
|---|---|
| Chequeo de estado general | `shibaclaw status` |
| Registros de contenedor | `docker logs shibaclaw-gateway` / `docker logs shibaclaw-web` |
| WebUI no conecta | Verifica el token con `shibaclaw print-token`, comprueba el puerto |
| Errores de proveedor | `shibaclaw status` muestra la API key y el estado OAuth |
| Fallo de login tras actualizar desde v0.9.5 | Ejecuta `shibaclaw reset-admin` |
| Política de seguridad | [`SECURITY.md`](./SECURITY.md) |
---
Consulta CONTRIBUTING.md para contribuir y CHANGELOG.md para el historial de versiones.
