Console UI

This document covers all pages, features, data flow, and development details of the MateClaw frontend console.

Tech Stack

Framework: Vue 3 + Composition API + TypeScript
State Management: Pinia (domain-driven design)
UI Library: Element Plus
Styling: TailwindCSS 4 + CSS variables
Build Tool: Vite 6
Routing: Vue Router (History mode)
i18n: vue-i18n (zh-CN / en-US)
HTTP Client: Axios (REST) + native fetch (SSE streaming)
Auth: JWT Token with automatic request interceptor injection and sliding-window renewal

Overall Layout

The application uses a classic left sidebar + right content area layout (MainLayout.vue).

The sidebar is organized into four navigation groups:

Group	Pages
Chat	Chat Console
Control	Channels, Sessions, Cron Jobs
Agent	Workspace, Skill Market, Tools, MCP Servers
Settings	Agent Management, Security, Token Usage, Settings

The sidebar supports collapse/expand with the state persisted to localStorage. The bottom section contains theme toggle buttons (light/dark/system) and current user information.

Auth Guard

All pages except /login are protected by a beforeEach route guard that checks for a valid Token in localStorage. Unauthenticated users are redirected to the login page. In development, set VITE_SKIP_AUTH=true to bypass authentication.

Page Reference

Route: /login

The authentication entry point. Provides a username/password form with a password visibility toggle.

Features:

Username + password login
On success, stores Token, username, and role in localStorage
Automatic redirect to the Chat Console

API Calls:

POST /api/v1/auth/login -- Submit credentials, receive JWT Token

Default credentials: admin / admin123

2. Chat Console (ChatConsole)

Route: /chat

The primary interaction interface for conversing with Agents.

Layout:

Left panel: Conversation sidebar (Agent selector + conversation list)
Right panel: Main chat area (message list + input box)

Features:

Agent selector: Dropdown at the top of the sidebar to switch the active Agent. Each Agent maintains its own conversation list
Conversation list: Grouped by date (Today, Yesterday, Last 7 Days, Earlier). Each entry shows the title, message count, and last active time. Supports creating new conversations and deleting existing ones
Model switcher: Dropdown in the chat header to select which model to use (from configured model providers)
Message bubbles: User and assistant messages displayed separately with Markdown rendering and code highlighting
SSE streaming: Uses native fetch to establish an SSE connection for real-time token-by-token response display
Stream status bar: Displayed between the message list and input box, showing tool call count and token usage during generation
Tool call visualization: Inline display of Agent tool invocations and their results
Thinking process display: Expandable/collapsible sections showing the ReAct reasoning chain
ToolGuard approval: When a tool call triggers a security rule, inline approve/reject buttons appear in the chat
File upload: Support for attaching files with preview and removal
Stop generation: Interrupt the streaming response mid-generation
Clear messages: Wipe all messages in the current conversation
Suggestions: Pre-defined conversation starters shown in empty conversations

API Calls:

POST /api/v1/chat/stream -- SSE streaming conversation (native fetch)
POST /api/v1/chat/upload -- Upload file attachment
POST /api/v1/chat/{conversationId}/stop -- Stop streaming generation
POST /api/v1/chat/{conversationId}/approve -- Approve a tool call
GET /api/v1/chat/{conversationId}/pending-approvals -- Query pending approvals
GET /api/v1/conversations -- List conversations
GET /api/v1/conversations/{id}/messages -- Get conversation message history
DELETE /api/v1/conversations/{id} -- Delete a conversation
DELETE /api/v1/conversations/{id}/messages -- Clear messages
GET /api/v1/agents -- List Agents
GET /api/v1/models/enabled -- List available models
GET /api/v1/models/active -- Get the currently active model
PUT /api/v1/models/active -- Switch the active model

Component Breakdown:

MessageList -- Renders messages, handles regeneration, thinking process toggle
ChatInput -- Handles text input, file selection, approval actions
StreamLoadingBar -- Displays streaming progress with tool call and token stats

3. Agent Management (Agents)

Route: /agents

CRUD management for Agents, displayed as a table.

Features:

