{"id":"a1a088a9-66cd-4560-8a0b-bb4648d4143b","slug":"shibaclaw","kind":"mcp","name":"ShibaClaw","summary":"Self-hosted personal AI agent with a WebUI, memory, tools, MCP, sub-agents and automations. Connect local or cloud LLMs.","owner":"RikyZ90","repoUrl":"https://github.com/RikyZ90/ShibaClaw","license":"Apache-2.0","licenseTier":"permissive","trust":"community","stars":84,"match":null,"fewStars":false,"format":"mcp","createdAt":"2026-03-20T00:26:05.000Z","addedAt":"2026-10-28T09:51:40.481Z","logoUrl":"https://avatars.githubusercontent.com/u/184956820?u=908a9914366f8d118a28043ff2d37299a003a8a3&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["memory-knowledge","search","cloud-infra"],"tags":["ai-agent","ai-agents","docker","self-hosted","agent-framework","multi-agent","ollama","security"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-28T09:55:18.635Z","sample":false,"url":"https://conduits.dev/tools/shibaclaw","language":"Python","transports":["stdio"],"install":{"pypi":"shibaclaw"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"

\n \"ShibaClaw\"\n

\n\n

ShibaClaw

\n\n

A self-hosted personal AI agent with a built-in WebUI. Use local or cloud models, with memory, tools and automations in one place.

\n\n

\n \"version\"\n \"PyPI\n \"Docker\n \"python\"\n \"Apache\n \"CI\n \"Ask\n

\n\n## Demo\n\n

\n \"ShibaClaw\n \"ShibaClaw\n

\n\n## Why ShibaClaw?\n\nFor people who want a personal AI assistant they can install and operate on their own machine or server, with a UI and configurable tools ready to use.\n\n- **One place to work** — built-in WebUI, a Windows desktop launcher, and a mobile layout for access over your LAN.\n- **Your choice of model** — local LLMs through Ollama or an OpenAI-compatible server; cloud providers and documented OAuth integrations.\n- **Persistent context** — editable memory, reusable skills, and an optional document knowledge base.\n- **Tools and MCP** — file, shell and web tools, plus external tools through the Model Context Protocol.\n- **Multi-agent tasks and automation** — isolated or forked sub-agents, scheduled tasks, and optional [project verification](docs/PROJECT_VERIFICATION.md).\n- **Security controls in the core** — an encrypted credential vault, workspace restrictions, SSRF filtering and prompt-injection defenses. See [their scope and limits](#security).\n\nCompare requirements in [ShibaClaw vs OpenClaw, nanobot and Hermes Agent](docs/COMPARISON.md).\n\n## Quick Start\n\n**Requirements:** Docker, or Python 3.12+ for the pip route. The Windows auto-installer needs neither — it ships a pre-built desktop app.\n\n### Auto-installer (recommended)\n\nChoose the installer for your operating system, or use Docker or pip below.\n\n> [!TIP]\n> Bring your own model: start with [Ollama](docs/integrations/OLLAMA.md), an OpenAI-compatible endpoint, or a cloud provider such as [OpenRouter](docs/integrations/OPENROUTER.md). Model availability, pricing and limits depend on the provider.\n\n**🪟 Windows (PowerShell):**\n```powershell\nirm https://github.com/RikyZ90/ShibaClaw/releases/latest/download/install.ps1 | iex\n```\n\nOr download and open **[ShibaClaw-Setup.exe](https://github.com/RikyZ90/ShibaClaw/releases/latest/download/ShibaClaw-Setup.exe)**. The PowerShell command downloads the same setup, verifies its SHA256 against the GitHub release asset digest, and starts it.\n\n**🐧 Linux / 🍎 macOS:**\n```bash\ncurl -fsSL https://github.com/RikyZ90/ShibaClaw/releases/latest/download/install.sh | bash\n```\n\n> [!NOTE]\n> Windows setup installs per user and preserves existing data. Linux/macOS use pip in an isolated virtual environment. See [Windows installation, updates and portable ZIP options](docs/WINDOWS_INSTALLATION.md).\n\n### Docker\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/RikyZ90/ShibaClaw/main/docker-compose.yml -o docker-compose.yml\ndocker compose up -d # pulls from Docker Hub\n```\n\nOpen `http://localhost:3000`, create your admin account on first launch (or sign in to an existing account), and follow the onboarding wizard. To reach it from your phone, configure authenticated access over your LAN, for example through an HTTPS reverse proxy.\n\n### pip\n\n```bash\npip install shibaclaw\nshibaclaw web --with-gateway # starts WebUI + agent engine on :3000\n```\n\nOpen `http://localhost:3000`, create your admin account on first launch and follow the onboarding wizard. `shibaclaw onboard` configures the agent and workspace from the CLI; WebUI account creation still happens in the browser.\n\nIf ShibaClaw is useful to you, consider [starring the repository](https://github.com/RikyZ90/ShibaClaw) to help others discover it.\n\n## Explore\n\n[Demo](#demo) · [Why ShibaClaw?](#why-shibaclaw) · [Installation](#quick-start) · [Features](#features) · [Integrations](docs/integrations/README.md) · [Documentation](docs/README.md)\n\n[Providers](#supported-providers) · [MCP](#mcp--integrations) · [Memory](#memory-system) · [Security](#security) · [Comparison](docs/COMPARISON.md) · [Architecture](#architecture) · [Contributing](CONTRIBUTING.md) · [Releases](#whats-new)\n\n🌐 [简体中文](README.zh-CN.md) · [Español](README.es.md) · [Português (BR)](README.pt-BR.md) · [日本語](README.ja.md) · [Deutsch](README.de.md) · [Français](README.fr.md) · [Italiano](README.it.md)\n\nTranslations retain their existing content; see the [synchronization checklist](docs/CONTRIBUTING_IDEAS.md#readme-translation-sync) for this README revision.\n\n## Features\n\n| Area | Included capabilities | Learn more |\n|---|---|---|\n| Agent runtime | Provider retries, durable tool journaling, context/resource guards, isolated or forked sub-agents | [Project verification](docs/PROJECT_VERIFICATION.md) |\n| Interactive WebUI | In-turn questions (`ask_user`), progress cards, masked credentials, permission controls | [Demo](#demo) |\n| Memory and knowledge | Editable long-term memory, session history, reusable skills, optional document retrieval | [Memory](#memory-system), [RAG](#knowledge-base-rag) |\n| AI automation | One-shot, interval and cron schedules; heartbeat tasks | [Automations](#automation--scheduling) |\n| Communication | WebUI and messaging integrations, including Discord, Telegram, Slack and Matrix | [Channels](#channels) |\n| Extensions | MCP tools, channel and TTS plugins, opt-in self-evolution with validation gates | [MCP](#mcp--integrations), [Plugins](#plugin-system) |\n\n---\n\n## Security\n\nSecurity controls are part of the agent runtime. Their effectiveness depends on configuration, installed audit tools and the tools you authorize.\n\n| Layer | What it does |\n|---|---|\n| Credential storage | Fernet-encrypted vault; encryption key in the OS keyring when available, with a restricted key-file fallback |\n| Install-time audit | Checks recognized package-install commands; blocks findings at the configured severity when the audit completes. Missing tools, errors or timeouts can allow installation with a warning |\n| Prompt-injection defenses | Randomized tool-output boundaries and pre-scanning of untrusted content |\n| Shell hardening | Deny patterns, escape normalization, internal URL detection |\n| Network guard | SSRF filtering, redirect revalidation, DNS-rebinding-safe resolution |\n| Workspace sandbox | File tools and file browser restricted to the configured workspace by default |\n| Access control | Admin username/password login, session-token authentication, channel allowlists, optional rate limiting |\n\nPrompt-injection defenses reduce exposure to untrusted tool output; they cannot guarantee safe model behavior. Protect the host account and vault key, review tool permissions, and use authentication and HTTPS when exposing the WebUI beyond localhost. Using a cloud model or remote MCP service sends relevant content to that service.\n\n> [!TIP]\n> Tool-output wrapping is also available as [Muzzle](https://github.com/RikyZ90/Muzzle). See the [security policy](SECURITY.md) for reporting and the [implementation](shibaclaw/security/) for current controls.\n\n## Memory System\n\nShibaClaw keeps context at three levels:\n\n1. **Working memory** (per session) — rolling context with automatic summarization and token-aware truncation\n2. **Long-term memory** (cross-session) — editable `USER.md`, `memory/MEMORY.md` and `memory/HISTORY.md`, with fact extraction and ranked history search\n3. **Procedural memory** (skills & automations) — learned workflows saved as reusable skills, plus cron-like schedules\n\nThe WebUI exposes memory editing, the dream diary and quarantined entries; sessions are stored as append-only JSONL. The optional [knowledge base](#knowledge-base-rag) adds FAISS document retrieval separately from these memory files.\n\n## MCP & Integrations\n\nShibaClaw is an MCP agent: it connects to external tools using the Model Context Protocol and registers the tools returned by each configured server. Add servers in Settings; transport, authentication and tool behavior must be compatible with the server you choose.\n\nConnected Apps integrates with [Klavis](https://klavis.ai) for hosted OAuth connections and MCP servers. Available apps and access depend on your Klavis account. Review each server's permissions and data handling before connecting it.\n\nFor model setup, use the dedicated [integration guides](docs/integrations/README.md): [OpenAI Codex](docs/integrations/OPENAI_CODEX.md), [Claude](docs/integrations/CLAUDE.md), [GitHub Copilot](docs/integrations/GITHUB_COPILOT.md), [OpenRouter](docs/integrations/OPENROUTER.md) and [Ollama](docs/integrations/OLLAMA.md).\n\n## Supported Providers\n\nShibaClaw uses provider-specific adapters and OpenAI-compatible endpoints, without a LiteLLM proxy. It resolves the provider from the selected model or a provider-prefixed model ID. Configured provider catalogs appear in the WebUI; the [provider registry](shibaclaw/thinkers/registry.py) is the source of truth for supported routes.\n\n**API key**\n\n| Provider | Env variable |\n|---|---|\n| OpenAI | `OPENAI_API_KEY` |\n| Anthropic | `ANTHROPIC_API_KEY` — see [current authentication limitation](docs/integrations/CLAUDE.md) |\n| DeepSeek | `DEEPSEEK_API_KEY` |\n| Google Gemini | `GEMINI_API_KEY`¹ |\n| Groq | `GROQ_API_KEY` |\n| Moonshot | `MOONSHOT_API_KEY` |\n| MiniMax | `MINIMAX_API_KEY` |\n| Zhipu AI | `ZAI_API_KEY` |\n| DashScope | `DASHSCOPE_API_KEY` |\n\n¹ Setting `GEMINI_API_KEY` is sufficient — the OpenAI-compatible endpoint is pre-configured.\n\n**Gateway / proxy** — OpenRouter, AiHubMix, SiliconFlow, VolcEngine, BytePlus, auto-detected by key prefix or `api_base`.\n\n**Local** — Ollama, LM Studio, llama.cpp, vLLM, or any OpenAI-compatible endpoint.\n\n> [!NOTE]\n> In Docker, `localhost` points inside the container. On Docker Desktop, use `host.docker.internal` to reach a host model server; native Linux needs a reachable host address or host-gateway mapping. See the [Ollama networking instructions](docs/integrations/OLLAMA.md#docker-or-another-host), including the required `/v1` API base.\n\n**Account connections** — availability and permitted use depend on each provider's current terms and your account.\n\n| Provider | Flow | Setup |\n|----------|------|-------|\n| OpenRouter | PKCE browser flow; returned API key saved in the credential vault | [Setup guide](docs/integrations/OPENROUTER.md) |\n| GitHub Copilot | Device flow with token refresh | [CLI and WebUI setup](docs/integrations/GITHUB_COPILOT.md) |\n| OpenAI Codex | PKCE browser flow | [CLI and WebUI setup](docs/integrations/OPENAI_CODEX.md) |\n| Claude | Existing subscription OAuth compatibility path; provider restrictions apply | [Requirements and caveats](docs/integrations/CLAUDE.md) |\n| Google Gemini CLI | PKCE browser flow, requires `SHIBACLAW_GEMINI_OAUTH_CLIENT_ID` and `SHIBACLAW_GEMINI_OAUTH_CLIENT_SECRET` env vars. **Note:** Unofficial third-party integration, Google may apply account restrictions. Use a separate account if this is a concern. | WebUI Settings |\n\nThe integration guides cover callback URLs, Docker networking, account limits and troubleshooting. A successful connection does not imply unlimited requests or access to every model.\n\n## Architecture\n\n

\n \"ShibaClaw\n

\n\n**Docker Compose**\n\n| Service | Role | Default port |\n|---|---|---|\n| `shibaclaw-gateway` | Core agent loop, message bus, channel integrations and automations | 19999 (HTTP) · 19998 (WS) |\n| `shibaclaw-web` | WebUI (Starlette + WebSocket), proxy to the gateway | 3000 |\n\nBoth mount the host's `./.shibaclaw/` data directory at `/root/.shibaclaw` for config, workspace, memory, automation jobs and media. Outside Docker, `shibaclaw web --with-gateway` starts the gateway as a managed background process. `shibaclaw web` alone expects a running gateway.\n\n**Stack** — Uvicorn/Starlette (ASGI), native WebSocket, vanilla JS + Marked.js + Highlight.js frontend, JSONL append-only sessions.\n\n**Container limits** — the supplied Compose file sets a 512 MB limit / 256 MB reservation for the gateway, and a 128 MB limit / 64 MB reservation for the WebUI. These are configuration limits, not measured memory requirements; RAG and local model servers need their own capacity planning.\n\n## CLI Reference\n\n```bash\nshibaclaw web # Start WebUI; requires a running gateway\nshibaclaw gateway # Start gateway only (for Docker split)\nshibaclaw onboard # CLI-based first-time setup wizard\nshibaclaw agent \"Hello\" # One-shot message via terminal\nshibaclaw agent # Interactive REPL with history\nshibaclaw status # Provider, workspace, OAuth health check\nshibaclaw channels status # List enabled channels\nshibaclaw provider login

# OAuth login (github-copilot, openai-codex)\nshibaclaw desktop # Launch Windows desktop app\n```\n\n## Channels\n\n| Channel | Type | Notes |\n|---|---|---|\n| WebUI | Built-in | Primary interface, full feature access |\n| Discord | Bot | Rich embeds, slash commands, attachments |\n| Telegram | Bot | Inline keyboards, media, reply markup |\n| WhatsApp | Plugin | Via WhatsApp Web |\n| Slack | Bot | Block kit, threads, app mentions |\n| DingTalk | Bot | Enterprise messaging |\n| Feishu/Lark | Bot | Rich cards, interactive elements |\n| QQ | Bot | Group & private messages |\n| WeCom | Bot | Workplace communication |\n| Matrix | Bot | Decentralized, E2E encryption |\n| MoChat | Bot | WeChat ecosystem |\n\nEach channel is configured independently in WebUI Settings and supports hot-reload on config changes.\n\n## Plugin System\n\nShibaClaw discovers plugins via Python entry points:\n\n- **Channel plugins** — implement `BaseChannel`, discoverable via `shibaclaw.integrations`\n- **TTS plugins** — implement `BaseTTS`, discoverable via `shibaclaw.tts`\n\nIncluded plugin projects: `shibaclaw-channel-whatsapp` (WhatsApp Web) and `shibaclaw-tts-supertonic` (local speech synthesis using Supertonic and ONNX Runtime). Manage plugin installation in WebUI Settings > Plugins. See the [plugin development guide](docs/PLUGINS_DEVELOPMENT_GUIDE.md) to build your own.\n\n## Text-to-Speech\n\nThe Supertonic plugin synthesizes speech locally and downloads its model assets on first use. Select the engine, voice and language in the WebUI audio settings. Available voices and languages depend on the installed Supertonic model; see the [plugin implementation](plugins/shibaclaw-tts-supertonic/shibaclaw_tts_supertonic/engine.py).\n\n## Automation & Scheduling\n\nSchedule one-shot, interval or cron tasks, or use heartbeat jobs that read a task file and decide whether to act. Manage jobs in the Automations panel; definitions and state persist in `automation.json`. Approval requirements and delivery destinations are configured per job. See the [automation skill](shibaclaw/skills/automation/SKILL.md) for examples of workflow automation.\n\n## Knowledge Base (RAG)\n\nOrganize documents into named collections (PDF, CSV, HTML, TXT, Markdown), upload via the WebUI, and search a FAISS index. The agent can call `knowledge_search`, or you can target a collection with `@kb:name`.\n\nInstall the optional document stack with `pip install shibaclaw[rag]`. For local embeddings, use `pip install \"shibaclaw[rag-local]\"`; the default local model is `all-MiniLM-L6-v2` and needs an initial model download. Cloud embedding providers require configuration and send document content to that provider.\n\n## Troubleshooting\n\n| Problem | Try |\n|---|---|\n| General status check | `shibaclaw status` |\n| Container logs | `docker logs shibaclaw-gateway` / `docker logs shibaclaw-web` |\n| WebUI won't connect | Verify port binding, then sign in again; first launch requires admin account creation |\n| Provider errors | `shibaclaw status` shows API key and OAuth state |\n| Login fails after upgrading from v0.9.5 | Run `shibaclaw reset-admin` |\n| Security policy | [`SECURITY.md`](./SECURITY.md) |\n\n---\n\n## Documentation and Contributing\n\nStart with the [documentation index](docs/README.md), [API reference](docs/API_REFERENCE.md), or [DeepWiki code guide](https://deepwiki.com/RikyZ90/ShibaClaw). To contribute, read [CONTRIBUTING.md](CONTRIBUTING.md) and the [contribution ideas](docs/CONTRIBUTING_IDEAS.md), including documentation, integrations, UI and tests.\n\nShibaClaw is licensed under [Apache 2.0](LICENSE).\n\nIf ShibaClaw is useful to you, consider [supporting its development on GitHub Sponsors](https://github.com/sponsors/RikyZ90).\n\n## What's New\n\n

\nv1.1.3 — 2026-10-27\n\n- **Provider endpoints** — Configure multiple independently named endpoints, including local servers without API keys; save and enable each endpoint separately.\n- **Model selection** — Find endpoints in chat and Agent settings, enter custom model IDs, and return a chat to its default model.\n- **Automation reliability** — Preserve approvals, delivery settings and task instructions while scheduling, editing and deleting jobs.\n\n
\n\n
\nv1.1.2 — 2026-10-25\n\n- **Security fixes** — Require patched `filelock` and `pypdf` for optional RAG support and refresh the locked `setuptools` dependency.\n- **Reliable delegation and project checks** — Background tasks keep their status across chat reconnects, distinguish execution from optional project verification, and show real exit codes, bounded logs, and check durations. See [project verification](docs/PROJECT_VERIFICATION.md) for setup.\n- **Chat rendering** — Restores final responses and missed messages accurately, keeps active input intact when a background result arrives, and renders task details safely on desktop and mobile.\n- **Windows installation** — The PowerShell command downloads the per-user setup, verifies its SHA256, and launches it. First-launch startup keeps the native window responsive while the local service starts.\n\n
\n\nSee the [changelog](CHANGELOG.md) for the full release history and [GitHub Releases](https://github.com/RikyZ90/ShibaClaw/releases) for downloads.\n"}