mateclaw

3.0.0 — Governed execution, recoverable long tasks and team delivery. Java 21, Spring Boot 4, Spring AI 2 and AgentScope 2 power the native runtime. Consistent context budgets, final-answer checks and team synthesis strengthen delivery while preserving approvals and workspace boundaries. Release and upgrade notes. Release date: 2026-10-26.

Other personal AI agents are built for one person. MateClaw is the one your IT department can actually sign off on.

Multi-user workspaces. Approval-gated sensitive actions. Full audit trail. Spring Boot Actuator health monitoring. Per-channel error isolation so one chat platform’s outage doesn’t take down the rest. One JAR in your environment; you control persisted data, and task content is sent only to model, channel, or tool services you explicitly configure.

And underneath, a real Agent Runtime. An employee is no longer welded to one reasoning loop. Choose the native AgentScope runtime for ReAct, Plan-and-Execute, Goals, and Team Runs, or run DeepSeek Harness as a managed external loop over SDK JSON-RPC. Both paths converge on the same conversations, workspace boundaries, Tool Guard, event projection, and lifecycle controls.

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 is unavailable, the next healthy provider retries the current request.

What changes in 3.0.0

3.0.0 includes the unpublished 2.4.0 development cycle. Release date: 2026-10-26. Download published packages from Releases.

• Native execution: AgentScope Java 2.0.4 runs ReAct and the tool loop within each Plan-Execute step. MateClaw retains plan scheduling, tool approvals, workspace permissions, cancellation, Goal acceptance and persistence. This path does not require a beta AgentScope Harness API.
• Consistent context budgets: request preparation, compaction retries and summary calls account for messages, effective tool schemas and one output reserve. Partial request options inherit model defaults; an explicitly empty tool list disables inherited callbacks. Estimates are conservative, rather than provider billing counts.
• Governed decisions and recovery: typed decisions default to SHADOW mode; existing domain constraints and Goal budgets still apply. Durable checkpoints block blind replay when side effects are uncertain.
• Long tasks and team delivery: unfinished work can continue within runtime limits, requests needing user input wait for a reply, and Team Runs publish completion after final synthesis. Worker progress preserves full results and failure causes.
• Everyday improvements: opt-in strict member file isolation, managed DSH SDK upgrades, voice selection/preview, structured MCP results and stricter model probes.

Use Java 21 for source builds. Back up the database, workspace, plugins and configuration before migration; use that backup for rollback. Architecture and upgrade notes · Model budget rules

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 tries the next healthy provider in configured order — including built-in and OpenAI-compatible options such as DashScope, OpenAI, Anthropic, Gemini, DeepSeek, Kimi, Ollama, LM Studio, and MLX — and attempts to recover the current request. It returns an error only when the available chain is exhausted. 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 preserves traceable citations for generated content. Open the citation drawer to inspect the corresponding source chunk and verify page or answer references.

This is the difference between a warehouse and a library.

3 · One product, five surfaces

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

Digital employees, not chatbots

You hire coworkers, not chat boxes. Each one has a Role, a Goal, a Backstory, a runtime, a pixel-art avatar, and a color of their own — six built-in templates ship ready (General Assistant · Product Assistant · Research Analyst · Customer Support · Data Analyst · Code Reviewer). Employee identity and governance stay stable even when the execution engine changes.

Agent Runtime: native or DSH (2.2.0+)

The AgentRuntimeProvider contract separates an employee from the engine that runs its turn. The native runtime keeps ReAct, Plan-and-Execute, persistent Goals, and Team Runs inside MateClaw. The DSH runtime launches the official dsh --profile sdk CLI and normalizes its thinking, text, tools, usage, completion, and cancellation events. Managed installation pins 0.2.0-rc.1 (alternative: 0.1.7-rc.2) with reviewed npm locks and Node.js 22. An opt-in 0.2.1-rc.2 candidate adds SDK compatibility updates; macOS arm64 installation, handshake and short real-model/tool checks passed, while default selection stays unchanged. Upgrades copy runtime homes, check the candidate, and switch a retained generation; rollback restores the previous home/configuration without merging newer sessions. Package and real-model adapter checks passed on macOS arm64; Linux x64 and persisted V3→V4 history migration remain unverified. Configure DeepSeek Harness →

Durable long tasks: checkpoint, restart, continue (2.2.0+)

