Configuration

MateClaw is configured through Spring Boot's application.yml, environment variables, and database-stored settings. This guide covers all configuration options.

Application Profiles

MateClaw ships with two Spring profiles:

Profile	Database	Activated By
default	H2 (file-based, ./data/mateclaw)	No special config needed
mysql	MySQL 8.0+	spring.profiles.active=mysql

The Docker deployment activates the mysql profile automatically.

Core Configuration (application.yml)

Server Settings

server:
  port: 18088                    # HTTP port (dev default)
  servlet:
    context-path: /              # Root context path

Database -- H2 (Development)

spring:
  datasource:
    url: jdbc:h2:file:./data/mateclaw;MODE=MYSQL
    username: sa
    password:
    driver-class-name: org.h2.Driver
  h2:
    console:
      enabled: true              # Access at /h2-console

Database -- MySQL (Production)

spring:
  profiles:
    active: mysql
  datasource:
    url: jdbc:mysql://localhost:3306/mateclaw?useSSL=false&serverTimezone=UTC
    username: root
    password: ${MYSQL_ROOT_PASSWORD}
    driver-class-name: com.mysql.cj.jdbc.Driver

AI Model Configuration

spring:
  ai:
    dashscope:
      api-key: ${DASHSCOPE_API_KEY}
      chat:
        options:
          model: qwen-max         # Default model
          temperature: 0.7
          max-tokens: 4096

MCP Server Configuration

mateclaw:
  mcp:
    servers:
      - name: filesystem
        transport: stdio
        command: npx
        args:
          - "-y"
          - "@anthropic/mcp-filesystem"
          - "/path/to/workspace"
      - name: remote-api
        transport: sse
        url: http://localhost:3001/sse

JWT Authentication

mateclaw:
  auth:
    jwt:
      secret: your-jwt-secret-key-at-least-32-characters
      expiration: 86400000        # Token TTL in milliseconds (24 hours)
      sliding-window: true        # Auto-renew tokens nearing expiry

Tool Guard

mateclaw:
  tool:
    guard:
      enabled: true               # Require approval for dangerous tools
      dangerous-tools:
        - ShellExecuteTool
        - WriteFileTool
        - EditFileTool

Environment Variables

Environment variables override application.yml values. These are the key variables:

Variable	Required	Description
DASHSCOPE_API_KEY	No	Alibaba DashScope API key (can also be configured in UI via Settings > Model Management)
SERPER_API_KEY	No	Google Serper API key (migrated to System Settings UI)
TAVILY_API_KEY	No	Tavily API key (migrated to System Settings UI)
MYSQL_ROOT_PASSWORD	Docker only	MySQL root password
SPRING_PROFILES_ACTIVE	No	Set to mysql for production

Setting Environment Variables

Linux / macOS:

export DASHSCOPE_API_KEY=sk-xxxxxxxxxxxxxxxx
export SERPER_API_KEY=xxxxxxxxxxxxxxxx

Windows (PowerShell):

$env:DASHSCOPE_API_KEY = "sk-xxxxxxxxxxxxxxxx"

Docker (.env file):

DASHSCOPE_API_KEY=sk-xxxxxxxxxxxxxxxx
MYSQL_ROOT_PASSWORD=secure-password-here

Database Configuration

SQL Initialization

On first startup, MateClaw automatically runs:

1. db/schema.sql -- Creates all mate_* tables
2. db/data.sql -- Inserts seed data (default admin user, built-in agent, etc.)

Table Naming Conventions

• All tables use the mate_ prefix
• Column names use snake_case; Java fields use camelCase (auto-mapped by MyBatis Plus)
• Every table has create_time, update_time, and deleted columns
• Logical delete: deleted = 0 means active, deleted = 1 means soft-deleted

Connecting to H2 in Dev Mode

Navigate to http://localhost:18088/h2-console and use:

Field	Value
JDBC URL	jdbc:h2:file:./data/mateclaw
Username	sa
Password	(leave empty)

Switching to MySQL

1. Create the database:

CREATE DATABASE mateclaw CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

2. Activate the mysql profile:

export SPRING_PROFILES_ACTIVE=mysql
export MYSQL_ROOT_PASSWORD=your-password
mvn spring-boot:run

Model Provider Settings

Model providers are configured through the database table mate_model_provider and managed from the Settings page in the UI. You can also set defaults in application.yml:

spring:
  ai:
    ollama:
      base-url: http://localhost:11434
      chat:
        options:
          model: qwen2.5:7b
    openai:
      api-key: ${OPENAI_API_KEY:}
      base-url: https://api.openai.com

See Model Configuration for detailed provider setup.

System Settings (Database)

Runtime settings stored in the mate_system_setting table can be changed from the Settings page without restarting:

Key	Type	Description
default_agent_id	Long	Agent used when no agent is specified
default_model_config_id	Long	Default model configuration
max_conversation_turns	Integer	Maximum turns per conversation
enable_memory	Boolean	Enable long-term memory features

Search Service Configuration

Web search configuration has been migrated from application.yml to the System Settings page. Changes take effect immediately without restart.

Setting	Description
Search Enabled	Whether the search tool is available to agents
Search Provider	serper (Google Serper) or tavily (Tavily)
Fallback on Failure	Automatically try the other provider when the primary fails
Serper API Key	Get from serper.dev
Serper Base URL	Default: https://google.serper.dev/search
Tavily API Key	Get from tavily.com
Tavily Base URL	Default: https://api.tavily.com/search

TIP

API keys are displayed in masked form in the UI. When saving, keys are only overwritten if a new value is entered.

Logging

logging:
  level:
    vip.mate: DEBUG              # Application logs
    org.springframework.ai: INFO # Spring AI logs
    root: INFO

For troubleshooting, temporarily set vip.mate to TRACE to see full agent reasoning steps and tool call details.

CORS Configuration

In development, the Vite dev server handles CORS via its proxy. In production (when the frontend is embedded in the JAR), CORS is not needed. If you deploy the frontend separately, configure allowed origins:

mateclaw:
  cors:
    allowed-origins:
      - http://localhost:5173
      - https://your-domain.com

Configuration Precedence

Settings are resolved in this order (highest priority first):

1. Environment variables
2. Command-line arguments (--server.port=9090)
3. application-{profile}.yml
4. application.yml
5. Database system settings (for runtime-configurable values)

Next Steps

• Model Configuration -- Set up DashScope, Ollama, OpenAI, and more
• Security -- JWT and tool guard details
• Channels -- Configure DingTalk, Feishu, Telegram webhooks