Search and filter: Keyword search + type filter tabs (All / ReAct / Plan-Execute)
Agent table: Columns for name (with icon and description), type, tags, enabled status, update time, and action buttons
Create Agent: Modal form for configuring name, description, type (ReAct / Plan-and-Execute), icon, model, system prompt, tags, etc.
Edit Agent: Modify existing Agent configuration
Enable/disable: Inline toggle switch for Agent status
Delete: Remove Agents that are no longer needed

API Calls:

GET /api/v1/agents -- List Agents
POST /api/v1/agents -- Create Agent
PUT /api/v1/agents/{id} -- Update Agent
DELETE /api/v1/agents/{id} -- Delete Agent

4. Agent Workspace (AgentWorkspace)

Route: /workspace

Per-Agent file workspace for managing core configuration files.

Layout:

Top: Agent selector
Left panel: File list
Right panel: File editor

Features:

Agent selector: Dropdown to choose which Agent's workspace to manage
File browser: Lists all files in the Agent's workspace with filename, size, and enabled status
File editor: Select a file to view and edit its content in the right panel, with save support
File enable/disable: Toggle whether a file is loaded by the Agent (e.g., PROFILE.md, MEMORY.md)
Create file: Add new files to the workspace
Refresh: Reload the file list

Typical Files:

PROFILE.md -- Agent persona and behavioral guidelines
MEMORY.md -- Agent long-term memory
Daily notes and other custom files

API Calls:

GET /api/v1/agents/{id}/workspace/files -- List workspace files
GET /api/v1/agents/{id}/workspace/files/{filename} -- Get file content
PUT /api/v1/agents/{id}/workspace/files/{filename} -- Save file content
DELETE /api/v1/agents/{id}/workspace/files/{filename} -- Delete file
GET /api/v1/agents/{id}/workspace/prompt-files -- Get prompt file list
PUT /api/v1/agents/{id}/workspace/prompt-files -- Set prompt file list

5. Tool Management (Tools)

Route: /tools

Manage the tools available to Agents, displayed as a table.

Features:

Tool table: Columns for tool name, description, bean name, type (builtin/mcp/custom), and enabled status
Register tool: Create a custom tool definition
Edit tool: Modify tool configuration
Enable/disable: Inline toggle switch for tool availability
Delete: Remove custom tools

Tool Types:

builtin -- Built-in tools (e.g., WebSearch, DateTime)
mcp -- Tools accessed via MCP protocol from external servers
custom -- User-defined tools

API Calls:

GET /api/v1/tools -- List tools
POST /api/v1/tools -- Register a new tool
PUT /api/v1/tools/{id} -- Update tool configuration
DELETE /api/v1/tools/{id} -- Delete tool
PUT /api/v1/tools/{id}/toggle?enabled={bool} -- Toggle enabled status

6. MCP Servers (McpServers)

Route: /mcp-servers

Manage MCP (Model Context Protocol) server connections.

Features:

Server table: Columns for server name, description, transport type, connection status, tool count, and enabled status
Transport types: Supports different MCP transport protocols
Connection status: Real-time display of each server's connection state (connected/disconnected), with error messages on failure
Add server: Create a new MCP server configuration
Test connection: Verify connectivity for an individual server
Refresh all: Re-check connection status for all servers at once
Enable/disable: Toggle server status
Edit/delete: Modify or remove server configurations

API Calls:

GET /api/v1/mcp/servers -- List servers
POST /api/v1/mcp/servers -- Create server
PUT /api/v1/mcp/servers/{id} -- Update configuration
DELETE /api/v1/mcp/servers/{id} -- Delete server
PUT /api/v1/mcp/servers/{id}/toggle?enabled={bool} -- Toggle enabled status
POST /api/v1/mcp/servers/{id}/test -- Test connection
POST /api/v1/mcp/servers/refresh -- Refresh all

7. Skill Market (SkillMarket)

Route: /skills

Manage skill packages that Agents can load, displayed as a card grid.

Features:

Category tabs: Filter skills by type, each tab showing a count
Skill cards: Display name, icon, type badge, version, description, and runtime status
Runtime status: Shows whether the skill is loaded, along with security scan results and dependency status
Security scan: Displays a summary of security findings
Dependency check: Lists any missing dependencies
Create skill: Register a new skill package
Enable/disable: Toggle skill availability
Refresh runtime: Reload runtime status for all skills