Persistent Goals turn work that takes hours into bounded, recoverable segments. The database preserves the goal checklist, continuation state, attempts, cooldowns, leases, and user input accepted while the worker is busy. After a single backend instance restarts, the supervisor reconciles the interrupted attempt, reads persisted checkpoints and artifacts, and schedules the next safe segment instead of asking you to repeat the task.

For file-producing work, ask the employee to keep a progress ledger, append small verifiable units, inspect the existing tail after recovery, and complete the Goal only after reproducible acceptance checks pass. The runtime does not promise exactly-once behavior for arbitrary external side effects; payments, sends, publishes, and destructive calls still need provider idempotency or review. Run and verify durable Goals →

Prompt pattern: “Create a persistent Goal first. Save the plan and progress in the workspace, write in small checkpoints, resume from existing evidence after errors or restart, and call completeGoal only after every criterion has verifiable evidence.”

Team Runs (2.1.0+)

One request, one durable Team Run. A stable runId links the user’s objective, task DAG, worker executions, final synthesis, and deliverables. Chat is the outcome surface, Agents Live groups the workers for real-time observation, and Teams owns history and governance — all three consume the same server projection. Worker conversations no longer flood the normal sidebar; summaries and files lead, while tasks, evidence, approvals, and read-only worker records drill down on demand. Underneath, the 2.0 shared board still provides dependency orchestration, parallel dispatch, prerequisite hand-off, execution leases, cancel-interrupt, and human approval gates.

Knowledge & memory

• LLM Wiki — raw materials digest into linked pages with citations; the hot cache auto-injects into every employee’s system prompt. Transformations engine (1.3.0+) turns the Wiki from a search index into a processing pipeline
• Workspace memory — AGENTS.md, SOUL.md, PROFILE.md, MEMORY.md, daily notes
• Memory lifecycle — post-conversation extraction, scheduled consolidation, Dreaming workflows. Workflows can also write directly into an employee’s MEMORY.md via the write_memory step

Skills · MCP · ACP — three ways to extend capability

• SKILL.md packages — manifest + prompt + tool list + LESSONS.md. In 2.1, reflection and cross-session recurring-request mining can produce reusable improvements; routine promotion, constrained auto-binding, curator handover/governance, origin policy, snapshots, and restore points keep evolution observable, workspace-scoped, and reversible. Eight starter templates plus a five-step creation wizard, with Pre-flight checks before install
• MCP — stdio / SSE / Streamable HTTP, plug into any external tool server. Per-employee binding (1.3.0+) means a tool you install for one employee doesn’t bleed into another’s toolbox
• ACP — bring top-tier coding agents like Claude Code and Codex in as employees, auto-bridged to skill cards with wrapper tools
• Tool Guard — RBAC + approval flow + path protection. Capability needs boundaries

Business orchestration (1.3.0+)

• Workflow — compose multiple employees plus system actions (approval / channel dispatch / write-memory) into a publishable, triggerable, replayable linear DSL. Seven step modes (sequential / fan_out / collect / conditional / await_approval / dispatch_channel / write_memory). JSON-first authoring with Monaco + schema validation, or natural-language → draft generation
• Triggers — wire system events to workflows or to employee conversations. Six pattern types (cron / webhook / channel_message / agent_lifecycle / content_match / workflow_completion). Default-on event governance: dedup, per-trigger rate limit, bot-self filter, recursion guard, fail-closed unknown patterns
• Wiki Transformations — Wiki stops being retrieval-only. User-authored templates run against raw materials or existing pages, with cross-material map-reduce aggregation, reverse-citation extraction, JSON output mode, and per-template model picker

You see what every employee is doing

Admin Runtime Console (Settings → System → Runtime) — who’s running, which runtime provider owns the turn, what step it is on, how many tokens it uses, and one-click force-recycle when stuck. Native and DSH events enter the same thinking / tool / answer projection; completion, failure, usage, and cancellation retain consistent lifecycle semantics. Per-event SSE IDs make reconnects safe, and Team Runs group member work under one live execution.

Multimodal creation

Text-to-speech · Speech-to-text · Image · Music · Video · 3D. First-class, not add-ons. Sidecar routing (1.3.0+) means a text-only main model + an image attachment no longer dead-ends — a configured vision model describes the image, and the main model answers. Image edit lands too: refer to an earlier conversation attachment by msg:<id>:<idx> and ask the model to recolor or restyle it. Four document-generation tools (DocxRenderTool / XlsxRenderTool / PptxRenderTool / PdfRenderTool) render Markdown straight to Office files inside the JVM — no subprocess, no Office install.

