mateaix/mateclaw

MateClaw – An Enterprise‑grade AI Agent Platform

What it is – MateClaw is a self‑hosted, Java‑based platform that lets teams create, run, and manage “digital employees”. Each employee is an AI‑driven agent with a role, goal, back‑story and a set of tools it can call. The system bundles a full backend (Spring Boot 4, Spring AI, AgentScope) and a Vue‑based admin UI, plus optional desktop, web‑widget and IM‑channel clients.

Key capabilities

• Multi‑vendor model fail‑over – configure a priority list of LLM providers (OpenAI, Anthropic, Gemini, DeepSeek, Ollama, etc.). If the primary model is unavailable the request is automatically routed to the next healthy provider, with health tracking and cooldown.
• LLM‑Wiki knowledge base – upload PDFs, markdown, web pages, etc.; the system parses them into linked wiki pages with citations that are injected into the agents’ prompts.
• Persistent, checkpointed goals – long‑running tasks are stored in the database; after a crash the runtime resumes from the last checkpoint and only completes a goal when all verification checks pass.
• Team runs & workflow DSL – compose multiple agents and system actions (approval, channel dispatch, write‑memory) into a JSON‑first workflow with seven step modes (sequential, fan‑out, conditional, etc.).
• Extensible tooling – SKILL.md packages, MCP (stdio/SSE/HTTP) and ACP bridges let you add custom tools or plug in external coding agents like Claude Code.
• Enterprise features – RBAC, JWT, personal access tokens, audit trail, distributed cron lock, Flyway‑managed schema, and per‑channel error isolation.
• Multiple front‑ends – web admin console, Electron desktop app (bundled JRE 21), embeddable chat widget, and integrations for DingTalk, Feishu, WeChat Work, Telegram, Discord, Slack, etc.

How it works

1. Agent runtime – either the native Java AgentScope loop (ReAct, plan‑and‑execute) or an external DSH JSON‑RPC runtime. Both expose the same event model (thinking, tool use, answer, usage, cancellation).
2. Workspace – each team has a workspace directory; uploaded material is digested into the LLM‑Wiki and stored in the database.
3. Execution – when a user sends a request, the chosen agent runs, may call tools via the Tool Guard (RBAC + approval), and updates its memory files (MEMORY.md, PROFILE.md, etc.). Long tasks are checkpointed; a supervisor service reconciles interrupted runs after a restart.
4. Observability – the Admin Runtime Console shows live status of every employee, token usage, and lets operators force‑recycle stuck runs.

Getting started

• Run the backend with Maven (mvn -pl mateclaw-server spring-boot:run) and the Vue UI (npm install && npm run dev).
• Or use the provided Docker Compose (docker compose up -d).
• Desktop binaries are available as a single JAR with an embedded JRE.

Target audience – Java‑centric enterprises that need a centrally governed AI‑agent layer, multi‑user access, auditability, and the ability to survive model outages. It is not a simple chatbot; it is an extensible “second brain” platform for building AI‑powered digital coworkers.

---

TL;DR – MateClaw = self‑hosted, Spring‑Boot‑based AI‑agent runtime with multi‑model fail‑over, knowledge‑base ingestion, persistent goals, workflow orchestration, and enterprise‑grade security, exposed via web, desktop, widget and many IM channels.