Your AI mate, always ready to lend a claw.
Your AI mate, always ready to lend a claw.
Chat console โ AI self-introduction with auto-generated ECharts donut chart
--- ## Architecture ``` mateclaw/ โโโ mateclaw-server/ # Spring Boot backend โ โโโ src/main/java/vip/mate/ โ โ โโโ agent/ # Agent engine (ReAct, Plan-and-Execute, StateGraph) โ โ โโโ planning/ # Task planning (Plan / SubPlan models) โ โ โโโ tool/ # Tool system (built-in + MCP adapters) โ โ โโโ skill/ # Skill management (workspace + ClawHub) โ โ โโโ channel/ # Channel adapters (Web, DingTalk, Feishu, etc.) โ โ โโโ workspace/ # Conversations, messages, workspace files โ โ โโโ memory/ # Memory extraction & consolidation โ โ โโโ llm/ # Multi-provider model configs โ โ โโโ cron/ # Scheduled tasks (CronJob) โ โ โโโ auth/ # Spring Security + JWT โ โ โโโ config/ # Spring bean configurations โ โโโ src/main/resources/ โ โโโ application.yml # Main config (H2 for dev) โ โโโ prompts/ # Prompt templates โ โโโ db/ # Schema & seed data (schema.sql, data.sql) โโโ mateclaw-ui/ # Vue 3 SPA frontend โ โโโ src/ โ โโโ views/ # Pages (ChatConsole, AgentWorkspace, SkillMarket, etc.) โ โโโ components/ # Reusable components โ โโโ stores/ # Pinia stores (domain-driven) โ โโโ api/ # Axios HTTP client โ โโโ router/ # Vue Router โ โโโ types/ # TypeScript types โ โโโ i18n/ # Internationalization (zh-CN, en-US) โโโ mateclaw-desktop/ # Electron desktop app โโโ docs/ # VitePress documentation (zh + en) โโโ docker-compose.yml โโโ .env.example ``` --- ## Tech Stack | Layer | Technology | |-------|-----------| | Backend Framework | Spring Boot 3.5 + Spring AI Alibaba 1.1 | | LLM Integration | DashScope, OpenAI, Anthropic, Gemini, DeepSeek, Kimi, MiniMax, Zhipu, Volcano Engine, OpenRouter, Ollama, LM Studio, llama.cpp, MLX | | Agent Engine | StateGraph (ReAct + Plan-and-Execute) | | Database | H2 (dev) / MySQL 8.0+ (prod) | | ORM | MyBatis Plus 3.5 | | Authentication | Spring Security + JWT | | API Docs | SpringDoc OpenAPI 3 | | Frontend | Vue 3 + TypeScript + Vite | | State Management | Pinia | | UI Components | Element Plus | | Styling | TailwindCSS 4 | | Desktop | Electron + electron-updater | | Docs Site | VitePress | --- ## Features ### Agent System - **ReAct Agent** โ Thought โ Action โ Observation reasoning loop with tool calling - **Plan-and-Execute** โ Auto-decompose complex tasks into ordered sub-steps with progress tracking - **Dynamic Agent** โ Load agent configs from database at runtime - **Multi-Agent** โ Create multiple independent agents, each with their own system prompt, tools, and personality ### Tool & Skill System - **Built-in Tools** โ Web search (Serper/Tavily), date/time, workspace memory read/write - **MCP Protocol** โ Connect external tools via Model Context Protocol (stdio, SSE, and Streamable HTTP transports). Full lifecycle management in the web UI โ add, edit, enable/disable, and test connections - **Pre-configured MCP Servers** โ GitHub (`@modelcontextprotocol/server-github`) and Filesystem ship out-of-the-box. Enable from the MCP management page and fill in your token โ no code changes needed - **Skill Packages** โ Install/uninstall skill packages with `SKILL.md` manifests - **ClawHub Marketplace** โ Browse and install skills from the ClawHub registry - **Workspace Skills** โ Convention-based skill directory at `~/.mateclaw/skills/{name}/` ### Memory System - **Short-Term** โ Conversation context window with auto-compression when token budget exceeded - **Post-Conversation Extraction** โ Event-driven async LLM analysis, writes to PROFILE.md / MEMORY.md / daily notes - **Memory Consolidation** โ Scheduled daily emergence (CronJob at 2:00 AM) merges daily notes into long-term memory - **Workspace Files** โ Per-agent AGENTS.md, SOUL.md, PROFILE.md, MEMORY.md, memory/*.md - **Agent Memory Tool** โ Agents can read/write their own workspace files during conversations ### Multi-Channel - **Web Console** โ SSE streaming with rich message rendering (Markdown, code, plans) - **DingTalk** โ Webhook + event subscription - **Feishu (Lark)** โ Webhook + event subscription - **WeChat Work** โ Callback API - **Telegram** โ Bot API with webhook - **Discord** โ Bot with slash commands - **QQ** โ QQ Bot API ### Model Providers Configure in the web UI (Settings โ Models). Supported providers: | Provider | Models | |----------|--------| | **Cloud Providers** | | | DashScope (Alibaba) | Qwen3.5-Max, Qwen3.5-Plus, Qwen3-Max, Qwen3-Plus, Qwen-Max, Qwen-Plus, Qwen-Turbo, Qwen-Long, DeepSeek-V3.2 | | ModelScope | Qwen3.5-122B-A10B, GLM-5 | | Aliyun Coding Plan | Qwen3.5-Plus, Qwen3-Coder-Next, GLM-5, GLM-4.7, MiniMax-M2.5, Kimi-K2.5 | | OpenAI | GPT-5.2, GPT-5, GPT-5-Mini, GPT-5-Nano, GPT-4.1, GPT-4.1-Mini, GPT-4.1-Nano, o3, o4-mini, GPT-4o | | Azure OpenAI | GPT-5, GPT-4.1, GPT-4o and more | | Anthropic | Claude Opus 4.6, Claude Sonnet 4.6 (via model discovery) | | Google Gemini | Gemini 3.1 Pro, Gemini 3 Flash, Gemini 2.5 Pro, Gemini 2.5 Flash, Gemini 2.0 Flash | | DeepSeek | DeepSeek-Chat, DeepSeek-Reasoner | | Kimi (Moonshot) | Kimi-K2.5, Kimi-K2-Thinking, Kimi for Coding (CN / International / Code) | | MiniMax | MiniMax-M2.7, MiniMax-M2.5 (International / China) | | Zhipu AI | GLM-5.1, GLM-5, GLM-5-Turbo, GLM-5V-Turbo (CN / International) | | Volcano Engine | Doubao-1.5-Pro-256K, Doubao-1.5-Lite, Doubao-1.5-Thinking-Pro, Doubao-1.5-Vision-Pro | | OpenRouter | GPT-5, Claude Opus 4.6, Gemini 2.5 Pro, Llama 4 Maverick, DeepSeek R1, and 200+ more | | **Local Providers** | | | Ollama | Qwen3, Gemma 4, Gemma 3, Llama 3.1, DeepSeek R1, Mistral (auto-detected on startup) | | LM Studio | Any locally-served model | | llama.cpp | Any locally-served model | | MLX (Apple Silicon) | Any locally-served model | ### Security - **Spring Security + JWT** โ Token-based authentication - **Tool Guard** โ Approval rules for sensitive tool operations - **File Validation** โ Path traversal prevention for workspace files - **Skill Security** โ Validation during skill installation ### Scheduled Tasks - **CronJob System** โ Create scheduled tasks with 5-field cron expressions - **Memory Consolidation** โ Auto-triggered daily for each agent - **Custom Tasks** โ Schedule any prompt to run periodically --- ## Documentation | Topic | Description | |-------|-------------| | [Introduction](https://mateclaw.mate.vip/en/intro) | What MateClaw is and core concepts | | [Quick Start](https://mateclaw.mate.vip/en/quickstart) | Install and run (local, Docker, desktop) | | [Console](https://mateclaw.mate.vip/en/console) | Web UI: chat and agent configuration | | [Agents](https://mateclaw.mate.vip/en/agents) | Agent engine: ReAct, Plan-and-Execute, StateGraph | | [Models](https://mateclaw.mate.vip/en/models) | Configure cloud, local, and custom providers | | [Tools](https://mateclaw.mate.vip/en/tools) | Built-in tools and custom tool development | | [Skills](https://mateclaw.mate.vip/en/skills) | Skill packages and ClawHub marketplace | | [MCP](https://mateclaw.mate.vip/en/mcp) | Model Context Protocol integration | | [Memory](https://mateclaw.mate.vip/en/memory) | Multi-layer memory system | | [Channels](https://mateclaw.mate.vip/en/channels) | DingTalk, Feishu, Telegram, Discord, and more | | [Security](https://mateclaw.mate.vip/en/security) | Authentication and tool guard | | [Desktop](https://mateclaw.mate.vip/en/desktop) | Desktop application guide | | [API Reference](https://mateclaw.mate.vip/en/api) | REST API documentation | | [Configuration](https://mateclaw.mate.vip/en/config) | Configuration reference | | [FAQ](https://mateclaw.mate.vip/en/faq) | Common questions and troubleshooting | --- ## Roadmap | Area | Item | Status | |------|------|--------| | **Agent** | Multi-agent collaboration and delegation | Planned | | **Agent** | Multimodal input (image, audio, video) | Planned | | **Models** | Small + large model routing | Planned | | **Memory** | Vector DB long-term memory (RAG) | Planned | | **Memory** | Multimodal memory fusion | Planned | | **Skills** | Richer ClawHub ecosystem | In Progress | | **Channels** | WeChat personal (iLink Bot) | Planned | | **Channels** | Email channel | Planned | | **Desktop** | Linux support | Planned | | **Security** | Multi-tenant support | Planned | | **Console** | Plugin marketplace in web UI | Planned | _Status:_ **In Progress** โ actively being worked on; **Planned** โ queued or under design. --- ## Contributing MateClaw is open to contributions! Whether it's bug fixes, new features, documentation improvements, or new channel/tool integrations โ all contributions are welcome. ```bash # Clone the repository git clone https://github.com/matevip/mateclaw.git cd mateclaw # Backend cd mateclaw-server mvn clean compile # Frontend cd ../mateclaw-ui pnpm install pnpm dev ``` Please read [CONTRIBUTING.md](https://github.com/matevip/mateclaw/blob/main/CONTRIBUTING.md) (if available) before submitting a PR. --- ## Contact Us | Discord | X (Twitter) | DingTalk | |---------|-------------|----------| | Coming soon | Coming soon | Coming soon | --- ## Why MateClaw? **Mate** โ a companion, always by your side. **Claw** โ sharp, capable, ready to grab any task. MateClaw is your personal AI mate that lends a claw whenever you need it. Built as a monolith with modular design, it's easy to deploy, extend, and customize. --- ## License MateClaw is released under the [Apache License 2.0](LICENSE).