API Calls:

GET /api/v1/skills -- List skills
POST /api/v1/skills -- Create skill
PUT /api/v1/skills/{id} -- Update skill
DELETE /api/v1/skills/{id} -- Delete skill
PUT /api/v1/skills/{id}/toggle?enabled={bool} -- Toggle enabled status
GET /api/v1/skills/runtime/active -- Get active skills
GET /api/v1/skills/runtime/status -- Get runtime status
POST /api/v1/skills/runtime/refresh -- Refresh runtime

8. Channel Management (Channels)

Route: /channels

Manage multi-channel integrations, displayed as a card grid.

Features:

Channel cards: Each card shows the channel type icon, name, type label, description, enabled status, and connection indicator
Supported channels: Web, DingTalk, Feishu, WeChat Work, Telegram, Discord
Connection indicator: Real-time display of channel connection health
Add channel: Create a new channel configuration (select type, fill in Webhook URL, Token, etc.)
Edit channel: Modify channel configuration parameters
Enable/disable: Toggle channel status
Delete channel: Remove channels no longer in use

API Calls:

GET /api/v1/channels -- List channels
POST /api/v1/channels -- Create channel
PUT /api/v1/channels/{id} -- Update channel
DELETE /api/v1/channels/{id} -- Delete channel
PUT /api/v1/channels/{id}/toggle?enabled={bool} -- Toggle enabled status
GET /api/v1/channels/status -- Query channel connection status
GET /api/v1/channels/webhook/weixin/qrcode -- Get WeChat iLink Bot QR code
GET /api/v1/channels/webhook/weixin/qrcode/status -- Query QR code scan status

9. Session Management (Sessions)

Route: /sessions

Browse and manage all conversation sessions, displayed as a table.

Features:

Search: Keyword search across sessions
Session table: Columns for session title, ID, associated Agent, message count, status (active/closed), and last active time
View session: Click to navigate to the Chat Console and view the session's messages
Delete session: Remove historical sessions

API Calls:

GET /api/v1/conversations -- List sessions
GET /api/v1/conversations/{id}/messages -- Get session messages
GET /api/v1/conversations/{id}/status -- Query session status
DELETE /api/v1/conversations/{id} -- Delete session

10. Cron Jobs (CronJobs)

Route: /cron-jobs

Manage scheduled automated tasks.

Features:

Job table: Columns for job name, associated Agent, task type, cron expression (with human-readable description), next run time, last run time, and enabled status
Create job: Configure a new scheduled task with name, Agent, cron expression, timezone, etc.
Edit job: Modify existing job configuration
Run now: Manually trigger immediate execution without waiting for the cron schedule
Enable/disable: Toggle the job's scheduling status
Delete job: Remove a scheduled task

API Calls:

GET /api/v1/cron-jobs -- List jobs
POST /api/v1/cron-jobs -- Create job
PUT /api/v1/cron-jobs/{id} -- Update job
DELETE /api/v1/cron-jobs/{id} -- Delete job
PUT /api/v1/cron-jobs/{id}/toggle?enabled={bool} -- Toggle enabled status
POST /api/v1/cron-jobs/{id}/run -- Run immediately

11. Token Usage (TokenUsage)

Route: /token-usage

View token consumption statistics.

Features:

Date range filter: Date picker to constrain the reporting period
Summary cards: Display total prompt tokens, total completion tokens, and total assistant messages
Per-model table: Breakdown by model provider and model name, showing prompt tokens, completion tokens, and message count for each

API Calls:

GET /api/v1/token-usage -- Get usage summary (supports startDate, endDate, modelName, providerId query parameters)

12. Settings

The Settings module uses a sub-route layout (Settings/Layout.vue) with three child pages.

12.1 Model Settings (Settings/Models)

Route: /settings/models (default Settings page)

Manage model providers and model configurations, displayed as a card grid.

Features:

