mirror of
https://gitee.com/mateos/mateclaw.git
synced 2026-09-13 03:13:41 +08:00
7ba8fe602b
Track the primary model health, not just fallback entries - NodeStreamingChatHelper accepts primaryProviderId via a new 5-arg constructor; AgentGraphBuilder passes ModelConfigEntity.getProvider() - Before the 5-retry primary loop, check healthTracker.isInCooldown(primaryProviderId): if true, log + broadcast "主模型暂时不可用（冷却中），直接尝试备选模型..." and short-circuit straight to the fallback chain. Prevents a degraded primary from burning 30+ seconds of backoff on every conversation turn. - recordPrimary(success/failure) now fires on every primary verdict — AUTH, BILLING, MODEL_NOT_FOUND, EMPTY_RESPONSE, generic UNKNOWN, and the explicit success path. Three consecutive failures push the primary provider into cooldown automatically. - Legacy 1/2/3-arg constructors leave primaryProviderId null; tracking silently disables for them so existing tests/wiring keep working. Split BILLING and MODEL_NOT_FOUND out of CLIENT_ERROR / AUTH_ERROR - BILLING (HTTP 402, "insufficient_quota", "credit balance is too low", "billing_hard_limit_reached", "quota exceeded"): payment failure on primary does not kill the call — a different provider may have credits. Skips same-model retries and heads to fallback chain. - MODEL_NOT_FOUND (HTTP 404, "Model not exist", "model_not_found", DashScope "[InvalidParameter] url error"): unknown model id will not start working on retry. Was previously misclassified as CLIENT_ERROR and terminated the whole call; now routes to fallback so a different provider can attempt with its default model. - classifyError ordering matters: BILLING / MODEL_NOT_FOUND are matched BEFORE the generic 400 / Bad Request branch, otherwise they would be swallowed by CLIENT_ERROR. Tests - ErrorClassificationTest: 11 tests, covers multi-vendor error phrasing for both new types + regression checks that 401 / 429 / 400 still classify as before - NodeStreamingChatHelperFallbackChainTest: +2 tests verifying primaryProviderId persistence on the new constructor and null on legacy ones - 181 tests pass (was 168 + 13 new) |
||
|---|---|---|
| assets | ||
| mateclaw-plugin-api | ||
| mateclaw-plugin-sample | ||
| mateclaw-server | ||
| mateclaw-ui | ||
| mateclaw-webchat | ||
| .dockerignore | ||
| .env.example | ||
| .gitignore | ||
| docker-compose.yml | ||
| LICENSE | ||
| README_zh.md | ||
| README.md | ||
| UPGRADING.md | ||
MateClaw
Build AI that thinks, acts, remembers, and ships.
[Website] [Live Demo] [Documentation] [中文]
An AI agent. A knowledge engine. A memory system. A tool runtime. A multi-channel presence.
One product. The whole widget.
MateClaw is a personal AI operating system built with Java + Vue 3, powered by Spring AI Alibaba. It's not a chatbox, not a workflow builder, not just another coding assistant. It's the entire system — from reasoning to remembering to shipping — in one deployment.
Three things make it insanely different:
- Agents do work, not just talk — ReAct + Plan-and-Execute. Not one-shot answers — iterative reasoning that actually completes tasks
- Knowledge is shaped, not just stored — An LLM Wiki that digests raw material into structured, linked pages. The difference between a warehouse and a library
- End-to-end, no compromises — Web console, desktop app, 7 IM channels, tool guardrails, enterprise auth. One team, one deployment, one experience
Why MateClaw
Most AI tools do one thing well. MateClaw does the whole thing.
| Capability | MateClaw | OpenClaw | CoPaw | QClaw | Claude Code | Cursor | Windsurf |
|---|---|---|---|---|---|---|---|
| Agent Orchestration | ReAct + Plan-Execute | Multi-agent teams | Multi-agent collab | Specialist agents | Agent Teams + subagents | Background Agents (cloud VM) | Cascade engine |
| Knowledge System | LLM Wiki (digestion) | Intelligence Mode + Wiki | Personal KB | Knowledge graph | CLAUDE.md (no RAG) | Codebase indexing | No |
| Memory | Extract + Consolidate + Dream | SQLite + Dreaming + Wiki | ReMe (hybrid retrieval) | 3-layer memory | 3-layer (CLAUDE.md + auto + files) | No persistent memory | Memories (~48h learning) |
| Tool Guard & Approval | RBAC + approval flow | HITL + risk levels | No | No | Permissions + Sandbox + Hooks | No | Turbo Mode (auto-approve) |
| Multi-Channel IM | 7 channels | 25+ channels | 7 channels | 5 channels | 3 channels (preview) | IDE only | IDE only |
| Web Management UI | Full admin dashboard | Control UI | Console UI | Dashboard | Enterprise dashboard | No | No |
| Desktop App | Electron + bundled JRE | macOS menu bar | Electron (Beta) | Win/Mac app | Claude Desktop (Mac/Win) | VS Code fork | VS Code fork |
| Multimodal Creation | TTS/STT/Img/Music/Video | TTS/Video/Music/Image | Vision input | No | Vision input only | No | No |
| Skill Ecosystem | ClawHub marketplace | ClawHub registry | Python skills | Templates | 340+ plugins, 1300+ skills | MCP marketplace | MCP one-click |
| Enterprise Auth | RBAC + JWT | Basic (password) | Basic auth | No | SSO/SCIM/RBAC | SSO + Teams | Teams plan |
| Open Source | Apache 2.0 | MIT | Apache 2.0 | Partial | No (source-available) | No | No |
| Pricing | Free | Free | Free | Free (beta) | $20–200/mo | $0–200/mo | $0–200/mo |
| Tech Stack | Java + Vue 3 | TypeScript | Python + TS | OpenClaw fork | TypeScript | Electron (VS Code) | Electron (VS Code) |
What makes MateClaw different?
Every product in this table is genuinely strong. Here's where MateClaw carves its own space:
- Plan-and-Execute orchestration — Break complex work into ordered steps, execute each, adapt mid-flight. Others have multi-agent, but structured task planning with dynamic replanning is rare
- LLM Wiki that digests, not just retrieves — Others index and search. MateClaw's Wiki turns raw material into structured, linked pages with summaries — a search engine vs. an encyclopedia
- Java ecosystem — Built for teams already running Spring Boot in production. One JAR, one deploy. No Python runtime, no Node.js dependency chain
- Complete admin dashboard — Agents, models, tools, skills, channels, security, cron jobs, token usage — all in one web UI. Not a CLI-first afterthought
- Full multimodal creation — TTS, STT, image, music, and video generation as first-class built-in features. OpenClaw matches here; most others don't
- Free and open, no asterisks — Apache 2.0. No token billing, no seat pricing, no feature gating. Claude Code starts at $20/mo, Cursor and Windsurf up to $200/mo
Architecture
Technical Architecture
Core Capabilities
Agent Runtime
- ReAct agents — Think, act, observe, repeat. Iterative reasoning that gets things done
- Plan-and-Execute — Decompose complex work into ordered steps, then execute each one
- Dynamic configuration — Load agent personality, tools, and constraints from the database at runtime
- Runtime resilience — Context pruning, smart truncation, stale stream cleanup, and recovery
Knowledge & Memory
- LLM Wiki — AI-powered knowledge base that digests raw materials into structured, linked pages with summaries
- Workspace memory —
AGENTS.md,SOUL.md,PROFILE.md,MEMORY.md, daily notes - Memory lifecycle — Post-conversation extraction, scheduled consolidation, dreaming workflows
- Compound memory — Understanding improves over time instead of resetting every query
Tools, Skills & MCP
- Built-in tools — Web search, file ops, memory access, date/time, and more
- MCP integration — stdio, SSE, and Streamable HTTP transports
- Skill system — Installable
SKILL.mdpackages with ClawHub marketplace - Tool guard — Approval flows, file-path protection, runtime filtering
Multimodal Creation
Text-to-speech · Speech-to-text · Image generation · Music generation · Video generation
Model Flexibility
14+ providers including DashScope, OpenAI, Anthropic, Gemini, DeepSeek, Kimi, Ollama, LM Studio, MLX, and more. Configure everything in the web UI.
Surfaces
- Web console — Chat, agents, tools, skills, knowledge, models, security, settings
- Desktop app — Electron with bundled JRE 21, no Java installation needed
- Channels — DingTalk, Feishu, WeChat Work, Telegram, Discord, QQ
Quick Start
Prerequisites
- Java 17+ · Node.js 18+ · pnpm · Maven 3.9+
Local Development
# Backend
cd mateclaw-server
mvn spring-boot:run # http://localhost:18088
# Frontend
cd mateclaw-ui
pnpm install && pnpm dev # http://localhost:5173
Login: admin / admin123
Docker
cp .env.example .env
docker compose up -d # http://localhost:18080
Desktop App
Download from GitHub Releases. Bundles JRE 21 — no Java needed.
Tech Stack
| Layer | Technology |
|---|---|
| Backend | Spring Boot 3.5 · Spring AI Alibaba 1.1 |
| Agent | StateGraph Runtime |
| Database | H2 (dev) / MySQL 8.0+ (prod) |
| ORM | MyBatis Plus 3.5 |
| Auth | Spring Security + JWT |
| Frontend | Vue 3 · TypeScript · Vite |
| UI | Element Plus · TailwindCSS 4 |
| Desktop | Electron · electron-updater |
Project Structure
mateclaw/
├── mateclaw-server/ Spring Boot backend
├── mateclaw-ui/ Vue 3 SPA frontend
├── mateclaw-desktop/ Electron desktop app
├── docker-compose.yml
└── .env.example
Documentation
Full docs at claw.mate.vip/docs
Roadmap
- Richer multi-agent collaboration
- Smarter model routing
- Deeper multimodal understanding
- Stronger long-term memory
- Richer ClawHub ecosystem
Contributing
git clone https://github.com/matevip/mateclaw.git
cd mateclaw
cd mateclaw-server && mvn clean compile
cd ../mateclaw-ui && pnpm install && pnpm dev
Why The Name
Mate is companion. Claw is capability.
A system that stays with you, and a system that grabs work and moves it.