Model Configuration

MateClaw supports 160+ models from multiple providers. This guide explains how to configure model providers, discover models, and switch between them.

Supported Providers

Provider	Example Models	Transport
DashScope (Alibaba)	Qwen-Max, Qwen-Plus, Qwen-Turbo, Qwen-VL	Cloud API
Ollama	Gemma 3/4, Qwen 3, Llama 3.1, DeepSeek R1, Mistral	Local (auto-discovery)
OpenAI	GPT-4o, GPT-4o-mini, o1	Cloud API
Kimi (Moonshot)	moonshot-v1-8k, moonshot-v1-32k	Cloud API
DeepSeek	deepseek-chat, deepseek-coder	Cloud API
Anthropic	Claude 3.5 Sonnet, Claude 3 Opus	Cloud API
Google Gemini	Gemini Pro, Gemini Ultra	Cloud API
Zhipu AI	GLM-5-Turbo, GLM-5V-Turbo, GLM-5, GLM-5.1	Cloud API
MiniMax	abab6.5, abab5.5	Cloud API
OpenAI-compatible	Any provider with OpenAI-compatible API	Cloud API

Protocol Support

MateClaw supports multiple model communication protocols, enabling integration with virtually all major providers:

Protocol	Description	Compatible Providers
OpenAI	Standard OpenAI API format	OpenAI, Kimi, DeepSeek, MiniMax, etc.
Anthropic	Anthropic Messages API	Anthropic Claude family
DashScope	Alibaba Cloud DashScope API	Qwen model family
Gemini	Google Generative AI API	Gemini family
Ollama	Local inference API	Locally hosted models via Ollama

Any service providing an OpenAI-compatible API can be integrated using the OpenAI protocol.

Database Tables

Model configuration uses two tables:

mate_model_provider

Stores provider-level settings:

Column	Description
id	Primary key
name	Provider identifier (dashscope, ollama, openai, etc.)
display_name	Human-readable name
protocol	Protocol type: dashscope / openai / ollama / anthropic / gemini
base_url	API base URL
api_key	Provider API key (encrypted)
enabled	Whether this provider is active

mate_model_config

Stores individual model configurations:

Column	Description
id	Primary key
provider_id	Foreign key to mate_model_provider
model_name	Model identifier (e.g., qwen-max)
display_name	Human-readable name
temperature	Default temperature (0.0 - 2.0)
max_tokens	Maximum output tokens
top_p	Top-p sampling parameter
enabled	Whether this model is available

Managing Models via the UI

The Settings page provides a comprehensive model management interface.

Add a Provider

1. Go to Settings -> Model Management
2. Click Add Provider
3. Enter the provider name, protocol, base URL, and API key
4. Click Save

Test Connection

After adding or editing a provider, click the Test Connection button to verify that the API URL and key are correct. The system sends a lightweight request to the provider to confirm connectivity.

Model Discovery

For providers that support model listing (such as OpenAI, Ollama), use the Discover Models feature to automatically retrieve all available models from the provider. Click the "Discover Models" button on the provider card. The system queries the provider API and lists available models, allowing you to add them to the system with one click.

Add Model Configs

Select a provider and specify the model name, display name, type, context window, and default parameters.

Per-Model Test

After adding a model, click the Test button on the model config card to send a simple message and verify that the model is working correctly. The test uses the current model configuration parameters and returns the model response along with latency information.

Active Model Switching

On the Model Management page, you can set the globally active model. Click the "Set as Active" button on any model to make it the system default. The switch takes effect immediately without restarting the service. New conversations and agents without a specified model will use the active model.

Per-Agent Override

Each agent can be assigned a specific model config, overriding the global default.

Managing Models via API

List model providers:

curl http://localhost:18088/api/v1/model-providers \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Add a model configuration:

curl -X POST http://localhost:18088/api/v1/model-configs \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "providerId": 1,
    "modelName": "qwen-plus",
    "displayName": "Qwen Plus",
    "temperature": 0.7,
    "maxTokens": 4096,
    "enabled": true
  }'

DashScope (Default Provider)

DashScope is the default provider, giving access to the Qwen model family.

Setup

1. Get an API key from the DashScope console
2. Set the environment variable:

export DASHSCOPE_API_KEY=sk-xxxxxxxxxxxxxxxx

Configuration

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

Available Models

Model	Context	Best For
qwen-max	32K	Complex reasoning, analysis
qwen-plus	32K	General tasks, good balance
qwen-turbo	8K	Fast responses, simple tasks
qwen-vl-max	32K	Vision + language tasks
qwen-long	1M	Very long documents

Model Management UI

The model management page groups providers into Local Models and Cloud Models:

• Local Models — Ollama, LM Studio, llama.cpp, MLX. Marked as is_local, no API key required.
• Cloud Models — DashScope, OpenAI, Anthropic, DeepSeek, etc. Requires API key.

Local providers always appear first for easy access.

Ollama (Local Models)

Ollama lets you run models locally without an API key.

Auto-Discovery on Startup

MateClaw automatically detects a running Ollama instance on startup (http://127.0.0.1:11434):

1. Ping — Check if Ollama is online
2. Discover — Fetch pulled models via /v1/models
3. Register — Add discovered models to the database
4. Enable — Auto-enable matching pre-configured models

If Ollama is not running, auto-discovery is silently skipped.

Pre-configured Models

6 popular Ollama models are pre-configured (disabled by default, auto-enabled on discovery):

Model	model_name	Description
Gemma 3	gemma3:latest	Google Gemma 3, lightweight
Qwen 3	qwen3:latest	Excellent Chinese capabilities
Llama 3.1	llama3.1:latest	Strong general-purpose
DeepSeek R1	deepseek-r1:latest	Reasoning model
Mistral	mistral:latest	Efficient inference
Gemma 4	gemma4:latest	Next-gen high-performance

Setup

1. Install Ollama from ollama.com
2. Pull a model:

ollama pull gemma3
ollama pull qwen3

3. Restart MateClaw — models are auto-discovered and enabled.

OpenAI

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      base-url: https://api.openai.com
      chat:
        options:
          model: gpt-4o
          temperature: 0.7

OpenAI-Compatible Providers

Many providers offer OpenAI-compatible APIs. Configure them using the OpenAI provider with a custom base URL:

Kimi (Moonshot)

spring:
  ai:
    openai:
      api-key: ${KIMI_API_KEY}
      base-url: https://api.moonshot.cn/v1
      chat:
        options:
          model: moonshot-v1-32k

DeepSeek

spring:
  ai:
    openai:
      api-key: ${DEEPSEEK_API_KEY}
      base-url: https://api.deepseek.com
      chat:
        options:
          model: deepseek-chat

Switching Models at Runtime

Agents can be switched to a different model without restart:

1. Update the agent's model config through the UI or API
2. Use the "Set as Active" button on the Model Management page to change the global default model
3. The switch takes effect immediately -- the next message processed uses the new model
4. In-flight conversations are not affected

Next Steps

• Configuration -- Full configuration reference
• Agent Engine -- How agents use models
• Settings Page -- UI for model management