Content Studio (1.8.0+)

A flagship scene, not a tool — a seeded “Content Studio” employee turns one sentence into a publishable post: pick-topic → research → draft → illustrate → de-AI → lay out → deliver. WeChat Official Account (公众号) articles land in your draft box as inline-style HTML with body images uploaded into WeChat; Xiaohongshu (小红书) notes package as ≥3 vertical 3:4 cards with an online preview. De-AI-ification runs against a measurable AI-trace score; every delivery is compliance-scanned and logged to a content calendar that dedups by topic fingerprint.

Enterprise-ready

RBAC + JWT. Personal Access Tokens for headless scripts and CI. HMAC-SHA-256 outbound webhook signing. Distributed Cron lock so multi-instance deployments don’t double-fire. Full audit trail. Flyway-managed schema. One JAR to ship. H2 for development; the public Docker stack defaults to PostgreSQL 16, the MySQL profile remains supported, and the Kingbase driver is opt-in.

AI is becoming infrastructure

Model providers rate-limit, networks fail, keys expire, and services become temporarily unavailable. Betting every AI capability on one provider turns an upstream incident into your own outage.

Once AI enters production, the stable layer should not be tied to one model supplier or one Agent loop. MateClaw absorbs model uncertainty through provider priorities, health tracking, cooldown, and failover, then places native and external execution engines behind one governed Agent Runtime contract.

MateClaw is that layer — built the Spring Boot way.

Why MateClaw

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. Digital employees, models, and tools sit behind permissions and workspace boundaries. Approval flows can pause risky actions for review, and key operations enter the audit trail. The Admin Runtime Console centralizes active employee and provider state with force-recycle for stuck runs. Spring Boot inside — a natural fit for Java shops already running production services.

Same “whole widget” philosophy. Different center of gravity.

Quick start

# Backend
# Java 21 and Maven required. Create a local JWT secret once and reuse it on restart.
[ -f .env.local ] || (umask 077; printf 'JWT_SECRET=%s\n' "$(openssl rand -hex 48)" > .env.local)
set -a
source .env.local
set +a
# From the repository root; use its configured models and workspace
SPRING_DATASOURCE_URL="jdbc:h2:file:$PWD/data/mateclaw;MODE=MySQL;DATABASE_TO_LOWER=TRUE;CASE_INSENSITIVE_IDENTIFIERS=TRUE" \
MATECLAW_WORKSPACE_SANDBOX_ROOT="$PWD/data/workspace" \
mvn -pl mateclaw-server spring-boot:run  # http://localhost:18088

# Frontend (new terminal, from the repository root)
cd mateclaw-ui
npm install && npm run dev -- --host 127.0.0.1    # http://localhost:5173

On a fresh database, log in with admin / admin123, change the password, then configure a model in Settings → Models. Existing model settings are read from the root data/ database; starting against mateclaw-server/data/ opens a different database. Keep .env.local private and set a non-empty JWT_SECRET of at least 32 UTF-8 bytes.

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

Project structure

mateclaw/
├── mateclaw-server/        Spring Boot 4.1.1 backend (Agent Runtime contract, native AgentScope + DSH)
├── mateclaw-ui/            Vue 3 + TypeScript admin SPA (built into the server JAR)
├── mateclaw-desktop/       Electron desktop app (local-embedded / remote-centralized)
├── mateclaw-webchat/       Embeddable chat widget (UMD / ES bundles)
├── mateclaw-plugin-api/    Java SDK for third-party capability plugins
├── mateclaw-plugin-sample/ Reference plugin implementation
├── mateclaw-plugin-mem0/   Optional Mem0 memory-provider plugin
├── mateclaw-plugin-search-sample/ Search Provider SPI example
├── docker-compose.yml
└── .env.example

Desktop binaries ship via GitHub Releases with a bundled JRE 21 — no Java install needed.

Tech stack

Documentation

Full docs at claw.mate.vip/docs — setup, architecture, each subsystem, API reference.

Roadmap

v2.3.0 (released 2026-09-20) — JSON acceptance and execution evidence for persistent Goals. Users can configure required JSON fields and bind checks to current requirements and immutable artifact versions. This release also adds controlled worker intervention and skill document/folder uploads, with fixes for DSH history and output budgets, vLLM reasoning, and SSE framing.

