MateClaw

English

中文

English

中文

Appearance

v1.7.0 ​

Stable · 2026-07-04 · Previous stable v1.6.0

The big things this release ​

v1.6.0 let the employee run on your database, grow senses and hands, and be shaped by you directly. This release is about what happens once you put it into real production collaboration — the places that go invisible, unresolved, out of reach, oversized for the window, and walled off from your systems.

In one line: v1.7.0 is a productionization pass — long-task progress and cost become visible, approvals close the loop, the desktop and intranet servers become reachable, injection fits the real model window, and the knowledge base and Deep Research become connectable as open APIs.

The big things:

  • All three approval paths close the loop — workflow approvals, the WebChat/API-Key channel, and Feishu/WeCom card clicks are all end-to-end now, no more silent hangs.
  • 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 download of generated files.
  • 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" leading to a pre-flight rejection or a silent truncation.
  • Opens up — a knowledge-base + Deep Research open API (API-key auth + rate limit + SSE), a pluggable search Provider SPI, and MCP identity forwarding (carry the authenticated user's identity into a STDIO MCP).
  • Reaches further — the desktop's local-embedded / remote-centralized dual mode (with the mateclaw-desktop source opened as of v1.7.0), plus a LAN deployment mode that opens controlled intranet-service access.
  • One-click operational data export — Dashboard 9-sheet Excel + a CLI for offline export.

Plus: Wiki processing-failure visibility, per-employee model chains, a debuggable OpenAPI/Swagger, a chat back-to-bottom floating button, and a batch of concurrent-memory-isolation, upload-path, and model-probe fixes.

That's it.

1. All three approval paths close the loop ​

MateClaw has three approval paths. Until now only the first was end-to-end; the other two had functional gaps (one a known silent failure):

PathNotifyResolve entryResume
Conversation tool approval (Web/IM)✅✅✅
Workflow await_approval step❌→✅⚠️→✅✅
WebAPI (API-Key / WebChat) channel❌→✅❌→✅❌→✅

Workflow approvals no longer fail silently. A step's declared approverChannels (e.g. feishu:oc_xxx) used to be serialized into the approval row for display only — nothing in the codebase read it back to send a notification. Now the step actually pushes an approval notification per channel, and the resolve → resume bridge is wired up (activating a recovery path that was previously dead code), so an approved workflow continues from the paused step.

WebChat (API-Key) channel gains the approval interaction. Before, an agent bound to WebChat that hit a ToolGuard-protected tool would suspend, but the visitor couldn't resolve it — the approval hung to a 30-minute GC timeout, wasting the whole turn. Now /sessions/approve and /sessions/deny endpoints reuse visitorToken + conversation-ownership auth (the pendingId is strictly scoped to the owned conversation, closing a cross-visitor IDOR), approve replays the tool, deny returns a synchronous result, and both broadcast tool_approval_resolved so the SDK clears the approval banner in real time.

Feishu / WeCom card clicks resolve workflow approvals directly. Once a workflow approval is pushed to a Feishu/WeCom group, the Approve/Deny buttons now actually work — fixing the fail-closed identity check for workflow approvals (system-initiated, no userId) and the dead end where the synthesized message's conversationId never matched workflow:run:{runId} so the pending was never found.

See Workflow and Security.

2. Long tasks are visible — Run Overview + token breakdown + sub-agent cost ​

Long tasks (multi-step plans, multi-agent collaboration) used to mean scrolling the message stream to track progress — and gave you no idea what they cost. This release puts both progress and cost on the table.

The always-on "Run Overview" rail. The chat view gains a persistent rail that assembles the data the backend already streams into one place:

  • Plan progress — in plan mode, live per-step status (pending / running / completed) and a progress count, with expandable step results. A "planning…" placeholder shows before the plan streams in, so the rail doesn't flicker.
  • Live sub-agent status — delegated sub-agents render as a live tree (name, tools called, running / completed / error / stalled state), with multi-level delegation expandable layer by layer.
  • One-click generated-file download — files written by execute_code / execute_shell_command, and other agent-produced artifacts, surface as clickable attachments right in the rail (the download uses the real filename, not the raw id URL).
  • Collapse / drawer — collapses to a badged rail; below 1280px it degrades to a floating drawer so it never squeezes the conversation column.

Per-turn token breakdown. Each turn now shows a usage breakdown: input / output / reasoning tokens, plus the cache hit / miss / write split — so you can see at a glance how much the Anthropic prompt cache saved and how much reasoning cost.

Sub-agent cost rolled up. Each delegated sub-agent's token usage rolls up layer by layer into the turn's total footer; both single-task and plan-step delegation surface it in a structured way, so what a spun-up team cost is right there.

Pure frontend assembly reusing the existing SSE event stream. See Chat.

3. Fits the real model window — context & token budgeting ​

Injection (memory, Wiki, the identity prompt, tool schemas) used to be stacked in on fixed assumptions. Against a small-window local model or a strict local inference server, that meant either a silent truncation or a max_tokens pre-flight rejection. This release makes every injected block scale with the real model window.

  • Local-model context-window probing — the real context window of Ollama / vLLM feeds the session budget; on an over-limit error the window value is back-solved and refilled, instead of "guess 32K".
  • Unified token budget for prefix injection — memory / Wiki and other first-request injection blocks scale together against the model's effective window; an oversized identity prompt warns instead of silently blowing the window.
  • Small-context degradation tiers — compact / floor tiers tighten injection, the compression trigger ratio adapts to 0.85, prefix chunks are counted, and a pre-overflow fast-fail keeps small windows stable.
  • Tool-schema budget gate — when too many tools push schemas over the window budget, cold tools auto-degrade to the extended catalog by usage frequency; enable_tool brings any back on demand.
  • Reasoning output cap respects model config — the reasoning node clamps its output cap against both the model's configured maxTokens and the real window, fixing the strict local server's max_tokens pre-flight rejection.
  • Informative compaction placeholders — after context is compacted, the placeholder keeps the tool name / original size / first-line gist so the model can judge whether to re-run, instead of a blob of "[omitted]".

See Models and Chat.

4. Opens up — KB / Deep Research open API + pluggable search + MCP identity forwarding ​

This release exposes MateClaw's capabilities as controlled open APIs for external systems for the first time, and makes the tool ecosystem more pluggable.

Knowledge-base and Deep Research open API. A new open-API surface for external integrations: 9 endpoints for knowledge-base search / pages / entities, plus the full Deep Research start / SSE / status / cancel flow. Auth goes through a dedicated API key (not a logged-in session), with rate limiting and centralized authorization; a session is strictly bound to the kbId in its path, and a cross-KB IDOR is closed. External apps can now call MateClaw's knowledge base and deep research directly, without logging into the admin console.

Pluggable search Provider. Search graduates from a few built-in implementations to a pluggable SPI: a new PluginType.SEARCH and PluginSearchProvider interface let a third-party search source drop in like a plugin; a search-provider catalog endpoint, a grouped settings UI, and a plugin config form let you pick and configure a search source right in Settings.

MCP identity forwarding. A STDIO-type MCP server can now, opt-in per server, forward the current authenticated user's identity (on-behalf-of), typed by channel and trust level; it fails closed on an unknown channel and self-heals the signing key, so identity can't be spoofed. Local MCP tools can finally know "who's using this right now."

See API, MCP, and Tools.

5. Reaches further — desktop remote + LAN deployment mode ​

Desktop connects to a remote server + source open-sourced. For the "many people collaborating against one centrally deployed server" scenario:

  • Local / remote dual mode — run the embedded JVM locally, or connect directly to a centrally deployed remote server.
  • First-run connection chooser — the first launch lets you pick the mode and enter the server URL (auto-prefixes https://, normalizes and validates).
  • Multi-server & switching — remembers recently used servers (up to 8) and a "Switch Server" menu to change environments anytime.
  • Self-signed intranet certs — accepts self-signed certificates for hosts the user explicitly trusts (scoped to the active connection, not a blanket bypass), suiting enterprise intranets.
  • The entire mateclaw-desktop source is open in the repository: Electron main / preload + the Vue renderer, packaging config, build assets, README / CODESIGNING guides; build artifacts, the bundled JRE, and signed binaries stay out via .gitignore.

LAN deployment mode. The outbound guard blocks intranet / metadata addresses by default to prevent SSRF; a new LAN deployment mode switch opens controlled intranet-service access once you explicitly enable it, for the "MateClaw sits on the same LAN as the intranet services" deployment. With the switch off, the default posture is harder: SSRF is re-checked on every request, redirect targets are blocked too, the cloud-metadata address is unbypassable, and the self-signed TLS allowance is scoped to LAN mode; the guard allowlist is configurable.

See Desktop and Security.

6. One-click operational data export — UI + CLI ​

A new operational data export: a multi-sheet report (.xlsx packaged as .zip) covering 9 sheets — overview KPIs, token usage, skill stats, user stats, user conversations, security & audit, channel stats, model config, cron jobs.

  • Dashboard one-click — global-admin only. Pick a date range (quick last 7/30/90 days, 90-day max) → generate (a circular progress ring) → download. Generate / progress / download are global-admin gated, the one-time download token is atomically single-use, and the file auto-cleans after 24h or on download.
  • Command-line export — a project-level CLI framework plus --cli.command=export lets you generate the report from a shell or docker exec and stream the ZIP to stdout (> report.zip), with no 90-day cap and no timeout — suitable for large offline ranges. The CLI is operator-only and never exposed over HTTP.
  • 19-digit Snowflake IDs are written to Excel as text to avoid the spreadsheet's numeric precision truncation.

See Backstage.

7. A few things that got more transparent and controllable ​

  • Wiki processing-failure visibility — a failed knowledge-base ingest is no longer silent: the error-code chain is traceable, silent sub-steps raise alerts, and there's a cross-KB failure center; a page written by an agent via wiki_create_page gets its raw/chunks/embeddings/citations backfilled so the UI can recognize and act on it. Cheap ingest steps can route to a configurable light model to save cost, the knowledge graph gains a search box to locate a node by name, and the built-in transformation starter pack is visible in every workspace.
  • Per-employee model chain — each employee can configure its own model chain (provider + model, a provider repeatable), overriding the global default.
  • Debuggable OpenAPI / Swagger — a global OpenAPI config (title / description / server + bearerAuth, covering both JWT and mc_ personal access tokens, dispatched by prefix), Swagger UI's Authorize works, and protected endpoints can be exercised via Try it out; every field is overridable via environment variables. See the OpenAPI / Swagger guide.
  • Chat "back to bottom" floating button — appears when you scroll up to read history, auto-docks to the edge after 15s of inactivity, and the End key jumps to the bottom; auto-scroll no longer fights you while reading.

A few more ​

  • Concurrent-session memory isolation — fixes memory bleeding across a single agent's concurrent sessions; session_search is strictly isolated to its own conversation; mate_memory_recall.filename is bounded to VARCHAR(256).
  • Upload & generated-file paths — chat uploads are stored root-relative (no longer an absolute server path); the generated-file link regex is narrowed to http(s) / relative URLs; a stale workspace agentId is dropped from the chat URL on remount.
  • Model & skill details — the model-discovery button stays visible before an API key is set; DeepSeek is no longer assumed vision-capable; skill ZIP size caps are configurable.
  • Outbound guard — the outbound HTTP guard gains a configurable SSRF allowlist.

Upgrade path ​

Config is fully compatible. Your agents / skills / Wiki / channels / cron jobs / workflows / triggers / goals all carry over unchanged.

If you're already running v1.6.0 in production:

  • Workflow approval notifications activate automatically from a step's approverChannels — declare a target like "feishu:oc_xxx" to receive notifications; a bare "web" is not actively pushed (resolve from the admin side).
  • Context & token budgeting is on by default and backward-compatible: large-window cloud models feel the same; small-window local models now probe the real window and inject against a budget — if you hand-set a window value before, give the model config a review.
  • Open API & Deep Research API require a separately issued API key by default and are rate-limited; existing logged-in calls are unaffected; issue no key and nothing is exposed.
  • LAN deployment mode is off by default — keeping the hard posture that blocks intranet / metadata addresses; only after you explicitly flip the switch is controlled intranet access opened.
  • MCP identity forwarding is per-server opt-in and off by default; enable it per STDIO MCP only when it needs to know the caller's identity.
  • Desktop remote connection is a new option; the default is still local-embedded, and the first-run chooser guides the choice.
  • OpenAPI metadata is driven by mateclaw.openapi.*; empty values use the built-in defaults. To lock down public Swagger access in production, add an explicit rule in SecurityConfig.

What this release means for you ​

If you run workflows — the await_approval step's notification actually reaches the Feishu/WeCom group, you approve with a card tap, and an approved workflow continues on its own instead of hanging silently.

If you run long tasks — the Run Overview rail shows progress and sub-agents, the per-turn token breakdown and sub-agent cost are right there, and generated files are one click away.

If you use local / small-window models — injection scales with the real window, no more pre-flight rejections or silent truncation; strict local inference servers run stably.

If you build external integrations — the knowledge base and Deep Research have controlled open APIs (API key + rate limit + SSE), search sources are pluggable, and a STDIO MCP can see the caller's identity.

If you do ops / audit — export the 9-sheet operational report in one click from the Dashboard or the command line, and a failed Wiki ingest is traceable.

If you collaborate as a team — the desktop reaches one centrally deployed server, the LAN can open controlled intranet-service access, and mateclaw-desktop source is open too, so you can build and distribute it yourself.

One last thing. ​

Visible, gathered, reachable, right-sized, connected.

A system whose approvals can hang silently is one you won't put inside a real business process.An employee whose long task — and its cost — you can't see is one you can only wait on.An assistant that blows past the window and gets rejected by a local model is one you can't even start locally.A product whose capabilities stay walled inside the admin console won't carry collaboration, and won't plug into your systems.

This release closes all of it: approvals end-to-end, long-task progress and cost visible while they run, injection that fits the real window, capabilities opened as controlled APIs, and a desktop that reaches the server you deployed — with its source opened.

From "it works" to "I'll put it in production."