Provider cards: Show name, icon, ID, builtin/custom badge, active status, base URL, API key, and model count
Configuration status: Indicates whether a provider is configured or not
Add custom provider: Create an OpenAI-compatible custom model provider
Manage models: View, add, or remove models under a provider
Provider settings: Modify base URL and API key
Test connection: Verify provider connectivity with latency reporting
Model discovery: Auto-discover models supported by a provider
Delete custom provider: Remove user-added providers

API Calls:

GET /api/v1/models -- List providers
GET /api/v1/models/enabled -- List enabled models
GET /api/v1/models/default -- Get default model
POST /api/v1/models -- Create model config
PUT /api/v1/models/{id} -- Update model config
DELETE /api/v1/models/{id} -- Delete model config
POST /api/v1/models/{id}/default -- Set as default model
PUT /api/v1/models/{providerId}/config -- Update provider config
POST /api/v1/models/custom-providers -- Create custom provider
DELETE /api/v1/models/custom-providers/{providerId} -- Delete custom provider
POST /api/v1/models/{providerId}/models -- Add model to provider
DELETE /api/v1/models/{providerId}/models/{modelId} -- Remove model from provider
GET /api/v1/models/active -- Get currently active model
PUT /api/v1/models/active -- Set active model
POST /api/v1/models/{providerId}/discover -- Discover models
POST /api/v1/models/{providerId}/discover/apply -- Apply discovered models
POST /api/v1/models/{providerId}/test-connection -- Test connection
POST /api/v1/models/{providerId}/models/{modelId}/test -- Test individual model

12.2 System Settings (Settings/System)

Route: /settings/system

Global system parameter configuration.

Features:

General settings:

Language: Switch the interface language (Simplified Chinese / English)
Stream response: Enable or disable SSE streaming output
Debug mode: Enable to display additional debug information

Search service configuration:

Search toggle: Enable or disable the WebSearch tool
Search provider: Choose between Serper (Google) and Tavily
API key: Configure the search service API key

API Calls:

GET /api/v1/settings -- Get system settings
PUT /api/v1/settings -- Update system settings
GET /api/v1/settings/language -- Get language setting
PUT /api/v1/settings/language -- Update language setting

12.3 About (Settings/About)

Route: /settings/about

Displays MateClaw version information and technology stack.

Contents:

MateClaw logo, version number, and project description
Tech stack list: Spring Boot 3.3.x, Spring AI 1.1.x, Spring AI Alibaba 1.1.x, Vue 3.5.x, Vite 6.x, MyBatis Plus 3.5.x

13. Security Center

The Security module uses a sub-route layout (Security/Layout.vue) with three child pages.

13.1 Tool Guard (Security/ToolGuard)

Route: /security/tool-guard (default Security page)

Configure security approval rules for tool execution.

Features:

Global configuration:
- Enable/disable Tool Guard
- Guard scope: all tools or only selected tools
- Specify guarded tools list (tag input)
- Specify denied tools list (tag input)
Rules table: Columns for rule name, severity level, category, decision (allow/needs approval/block), builtin flag, and enabled status
Create rule: Add custom approval rules
Edit/delete rule: Modify or remove custom rules
Enable/disable rule: Toggle individual rule activation

API Calls:

GET /api/v1/security/guard/config -- Get guard configuration
PUT /api/v1/security/guard/config -- Update guard configuration
GET /api/v1/security/guard/rules -- List custom rules
GET /api/v1/security/guard/rules/builtin -- List builtin rules
POST /api/v1/security/guard/rules -- Create rule
PUT /api/v1/security/guard/rules/{id} -- Update rule
PUT /api/v1/security/guard/rules/{id}/toggle?enabled={bool} -- Toggle rule status
DELETE /api/v1/security/guard/rules/{id} -- Delete rule

13.2 File Guard (Security/FileGuard)

Route: /security/file-guard

Configure file access control policies.

Features:

Enable/disable: Global toggle for File Guard
Sensitive paths management: Tag-style input to add or remove protected file paths

API Calls:

GET /api/v1/security/guard/config/file-guard -- Get File Guard configuration
PUT /api/v1/security/guard/config/file-guard -- Update File Guard configuration

13.3 Audit Logs (Security/AuditLogs)

Route: /security/audit-logs

