MateClaw: A Spring Boot Agent Runtime Behind an Approval Gate
🤖 MateClaw — Your second brain with Multi-Agent Orchestration, MCP Protocol, Skills & Memory, Dream, and Multi-Channel Support. Built on Spring AI Alibaba.
At a glance
- What is it?
- MateClaw is a Java 21 and Spring Boot 3.5 agent platform that separates digital employees from the engine executing their turns, offering a native StateGraph runtime or a managed DeepSeek Harness loop. Its pitch is governance: multi-user workspaces, approval-gated actions, an audit trail, and per-channel fault isolation.
- Who is it for?
- Adopt MateClaw if you are a Java or Spring shop that needs multi-user workspaces, approval-gated tool calls, and an audit trail, and you are willing to run the database and the JAR yourself. Do not adopt it if you want a single-user CLI assistant, if you cannot host Java 21 and a persistent store, or if your team has no appetite for configuring providers, channels, and runtime capabilities one by one.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly Java, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem MateClaw is aimed at: agents your IT department can approve
Most personal agent projects assume one operator, one machine, and one API key. The README states the contrast directly: other personal AI agents are built for one person, and MateClaw is positioned as the one an IT department can sign off on. That framing tells you who the target user is. It is not the individual developer who wants a terminal assistant. It is a team or an internal platform group that has to answer questions about who ran what, which credentials were used, and what happens when a chat platform goes down.
The features that follow from that audience are governance features, not capability features. Multi-user workspaces. Approval-gated sensitive actions. A full audit trail. Spring Boot Actuator health monitoring. Per-channel error isolation, which the README describes as keeping one chat platform's outage from taking down the rest. MateClaw also states that one JAR runs in your environment, that you control persisted data, and that task content is sent only to model, channel, or tool services you explicitly configure. Those are procurement arguments as much as engineering arguments.
The second audience is the Java team that already has Spring Boot in production and does not want to introduce a Python service just to run an agent loop. MateClaw is built on Spring AI Alibaba, runs on Java 21 and Spring Boot 3.5, and ships a Vue 3 console. For a shop with existing Spring operational tooling, that is a smaller step than adding a separate runtime with its own deployment story.
The AgentRuntimeProvider contract and what each runtime owns
The architectural centre of version 2.2.0 is the AgentRuntimeProvider contract, which separates an employee from the engine that runs its turn. This is the design decision worth understanding before anything else, because it determines what you can swap later without losing state.
The native runtime keeps ReAct, Plan-and-Execute, persistent Goals, and Team Runs inside MateClaw, implemented on a StateGraph engine. The DSH runtime, short for DeepSeek Harness, manages dsh-jsonrpc-agent as an authenticated child process. According to the README, DSH streams thinking, text, tool calls, usage, completion, and cancellation back as normalized runtime events. The division of responsibility is explicit: DSH owns the external agent loop, while MateClaw still owns the session, workspace, credentials, tools, approvals, messages, and UI projection.
That split is the interesting part. If it holds, an employee's identity, permissions, and conversation history survive a change of execution engine, because those live on the MateClaw side. The README claims runtime availability and capabilities are validated before startup, and that DSH can be installed, verified, connection-tested, enabled, or disabled from the console. Whether the normalization is lossless across both runtimes is not something the supplied material establishes, and it is the first thing I would probe if reasoning quality differed between the two paths.
Durable Goals: checkpointing long work across a restart
Persistent Goals are the feature that addresses a real failure mode in agent systems: a task that runs for hours and dies halfway. The README describes Goals as turning that work into bounded, recoverable segments, with the database preserving the goal checklist, continuation state, attempts, cooldowns, leases, and user input accepted while the worker is busy.
The recovery path is described for a single backend instance. After that instance restarts, a supervisor reconciles the interrupted attempt, reads persisted checkpoints and artifacts, and schedules the next segment. Note the scope: the material describes single-instance restart recovery. It does not describe multi-instance failover, leader election, or how leases behave when two backend instances are running against the same database. If you plan to run MateClaw behind a load balancer, that is an open question you should resolve from the documentation rather than assume.
The trade-off embedded here is storage. Checkpoints, artifacts, leases, and continuation state all live in a database, which means MateClaw is not a stateless container you can kill and recreate at will. Your backup and migration story now covers agent working state, not just configuration. That is a normal cost for durable execution, but it changes what operating MateClaw involves.
Provider failover and the cooldown window
MateClaw's first stated differentiator is resilience to model provider failure. The README lists the failure cases plainly: an expired primary key, a vendor returning 401, a network blip, a drained quota. Instead of surfacing an error card, MateClaw tries the next healthy provider in configured order and attempts to recover the current request, returning an error only when the chain is exhausted.
The supported options named in the README include DashScope, OpenAI, Anthropic, Gemini, DeepSeek, Kimi, Ollama, LM Studio, and MLX, with built-in and OpenAI-compatible entries. A provider health tracker parks a failing vendor in a cooldown window, which the README frames as avoiding wasted seconds on every turn. Configuration is described as dragging providers into priority order under Settings, with a health dashboard showing routing in real time.
Two things are worth flagging. First, failover across providers is not the same as equivalent output. A request recovered on a different model may produce different reasoning, different tool-call formatting, and different token accounting. The README does not describe any normalization of model behaviour across the chain, only of provider health and routing. Second, the cooldown window is a heuristic. A provider that fails one request and recovers in ten seconds will still sit parked for the duration of that window, and the material does not state how long the window is or whether it is configurable.
Getting it running: Java 21, the JAR, and the console settings that matter
The prerequisites are stated in the repository badges and README: Java 21 or later, Spring Boot 3.5, and a Vue 3 front end for the console. The README describes deployment as one JAR in your environment, and separately offers a Desktop build, an Electron application with a bundled JRE 21, which the README says needs no Java install.
The configuration surfaces named in the material are console-based rather than file-based. Providers are ordered by dragging them in Settings, with a Models section and a health dashboard. DSH has its own documented configuration path, linked from the README as the DeepSeek Harness documentation page. Runtime availability and capabilities are validated before startup, and DSH can be installed, verified, connection-tested, enabled, or disabled from the console. Spring Boot Actuator health monitoring is part of the operational story.
What the supplied README does not give is a literal install command, a docker-compose file, or a list of environment variables and config keys. That is a gap. For a project whose selling point is that IT can sign off on it, the absence of a copy-pasteable deployment section in the README means your first real step is the documentation site at claw.mate.vip/docs, not the repository front page. Treat the console as the primary configuration interface and expect to learn the provider, channel, and runtime settings there.
Where MateClaw is the wrong tool, and what to use instead
The clearest case against MateClaw is a single developer who wants an agent in a terminal. MateClaw is a Spring Boot service with a database, a web console, multi-user workspaces, and eight IM channel integrations. If you do not need workspaces, approval gates, or an audit trail, you are paying the operational cost of a platform for the capability of a script. Aider or a comparable local coding agent that operates directly on your working tree is a different shape of tool: no server, no database, no channel layer, and no governance model, because there is only one user to govern.
The more interesting comparison is against building on Spring AI directly, since MateClaw is itself built on Spring AI Alibaba. Spring AI gives you model clients, tool calling, and vector store integrations as a library. MateClaw gives you a runtime around them: the AgentRuntimeProvider contract, durable Goals with checkpoints and leases, Tool Guard, approval gates, event projection, and the channel adapters. The difference in approach is library versus platform. With Spring AI you write the loop, own the persistence, and decide what an approval means. With MateClaw that loop and its recovery semantics are already implemented, at the cost of adopting its data model and its console as the place where configuration lives. If your requirements are unusual, for example a novel approval workflow or a non-standard persistence layer, the platform's opinions will be in your way rather than saving you work.
A third boundary is the model-provider chain itself. If your organization mandates a single approved provider with no fallback, the failover routing described in the README buys you nothing and adds a configuration surface you have to keep correct.
Maintenance cost, release cadence, and the Apache-2.0 terms
The release history in the repository metadata shows v2.0.0 on 2026-07-31, v2.1.0 on 2026-08-17, and v2.2.0 on 2026-08-29, with the last push to the dev branch on 2026-09-08. Three minor releases in roughly a month is a fast cadence, and v2.2.0 introduces structural changes: the AgentRuntimeProvider contract, the DSH runtime, and durable Goals. Fast structural change means upgrade cost is not just dependency bumps. If you build on the runtime contract or on persisted goal state, you should expect to read release notes before every upgrade rather than pinning and forgetting.
The default branch is dev, not main, which is worth noting when you decide what to track. The repository is not archived.
On licensing: the repository is Apache-2.0 per the badge and the LICENSE file. Apache-2.0 is a permissive licence that typically allows commercial use, modification, and redistribution provided you retain the required notices and comply with its terms, and it includes a patent grant. I am not your lawyer and this is not legal advice. Two project-specific points to check in the actual LICENSE text rather than the badge: whether any bundled components, such as the Desktop Electron build or third-party model provider SDKs, carry different terms, and what obligations attach if you redistribute the JAR inside your own product. The README's claim that you control persisted data and that task content goes only to services you configure is a statement about architecture, not a contractual commitment, so treat it as a design property to verify in your own deployment.
Editorial conclusion
Adopt MateClaw if you are a Java or Spring shop that needs multi-user workspaces, approval-gated tool calls, and an audit trail, and you are willing to run the database and the JAR yourself. Do not adopt it if you want a single-user CLI assistant, if you cannot host Java 21 and a persistent store, or if your team has no appetite for configuring providers, channels, and runtime capabilities one by one. Before committing, verify three things against the docs at claw.mate.vip: which of the eight IM channels you actually need, whether the DSH runtime is a hard requirement or the native StateGraph engine is enough, and what the licence text in the LICENSE file says about your redistribution plans. The repository ships a live demo at claw-demo.mate.vip, which is the cheapest way to check the console before you install anything.
Community notes