A personal AI assistant system built with Java + Vue 3, powered by Spring AI Alibaba. Features multi-agent orchestration, a flexible tool/skill system with MCP protocol support, multi-layer memory, and multi-channel adapters.
Core capabilities:
Multi-Agent Orchestration β ReAct (Thought β Action β Observation loop) and Plan-and-Execute (auto-decompose complex tasks into ordered sub-steps). Create multiple independent agents, each with their own personality and tools.
Tool & Skill System β Built-in tools (web search, date/time) + MCP protocol for external tool integration. Pre-configured GitHub and Filesystem MCP servers β enable and go. Install skill packages from ClawHub marketplace or custom sources.
Multi-Layer Memory β Short-term context window with auto-compression, event-driven post-conversation memory extraction, workspace files (PROFILE.md / MEMORY.md / daily notes), and scheduled memory consolidation.
Every Channel β Web console, DingTalk, Feishu, WeChat Work, Telegram, Discord, QQ. One MateClaw, connect as needed.
Multi-Provider Models β 20+ providers: DashScope, OpenAI, Anthropic, Google Gemini, DeepSeek, Kimi, MiniMax, Zhipu AI, Volcano Engine, OpenRouter, Ollama, LM Studio, llama.cpp, MLX, and more. Configure in the web UI.
Desktop App β Electron-based desktop application with auto-update support. Download and double-click to run.
- Quick Start
- Screenshots
- Architecture
- Tech Stack
- Features
- Documentation
- Roadmap
- Contributing
- Contact Us
- License
- Java 17+
- Node.js 18+ & pnpm
- Maven 3.9+ (or use
mvnw) - At least one LLM API Key (e.g., DashScope)
1. Start the backend
cd mateclaw-server
export DASHSCOPE_API_KEY=your-key-here
mvn spring-boot:run
# Backend runs at http://localhost:18088
# H2 Console: http://localhost:18088/h2-console
# API Docs (SpringDoc OpenAPI): http://localhost:18088/swagger-ui.html2. Start the frontend
cd mateclaw-ui
pnpm install
pnpm dev
# Frontend runs at http://localhost:5173 (proxies /api to :18088)3. Log in
Open http://localhost:5173 and log in with admin / admin123.
cp .env.example .env
# Edit .env β fill in DASHSCOPE_API_KEY and other variables
docker compose up -d
# Service runs at http://localhost:18080 (MySQL + backend)Download the installer from GitHub Releases:
| Platform | File | Notes |
|---|---|---|
| macOS (Apple Silicon) | MateClaw_<version>_arm64.dmg |
Recommended for M1/M2/M3/M4/M5 Mac |
| macOS (Apple Silicon) | MateClaw_<version>_arm64.zip |
zip format (Apple Silicon) |
| macOS (Intel) | MateClaw_<version>_x64.dmg |
For Intel-based Mac |
| macOS (Intel) | MateClaw_<version>_x64.zip |
zip format (Intel) |
| Windows (x64) | MateClaw_<version>_Setup.exe |
For most Windows PCs (64-bit) |
| Windows (x64) | MateClaw_<version>_x64_Setup.exe |
Explicit x64 build |
| Windows (ARM64) | MateClaw_<version>_arm64_Setup.exe |
For ARM-based Windows (e.g. Surface Pro X) |
Double-click to run. The app bundles JRE 21 + the Spring Boot backend, no Java installation needed. Supports auto-update via GitHub Releases.
macOS users: If macOS blocks the app, right-click β Open β Open again, or go to System Settings β Privacy & Security β Open Anyway.
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
| 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 |
- 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
- 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.mdmanifests - ClawHub Marketplace β Browse and install skills from the ClawHub registry
- Workspace Skills β Convention-based skill directory at
~/.mateclaw/skills/{name}/
- 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
- 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
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 |
- 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
- 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
| Topic | Description |
|---|---|
| Introduction | What MateClaw is and core concepts |
| Quick Start | Install and run (local, Docker, desktop) |
| Console | Web UI: chat and agent configuration |
| Agents | Agent engine: ReAct, Plan-and-Execute, StateGraph |
| Models | Configure cloud, local, and custom providers |
| Tools | Built-in tools and custom tool development |
| Skills | Skill packages and ClawHub marketplace |
| MCP | Model Context Protocol integration |
| Memory | Multi-layer memory system |
| Channels | DingTalk, Feishu, Telegram, Discord, and more |
| Security | Authentication and tool guard |
| Desktop | Desktop application guide |
| API Reference | REST API documentation |
| Configuration | Configuration reference |
| FAQ | Common questions and troubleshooting |
| 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.
MateClaw is open to contributions! Whether it's bug fixes, new features, documentation improvements, or new channel/tool integrations β all contributions are welcome.
# 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 devPlease read CONTRIBUTING.md (if available) before submitting a PR.
| Discord | X (Twitter) | DingTalk |
|---|---|---|
| Coming soon | Coming soon | Coming soon |
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.
MateClaw is released under the Apache License 2.0.