View security audit records for tool executions.

Features:

Stats cards: Display total requests, blocked count, needs-approval count, and allowed count
Filters: Filter by tool name and decision type (ALLOW / NEEDS_APPROVAL / BLOCK)
Audit table: Columns for timestamp, tool name, decision, severity, and conversation ID
Detail expansion: Click a row to view matched rule details and tool call parameters

API Calls:

GET /api/v1/security/audit/logs -- Get audit logs (supports toolName, decision query parameters)
GET /api/v1/security/audit/stats -- Get audit statistics

Pinia State Management

MateClaw uses domain-driven Pinia stores. Each store exclusively owns its slice of state -- external code must not modify a store's state directly.

Store List

Store	File	Responsibility
`useAgentStore`	`stores/useAgentStore.ts`	Agent list, Agent CRUD
`useCronJobStore`	`stores/useCronJobStore.ts`	Cron job list, job CRUD
`useThemeStore`	`stores/useThemeStore.ts`	Theme mode (light/dark/system), persistence

Note: Chat state is managed via the useChat composable (composables/chat/useChat.ts) rather than a global store. This design ties chat state to the component lifecycle, avoiding global state pollution.

State Ownership Principle

typescript

// Correct: modify state through store actions
agentStore.fetchAgents()
themeStore.setMode('dark')

// Wrong: mutate store state directly
agentStore.agents = []  // Do not do this

Dark Mode

Three Modes

MateClaw's theme system supports three modes:

Light: Fixed light theme
Dark: Fixed dark theme
System: Automatically follows the operating system's dark mode preference

Theme toggle buttons are located at the bottom of the sidebar.

Implementation

useThemeStore manages theme state with the mode value persisted to localStorage
Toggling adds/removes the dark class on the <html> element
TailwindCSS 4 applies dark styles via the dark: prefix
Element Plus themes are switched via --mc-* CSS variables
System mode uses matchMedia('(prefers-color-scheme: dark)') to listen for OS changes

Writing Styles

vue

<template>
  <div class="bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100">
    <el-card class="border dark:border-gray-700">
      <p>Dark-mode-aware content</p>
    </el-card>
  </div>
</template>

Internationalization (i18n)

Supported Languages

zh-CN: Simplified Chinese (default)
en-US: English

Language Files

src/i18n/
  index.ts        # i18n instance configuration
  zh-CN.ts        # Chinese translations
  en-US.ts        # English translations

Switching Language

Navigate to Settings > System Settings to switch the language. The change takes effect immediately and is persisted to the backend. The frontend updates the vue-i18n locale in sync.

Usage in Components

vue

<template>
  <h1>{{ $t('chat.title') }}</h1>
  <el-button>{{ $t('common.save') }}</el-button>
</template>

<script setup lang="ts">
import { useI18n } from 'vue-i18n'
const { t } = useI18n()

const title = computed(() => t('chat.title'))
</script>

API Communication Layer

Axios Instance

The frontend communicates with the backend through a centralized Axios instance (src/api/index.ts):

typescript

const http = axios.create({
  baseURL: '/api/v1',
  timeout: 30000,
})

Request Interceptor

Automatically reads the JWT Token from localStorage and injects it into the Authorization header

Response Interceptor

Adapts the backend's unified response format R<T>: { code, msg, data }
Sliding-window Token renewal: the backend issues a new Token via response headers when the current one is near expiry
401/403 handling: clears the local Token and redirects to the login page

SSE Streaming

Chat streaming does not use Axios. Instead, it uses the native fetch API to establish an SSE connection:

typescript

fetch('/api/v1/chat/stream', {
  method: 'POST',
  headers: { Accept: 'text/event-stream', Authorization: `Bearer ${token}` },
  body: JSON.stringify(data),
})

This is necessary because Axios does not support SSE streaming -- the response must be read incrementally via ReadableStream.

Route Structure