• Managed JSON acceptance: users select required fields; the server stores immutable JSON versions, binds checks to requirement revisions and slot generations, and rechecks them at Goal completion.
• Execution evidence: observe mode records execution and artifacts by default; on-demand version and JSON field diagnostics do not establish Goal acceptance.
• Worker intervention: handle worker tool approvals, denial, and feedback from team details while retaining conversation governance and exclusive execution.
• Skill uploads: upload documents, binary files, and folders with directory structure preserved; each file is limited to 10 MiB.
• Reliability fixes: bounded DSH history/output tokens, vLLM thinking control, SSE line-ending support, bounded spreadsheet extraction, and tool timeouts.

↗ v2.3.0

v2.2.0 (shipped 2026-08-29) — from one built-in reasoning loop to a pluggable and recoverable Agent Runtime:

• Runtime contract — provider registry, session factory, capability validation, normalized event stream, lifecycle, usage, and UI projection decouple employees from execution engines
• DeepSeek Harness runtime — managed installation and configuration, authenticated JSON-RPC process bridge, Cordis composition, cancellable streaming, isolated child environment, and host-governed tool dispatch
• Durable long work — bounded Goal segments, persisted continuation and input queues, attempts, cooldown, retry, leases, restart recovery, and explicit pause / resume semantics
• Agent interoperability — inbound and outbound A2A with Agent Cards, JSON-RPC / SSE tasks, authentication, idempotency, and guarded network boundaries
• Runtime hardening — tighter workspace ownership, reliable Team Run recovery and deliverable gates, plus consistent long-form output and input handling across approval, stop, and recovery

Full story in the v2.2.0 release notes.

v2.1.0 (shipped 2026-08-15) — from “a board full of tasks” to one governable team run:

• Unified Team Runs — one runId links request, task DAG, worker conversations, events, final synthesis, and deliverables; Chat delivers outcomes, Agents observes live work, Teams governs history
• Closed skill evolution — reflection + recurring-request mining + promotion + constrained auto-binding + curator governance + snapshots/restore, conservative by default and isolated per workspace
• Replayable execution — live <think> extraction, every reasoning iteration in emission order with real duration, superseded narration, and linear trajectory export
• Capabilities reach operations — proactive IM push, targeted Cron delivery, model-specific context windows, progressive tool disclosure, and tool-backed action completion
• Reliability pass — hardened browser refs/navigation/waits, WebChat/SSE cleanup and upstream idle timeout, Feishu progress, Qwen3-ASR HTTP, batch session deletion, date-partitioned files, and safe 64-bit ids

Full story in the v2.1.0 release notes.

v2.0.0 (shipped 2026-07-31) — from “one person who gets things done” to “a team that collaborates”: Agent Teams become a standing roster around a shared task board:

• Agent teams and a shared task board — teams / roles (lead · member · reviewer), an eight-status kanban, blockedBy dependency orchestration, member-level parallel dispatch, automatic prerequisite hand-off, settled results waking the lead; the Teams page ships an event-driven live board + activity banner + task timelines + deliverable downloads + manual task creation
• An execution chain hardened for long tasks — execution leases + runtime heartbeats against double execution, cancel that actually interrupts, in_review approval gates, retry for failed/stale
• Plan-Execute plans hand over to the board — steps become tasks, dependencies become parallelism, a parked-plan resume gate synthesizes deterministically
• Workspace isolation fully sealed — channel-scoped conversation ids; same-named skills coexist per workspace with conversation-scoped runtime resolution
• Channel experience — magic commands on every channel (/new /clear /status /stop /model /help), WeCom’s event-driven progress bubble (live tool trace + per-stage rolling narration)
• Server-side rewind / regenerate · explainable auto-approval misses (reason codes on audit rows + one-click grant creation) · policy-driven LLM error recovery (overload vs rate-limit split · Retry-After-aware backoff · provider TTL readmission)

Plus: in-chat attachment preview (pdf / docx / xlsx / html / text), single-source SKILL.md + console bundle-file management, the optional Mem0 plugin memory provider, and the knowledge-graph relation schema whitelist.

Full story in the v2.0.0 release notes.

v1.8.0 (shipped 2026-07-12) — the employee turns outward and does a whole job: Content Studio, the first flagship scene built end-to-end on MateClaw’s own primitives:

