6a3df2a6e0
Adds explicit user-intent gating to the provider catalog. Fresh installs
get an empty dropdown by default — built-in cloud + local providers
(OpenAI, Anthropic, Ollama, LM Studio, MLX, llama.cpp, etc.) live in a
new 'Add Provider' drawer until the user opts them in. Existing installs
upgrade conservatively: V55 promotes any provider with evidence of use
(real api_key, OAuth token, recent chat usage, or current default model).
Backend
- V55 migration (H2 + MySQL): adds enabled BOOLEAN DEFAULT FALSE on
mate_model_provider, plus 4 promote-to-true UPDATE rules. Also
CREATE INDEX idx_message_runtime_provider_time so the 30-day usage
lookup doesn't full-scan mate_message on heavy users.
- ModelProviderEntity, ProviderInfoDTO: enabled field.
- ModelProviderService:
* listProviders() now filters WHERE enabled = TRUE — chat path,
ModelSelector, Settings/Models main grid see only opted-in rows.
* listCatalog() new — full catalog (enabled + disabled) for the drawer.
* setEnabled(id, enabled) flips the flag, publishes
ModelConfigChangedEvent (re-probe via the existing listener), and
on disable auto-promotes a replacement default model when the
disabled provider owned the current default. Returns EnableResult
so the frontend can fire a toast.
* createCustomProvider sets enabled=true (user just made the row).
- ProviderInitProbe.listConfiguredProviders also filters enabled=true —
no point probing rows the user can't see.
- ModelConfigController: GET /catalog, POST /{id}/enable, POST /{id}/disable.
- Plugin-registered ChatModels are unaffected — they live in
pluginChatModels (in-memory map), don't go through DB listProviders,
so the enabled filter doesn't strand them.
Frontend
- New types: ProviderInfo.enabled, EnableResult.
- New API: catalog / enableProvider / disableProvider.
- New composable useProviderEnablement: catalog ref, drawerOpen,
togglingId, loadCatalog, openDrawer / closeDrawer, enableProvider,
disableProvider (fires defaultSwitchedToast on auto-switch).
- AddProviderDrawer.vue: lazy-loaded, reuses DoctorDrawer's Teleport +
overlay + slide-in panel pattern. Two groups (cloud / local),
unenabled rows surface to the top of each group, enabled rows show
an 'Enabled' badge instead of a button. Mobile: full-screen sheet
that slides up from below.
- ProviderCard: new 'Disable' button with soft-danger styling on
enabled providers — soft-hide that keeps the config; user can
re-enable from the drawer.
- Settings/Models index.vue:
* Two top CTAs: 'Enable Provider' (drawer) and 'Custom' (existing
custom-create modal) — distinct workflows, both surfaced.
* Empty state with prominent 'Enable Provider' CTA when zero
enabled providers — paired with onMounted auto-open of the
drawer (sessionStorage guard so closing it doesn't bring it
back on the next route visit in the same session).
* Deep-link: ?addProvider=1 query forces the drawer open and
strips itself after, so a back/forward doesn't re-fire the open.
- ModelSelector: when groups.length === 0 and not searching, show
'No providers configured -> Configure' CTA linking to
/settings/models?addProvider=1 — the natural flow when a fresh
user opens chat before configuring anything.
- i18n: 13 new keys per locale (zh-CN + en-US) plus common.close.
Migration safety
- Conservative default policy: only rows with concrete evidence of
use are auto-enabled; everything else stays hidden. Upgrade users
may notice unused built-ins disappearing from their dropdown —
that's the intended cleanup.
- mate_message index added so the 30-day usage rule doesn't full-scan
on large installations; FlywayRepairConfig handles redeploy idempotency.
Tests
- ModelProviderServiceEnableTest covers all 7 enable/disable branches:
flag flip + event publish, no-op on already-{enabled,disabled},
default-switch when disabled provider owned current default,
no-switch when default belongs elsewhere, no-replacement returns
unchanged, getDefaultModel exception path, candidates with no
models are skipped.
- ProviderInitProbeTest: helper provider() now sets enabled=true so
the new probe filter doesn't strand existing fixtures.
- vip.mate.llm.** suite: 125 tests green. vue-tsc 0 errors. Browser
page renders with both new buttons + drawer.
|
||
|---|---|---|
| assets | ||
| docker/searxng | ||
| 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 | ||
Most AI tools die when their vendor has a bad day. Most forget you the moment the tab closes. Most give you a chatbox and call it a product.
MateClaw is the whole widget. One deployment. Reasoning, knowledge, memory, tools, channels — built together, not bolted on. And when your primary model goes down, the next one picks up mid-sentence.
Three things that make it different
1 · Your AI doesn't die when a model does
Primary key expired. Vendor returns 401. Network blip. Quota drained.
Other tools hand you a red error card. MateClaw routes to the next healthy provider — DashScope, OpenAI, Anthropic, Gemini, DeepSeek, Kimi, Ollama, LM Studio, MLX, 14+ in total — and the user sees the reply finish. A provider health tracker parks bad vendors in a cooldown window so they don't waste seconds on every turn.
You don't write a retry script. You drag providers into priority order in Settings → Models and watch the health dashboard fill with green dots as requests route around failures in real time.
2 · Knowledge that links itself
Upload a PDF, a batch of markdown, a scraped page — raw material in.
MateClaw's LLM Wiki digests it into structured pages, builds [[links]] between them, and remembers where every sentence came from. Click a citation, see the exact source chunk. Ask a question, the page you get is stitched from the right chunks — with references you can verify.
This is the difference between a warehouse and a library.
3 · One product, five surfaces
| Surface | What it is |
|---|---|
| Web Console | Full admin — agents, models, tools, skills, knowledge, security, cron |
| Desktop | Electron app with a bundled JRE 21. Double-click, run. No Java install |
| Webchat Widget | One <script> tag embed. Drop it on any site |
| IM Channels | DingTalk · Feishu · WeChat Work · Telegram · Discord · QQ |
| Plugin SDK | Java module for third-party capability packs |
Same brain. Same memory. Same tools. Different doors.
$0 · No tokens metered. No seats billed. Your server. Your data. Your keys.
What's in the box
Agent runtime
ReAct for iterative reasoning. Plan-and-Execute for complex multi-step work. Dynamic context pruning, smart truncation, stale-stream cleanup — the boring stuff that makes long conversations actually work.
Knowledge & memory
- LLM Wiki — raw materials digest into linked pages with citations
- Workspace memory —
AGENTS.md,SOUL.md,PROFILE.md,MEMORY.md, daily notes - Memory lifecycle — post-conversation extraction, scheduled consolidation, dreaming workflows
Tools, skills, MCP
Built-in tools for web search, files, memory, date/time. MCP over stdio / SSE / Streamable HTTP. SKILL.md packages from the ClawHub marketplace. A Tool Guard layer with RBAC, approval flows, and path protection — capability needs boundaries.
Multimodal creation
Text-to-speech · Speech-to-text · Image · Music · Video. First-class, not add-ons.
Enterprise-ready
RBAC + JWT. Full audit trail. Flyway-managed schema that auto-heals on upgrade. One JAR to ship. MySQL in production, H2 for dev — nothing to change in your code.
AI is becoming infrastructure
On March 2, 2026, Claude went dark for 4 hours across API, web, and mobile. Three weeks later, another 5 hours. Every company that bet their AI strategy on a single vendor spent those outages staring at red error cards.
This is the same shift databases went through around 2010 and cloud went through around 2018: the winning layer stops being tied to one supplier. 57% of companies now run AI agents in production. None of them want one vendor's bad day to become their bad day.
MateClaw is that layer — built the Spring Boot way.
Why MateClaw
| MateClaw | OpenClaw | Hermes Agent | Claude Code | Cursor | |
|---|---|---|---|---|---|
| Multi-vendor failover | Chain + health tracker + cooldown | Swap providers via config | Orchestration w/ retry | Anthropic only | One model |
| Knowledge digestion | LLM Wiki + page-level citations | Canvas + memory | Skills Hub + memory | — | Code index |
| Multi-user admin | RBAC + approval flow + audit | Config-file first | Single-user CLI | Enterprise tier | Teams plan |
| Surfaces | Web admin + Desktop + Widget + SDK + 6 IM | 25+ chat channels | 15+ channels (CLI-led) | 3 IM preview | IDE only |
| Stack | Java (Spring Boot) | TypeScript | Python | TypeScript | Electron/TS |
| License / Price | Apache 2.0 · Free | MIT · Free | MIT · Free | Proprietary · $20–200/mo | Proprietary · $0–200/mo |
OpenClaw and Hermes Agent are excellent personal AI platforms — pick either if you're running one user on one laptop, building your own agent from CLI, and treating everything as config files to hand-tune. Both have bigger communities than MateClaw today.
MateClaw is the version built for teams. RBAC per agent, per model, per tool. An approval flow that pauses risky actions for review. Full audit trail. A web admin dashboard where one operator manages 50 agents across 14 vendors. Spring Boot inside — drop-in for any Java shop already running production services.
Same "whole widget" philosophy. Different center of gravity.
Quick start
# 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
Download from GitHub Releases. Bundles JRE 21. No Java install needed.
Architecture
Technical architecture
Project structure
mateclaw/
├── mateclaw-server/ Spring Boot 3.5 backend (Spring AI Alibaba, StateGraph runtime)
├── mateclaw-ui/ Vue 3 + TypeScript admin SPA (built into the server JAR)
├── mateclaw-webchat/ Embeddable chat widget (UMD / ES bundles)
├── mateclaw-plugin-api/ Java SDK for third-party capability plugins
├── mateclaw-plugin-sample/ Reference plugin implementation
├── docker-compose.yml
└── .env.example
Desktop binaries ship via GitHub Releases with a bundled JRE 21 — no Java install needed.
Tech stack
| Layer | Technology |
|---|---|
| Backend | Spring Boot 3.5 · Spring AI Alibaba 1.1 · MyBatis Plus · Flyway |
| Agent | StateGraph runtime · ReAct + Plan-Execute |
| Database | H2 (dev) · MySQL 8.0+ (prod) |
| Auth | Spring Security + JWT |
| Frontend | Vue 3 · TypeScript · Vite · Element Plus · TailwindCSS 4 |
| Desktop | Electron · electron-updater · JRE 21 (bundled) |
| Widget | Vite library mode · UMD + ES bundles |
Documentation
Full docs at claw.mate.vip/docs — setup, architecture, each subsystem, API reference.
Roadmap
Sharper multi-agent collaboration · Smarter model routing · Deeper multimodal understanding · Longer-lived memory · A richer ClawHub.
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.
Something that stays with you — and grabs work and moves it.
License
Apache License 2.0. No asterisks.