/login                     -- Login page
/                          -- Redirects to /chat
/chat                      -- Chat Console
/channels                  -- Channel Management
/sessions                  -- Session Management
/cron-jobs                 -- Cron Jobs
/workspace                 -- Agent Workspace
/skills                    -- Skill Market
/tools                     -- Tool Management
/mcp-servers               -- MCP Servers
/agents                    -- Agent Management
/security                  -- Security Center (redirects to /security/tool-guard)
/security/tool-guard       -- Tool Guard
/security/file-guard       -- File Guard
/security/audit-logs       -- Audit Logs
/token-usage               -- Token Usage
/settings                  -- Settings (redirects to /settings/models)
/settings/models           -- Model Settings
/settings/system           -- System Settings
/settings/about            -- About

Unmatched paths are redirected to /chat.

Build and Development

Development Server

bash

cd mateclaw-ui
pnpm install
pnpm dev          # Start dev server on port 5173

In development, Vite proxies /api requests to http://localhost:18088 (the backend dev server).

Production Build

bash

pnpm build

Build process:

vue-tsc runs TypeScript type checking
Vite bundles the output to ../mateclaw-server/src/main/resources/static

The build artifacts are embedded directly in the Spring Boot JAR -- no separate frontend deployment is needed.

Linting

bash

pnpm lint         # ESLint with auto-fix

Development Tips

Hot reload: pnpm dev supports HMR -- changes appear instantly in the browser
Path alias: @ maps to src/ (configured in vite.config.ts and tsconfig.json)
Component library: Use Element Plus components with auto-import
Styling priority: Prefer TailwindCSS utility classes; use <style scoped> for complex component-specific CSS
Type definitions: Shared types are defined in src/types/
Skip auth: Set VITE_SKIP_AUTH=true during development to bypass the login requirement

Console UI ​

Tech Stack ​

Overall Layout ​

Sidebar ​

Auth Guard ​

Page Reference ​

1. Login ​

2. Chat Console (ChatConsole) ​

3. Agent Management (Agents) ​

4. Agent Workspace (AgentWorkspace) ​

5. Tool Management (Tools) ​

6. MCP Servers (McpServers) ​

7. Skill Market (SkillMarket) ​

8. Channel Management (Channels) ​

9. Session Management (Sessions) ​

10. Cron Jobs (CronJobs) ​

11. Token Usage (TokenUsage) ​

12. Settings ​

12.1 Model Settings (Settings/Models) ​

12.2 System Settings (Settings/System) ​

12.3 About (Settings/About) ​

13. Security Center ​

13.1 Tool Guard (Security/ToolGuard) ​

13.2 File Guard (Security/FileGuard) ​

13.3 Audit Logs (Security/AuditLogs) ​

Pinia State Management ​

Store List ​

State Ownership Principle ​

Dark Mode ​

Three Modes ​

Implementation ​

Writing Styles ​

Internationalization (i18n) ​

Supported Languages ​

Language Files ​

Switching Language ​

Usage in Components ​

API Communication Layer ​

Axios Instance ​

Request Interceptor ​

Response Interceptor ​

SSE Streaming ​

Route Structure ​

Build and Development ​

Development Server ​

Production Build ​

Linting ​

Development Tips ​

Console UI

Tech Stack

Overall Layout

Sidebar

Auth Guard

Page Reference

1. Login

2. Chat Console (ChatConsole)

3. Agent Management (Agents)

4. Agent Workspace (AgentWorkspace)

5. Tool Management (Tools)

6. MCP Servers (McpServers)

7. Skill Market (SkillMarket)

8. Channel Management (Channels)

9. Session Management (Sessions)

10. Cron Jobs (CronJobs)

11. Token Usage (TokenUsage)

12. Settings

12.1 Model Settings (Settings/Models)

12.2 System Settings (Settings/System)

12.3 About (Settings/About)

13. Security Center

13.1 Tool Guard (Security/ToolGuard)

13.2 File Guard (Security/FileGuard)

13.3 Audit Logs (Security/AuditLogs)

Pinia State Management

Store List

State Ownership Principle

Dark Mode

Three Modes

Implementation

Writing Styles

Internationalization (i18n)

Supported Languages

Language Files

Switching Language

Usage in Components

API Communication Layer

Axios Instance

Request Interceptor

Response Interceptor

SSE Streaming

Route Structure

Build and Development

Development Server

Production Build

Linting

Development Tips