mirror of
https://gitee.com/mateos/mateclaw.git
synced 2026-09-13 03:13:41 +08:00
3b11a3def6
Two related issues from the Kimi-401 user report:
1. Backend (NodeStreamingChatHelper): a primary AUTH_ERROR (e.g. Kimi 401
with an invalid API key) returned immediately without trying the
fallback chain — a fallback provider with a different, valid key
never got a chance. Even with DashScope correctly configured as the
fallback, the user chat dead-ended on a 401.
The original assumption ("auth never self-heals so do not retry")
holds for the primary same-model retry loop but is wrong for the
fallback chain — different providers have different keys. Apply the
same break-into-fallback policy that BILLING and MODEL_NOT_FOUND
already use. recordPrimary(false) is preserved so the cooldown
counter still accumulates.
2. Frontend (chatError.ts + i18n): the error-text matching for
/认证|auth|unauthorized|401/i was so broad it matched the substring
"auth" inside URLs like https://api.kimi.com/.../auth, classifying
any model 401 as user "session expired" and rendering the misleading
"页面将自动跳转到登录页" copy. (The redirect itself only fires from
/api/v1/auth/* axios paths and SSE-connection 401s, not from this
payload-text path — but the copy alone is the worst kind of false
alarm.)
Add a new ChatErrorCategory provider_auth_error and split the
pattern matching: narrow auth_expired (HTTP 401 / 登录已过期 /
session expired / 凭证失效) is matched FIRST, then the broad
401-ish pattern routes to provider_auth_error. BACKEND_ERROR_TYPE_MAP
for AUTH_ERROR is also remapped, since structured backend payloads
currently always come from LLM providers — never from our own
/api/v1/auth path.
Tests
- NodeStreamingChatHelperFailoverTest (5 cases): primary 401 →
fallback succeeds; chain skips auth-failing fallback to next healthy
one; whole-chain failure surfaces last AUTH_ERROR (no silent drop);
BILLING regression unchanged; primary-success path does not touch
chain
- Browser preview verified: new i18n keys resolve in en-US, classifier
correctly routes "[错误] 401 from kimi.com" → provider_auth_error
while "[错误] HTTP 401 from /api/v1/auth/ping" stays auth_expired
- 186 tests pass (was 181 + 5 new); vue-tsc clean
Do-not-touch list: handleAuthFailure() in useStream/api/index.ts (real
session-expiry path) is unmodified — only the misclassification
upstream is fixed. auth_expired i18n copy is unchanged.
|
||
|---|---|---|
| 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.