• Content Studio — one sentence to a publishable post — a seeded “Content Studio” employee runs pick-topic → research → draft → illustrate → de-AI → layout → deliver. WeChat Official Account (公众号) image-text articles (inline-style HTML → draft box) and Xiaohongshu (小红书) image-first notes (≥3 vertical 3:4 cards + online preview) ship first-class
• De-AI-ification you can measure — a heuristic AI-trace score (no LLM, deterministic) drives a detect → rewrite → re-check loop, capped at 3 rounds
• A publish chain hardened for real operation — body images uploaded into WeChat (no broken external links), AES-GCM-encrypted secrets, reused service + persisted token, retry + Chinese error hints, a guaranteed fallback cover; draft-box-first, publish approval-gated
• A content calendar that dedups and remembers — every delivery is compliance-scanned and auto-recorded, a topic fingerprint stops repeat picks, and a read-only Content Calendar page shows drafted/packaged/published/failed
• The browser agent sees by reference — an accessibility-tree ref snapshot + interact-by-ref (click the element, not a pixel), real-browser privacy guardrails, and a controlled CDP escape hatch
• Sharper attention, tighter loops — attention anchoring & environment awareness (MCP tool provenance + pinned skill constraints + event notifications), a tool-call loop guard, and a post-mutation verify reminder

Plus: a fast-load pass (initial load down ~78%), a chat context-occupancy panel, cross-KB wikilinks, MCP progress notifications, a Volcano Engine provider, and the public Docker stack on PostgreSQL 16.

Full story in the v1.8.0 release notes.

v1.7.0 (shipped 2026-07-04) — a productionization pass: once it’s in real collaboration, close every loop you can’t see, gather, reach, fit, or connect:

• All three approval paths close the loop — workflow await_approval actually pushes to channels and resolves → resumes, the WebChat (API-key) channel can approve/deny and replay, and Feishu/WeCom card clicks resolve workflow approvals directly
• Long tasks are visible — an always-on Run Overview rail + a per-turn token breakdown (cache hit/miss/write + reasoning split) + sub-agent cost rolled up + one-click generated-file download
• Fits the real model window — local-model context-window probing, a unified token budget for prefix injection, small-context degradation, and tool-schema budget gating — no more “guess 32K” pre-flight rejections or silent truncation
• Opens up — a knowledge-base + Deep Research open API (API-key + rate limit + SSE), a pluggable search Provider SPI, and MCP identity forwarding (carry the authenticated user’s identity into a STDIO MCP)
• Reaches further — desktop local-embedded / remote-centralized dual mode (with mateclaw-desktop source opened) + a LAN deployment mode for controlled intranet access
• One-click operational data export — Dashboard 9-sheet Excel + a CLI for offline export

Full story in the v1.7.0 release notes.

v1.6.0 (shipped 2026-06-22) — make the autonomous employee fast, sharp-eyed, and embeddable: two-stage skill loading + prefix compression (faster first token) · execute_code native sandboxed code execution · vision that persists across turns + image_analyze · embeddable/headless webchat with per-endUserId memory · a Wiki you actually read (reading split from management · unified Sources tab · clickable [[wikilinks]]) · steadier under load (self-healing MCP · tool-call recovery · evidence-gated plans). Full story in the v1.6.0 release notes.

v1.5.0 (shipped 2026-06-04) — Goal checklists (fuzzy score → ticked boxes) · self-maintaining Wiki ([[wikilinks]] · fact/experience layers · pageType profiles & permissions · KB pipelines · local-directory ingest) · per-owner memory isolation (owner_key + visibility scope + endUserId passthrough) · per-agent primary knowledge base · provider-preference model routing. Full story in the v1.5.0 release notes.

v1.4.0 (shipped 2026-05-23) — Persistent Goals (lock a goal, self-evaluate every turn) · subagent delegation tree (3 levels deep · sync / parallel / async · one-sentence team builder) · progressive tool/skill disclosure · Workspace RBAC (Owner / Admin / Member / Viewer) · Feishu first-class (interactive / approval / streaming cards · channel-native tools). See the v1.4.0 release notes.

v1.3.0 (shipped 2026-05-13) — Workflow engine · 6-pattern trigger system · Wiki transformations · per-agent MCP binding · multimodal sidecar routing · four JVM-native document-generation tools · image edit. See the v1.3.0 release notes.

Contributing

git clone https://github.com/mateaix/mateclaw.git
cd mateclaw
mvn -pl mateclaw-server -am clean compile
cd mateclaw-ui && npm install && npm run dev -- --host 127.0.0.1

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.