模型配置

本文档介绍 MateClaw 支持的大模型提供商、模型配置方式以及相关功能。

支持的模型提供商

MateClaw 内置支持以下模型提供商，已预配置超过 160 个模型：

提供商	协议	典型模型	说明
DashScope (通义千问)	DashScope API	qwen-max, qwen-plus, qwen-turbo, qwen-long	阿里云百炼平台，默认提供商
Ollama	OpenAI 兼容	gemma3, qwen3, llama3.1, deepseek-r1, mistral, gemma4	本地部署，无需 API Key，启动自动发现
OpenAI	OpenAI API	gpt-4o, gpt-4-turbo, gpt-3.5-turbo	需要 OpenAI API Key
Kimi (月之暗面)	OpenAI 兼容	moonshot-v1-8k, moonshot-v1-32k, moonshot-v1-128k	支持超长上下文
DeepSeek	OpenAI 兼容	deepseek-chat, deepseek-coder	代码能力出色
Anthropic	Anthropic API	claude-3-opus, claude-3-sonnet, claude-3-haiku	需要 Anthropic API Key
Gemini (Google)	Gemini API	gemini-pro, gemini-1.5-pro	Google AI 平台
Zhipu AI (智谱)	OpenAI 兼容	glm-5-turbo, glm-5v-turbo, glm-5, glm-5.1	智谱 GLM 系列，支持国内版和国际版
MiniMax	OpenAI 兼容	abab6.5, abab5.5	国产大模型

协议支持

MateClaw 支持多种模型通信协议，可接入几乎所有主流模型提供商：

协议	说明	适用提供商
OpenAI	OpenAI 标准 API 格式	OpenAI、Kimi、DeepSeek、MiniMax 等
Anthropic	Anthropic Messages API	Anthropic Claude 系列
DashScope	阿里云百炼 API	通义千问系列
Gemini	Google Generative AI API	Gemini 系列
Ollama	本地推理 API	Ollama 托管的本地模型

任何提供 OpenAI 兼容 API 的服务均可通过 OpenAI 协议接入。

数据模型

模型提供商表（mate_model_provider）

字段	类型	说明
`id`	bigint	主键
`name`	varchar	提供商名称，如 "DashScope"
`protocol`	varchar	协议类型：`dashscope` / `openai` / `ollama` / `anthropic` / `gemini`
`base_url`	varchar	API 基础地址
`api_key`	varchar	API 密钥（加密存储）
`enabled`	tinyint	是否启用
`sort_order`	int	排序权重
`create_time`	datetime	创建时间
`update_time`	datetime	更新时间
`deleted`	tinyint	逻辑删除

模型配置表（mate_model_config）

字段	类型	说明
`id`	bigint	主键
`provider_id`	bigint	关联的提供商
`model_name`	varchar	模型标识，如 "qwen-max"
`display_name`	varchar	显示名称
`model_type`	varchar	类型：`chat` / `embedding` / `image`
`max_tokens`	int	最大输出 Token 数
`context_window`	int	上下文窗口大小
`enabled`	tinyint	是否启用
`properties`	json	扩展属性（温度、Top-P 等）
`create_time`	datetime	创建时间
`update_time`	datetime	更新时间
`deleted`	tinyint	逻辑删除

通过 UI 管理模型

添加提供商

进入 设置 -> 模型管理 页面
点击 添加提供商
填写提供商信息：
- 名称：如 "我的 OpenAI"
- 协议：选择对应协议类型
- Base URL：API 地址（如 https://api.openai.com/v1）
- API Key：填入密钥
点击保存

测试连接

添加或编辑提供商后，可以点击「测试连接」按钮验证 API 地址和密钥是否正确。系统会尝试向提供商发送一个轻量请求，确认连接可用性。

模型发现

对于支持模型列表查询的提供商（如 OpenAI、Ollama），可以使用「模型发现」功能自动获取该提供商下所有可用模型。点击提供商卡片中的「发现模型」按钮，系统会查询提供商 API 并列出可用模型，支持一键添加到系统中。

添加模型

在提供商卡片中点击 添加模型
填写模型信息：
- 模型标识：如 gpt-4o
- 显示名称：如 "GPT-4o"
- 类型：选择 chat
- 上下文窗口：如 128000
- 最大输出 Token：如 4096
点击保存

单模型测试

添加模型后，可以在模型配置卡片上点击「测试」按钮，发送一条简单消息验证该模型是否正常工作。测试会使用当前模型配置的参数发送请求，返回模型响应及耗时信息。

活跃模型切换

在模型管理页面，可以设置全局活跃模型。点击某个模型的「设为活跃」按钮，该模型将成为系统默认使用的模型。切换即时生效，无需重启服务。后续新建的对话和未指定模型的 Agent 将使用该活跃模型。

在 Agent 中使用模型

创建或编辑 Agent 时，在模型选择下拉框中选择已配置的模型即可。每个 Agent 可以独立选择不同的模型。

配置 API Key

方式一：环境变量（推荐）

bash

# DashScope（必需）
export DASHSCOPE_API_KEY=sk-your-dashscope-key

# 其他提供商（可选）
export OPENAI_API_KEY=sk-your-openai-key
export ANTHROPIC_API_KEY=sk-ant-your-key
export KIMI_API_KEY=your-kimi-key
export DEEPSEEK_API_KEY=your-deepseek-key

方式二：UI 配置

在 设置 -> 模型管理 中，编辑对应提供商并填入 API Key。密钥会加密存储在数据库中。

方式三：application.yml

yaml

mateclaw:
  llm:
    dashscope:
      api-key: ${DASHSCOPE_API_KEY}
    openai:
      api-key: ${OPENAI_API_KEY}
      base-url: https://api.openai.com/v1

内置搜索集成

MateClaw 支持大模型内置搜索能力，适用于需要实时信息的场景。

配置方式

在模型配置的扩展属性中启用：

json

{
  "enable_search": true,
  "search_strategy": "pro"
}

搜索策略

策略	说明
`auto`	模型自动判断是否需要搜索
`pro`	增强搜索，适合需要最新信息的场景
`standard`	标准搜索

Kimi $web_search

Kimi 模型支持通过 $web_search 工具进行网络搜索：

json

{
  "enable_search": true,
  "search_tool": "$web_search"
}

启用后，Kimi 在回答问题时会自动搜索网络获取最新信息，并在回复中附带搜索结果引用。

模型管理界面

模型管理页面将 Provider 按本地模型和云端模型分组展示：

本地模型 — Ollama、LM Studio、llama.cpp、MLX，标记为 is_local，无需 API Key
云端模型 — DashScope、OpenAI、Anthropic、DeepSeek 等，需要配置 API Key

本地 Provider 始终排列在最前面，方便优先使用本地推理。

本地模型（Ollama）

启动自动发现

MateClaw 启动时会自动探测本地运行的 Ollama 实例（默认 http://127.0.0.1:11434）：

Ping 探测 — 检查 Ollama 是否在线
模型发现 — 调用 /v1/models 获取已拉取的模型列表
自动注册 — 将发现的模型注册到数据库
自动启用 — 匹配预配置模型（如 gemma3、qwen3）自动设为启用状态

如果 Ollama 未运行，自动发现会静默跳过，不影响启动。

预配置模型

MateClaw 内置了 6 个热门 Ollama 模型预配置（默认禁用，自动发现后启用）：

模型	model_name	说明
Gemma 3	`gemma3:latest`	Google Gemma 3，轻量高效
Qwen 3	`qwen3:latest`	通义千问 3，中文能力出色
Llama 3.1	`llama3.1:latest`	Meta Llama 3.1，通用能力强
DeepSeek R1	`deepseek-r1:latest`	DeepSeek R1 推理模型
Mistral	`mistral:latest`	Mistral 7B，高效推理
Gemma 4	`gemma4:latest`	Google Gemma 4，新一代高性能

安装 Ollama

bash

# macOS
brew install ollama

# Linux
curl -fsSL https://ollama.ai/install.sh | sh

拉取模型

bash

ollama pull gemma3
ollama pull qwen3
ollama pull llama3.1

拉取完成后重启 MateClaw，模型会被自动发现并启用。

注意事项

Ollama 默认监听 localhost:11434，MateClaw 已预配置此地址
建议至少 8GB 内存运行 7B 模型
可同时配置多个本地模型，在 Agent 中按需选择
设为激活模型时会自动启用（无需手动启用）
Ollama 不支持内置搜索功能，需配合工具使用

模型参数调整

在 Agent 编辑页面或模型配置中，可以调整以下参数：

参数	默认值	说明
`temperature`	0.7	生成随机性，0 为确定性输出，1 为最大随机性
`top_p`	0.9	核采样阈值
`max_tokens`	4096	单次回复最大 Token 数
`presence_penalty`	0	存在惩罚，减少重复话题
`frequency_penalty`	0	频率惩罚，减少重复用词

常见问题

Q: 如何确认模型配置是否生效？

在聊天页面发送消息后，可以在消息详情中查看实际使用的模型名称和 Token 消耗。

Q: 切换模型后历史消息会丢失吗？

不会。模型切换只影响后续的回复，历史消息保留在会话中。

Q: 多个提供商配置了同名模型怎么办？

系统会按提供商的 sort_order 优先级选择。建议避免同名配置。

Q: 模型发现功能支持哪些提供商？

目前支持 OpenAI 兼容 API 和 Ollama 的模型发现。其他提供商需要手动添加模型配置。

模型配置 ​

支持的模型提供商 ​

协议支持 ​

数据模型 ​

模型提供商表（mate_model_provider） ​

模型配置表（mate_model_config） ​

通过 UI 管理模型 ​

添加提供商 ​

测试连接 ​

模型发现 ​

添加模型 ​

单模型测试 ​

活跃模型切换 ​

在 Agent 中使用模型 ​

配置 API Key ​

方式一：环境变量（推荐） ​

方式二：UI 配置 ​

方式三：application.yml ​

内置搜索集成 ​

配置方式 ​

搜索策略 ​

Kimi $web_search ​

模型管理界面 ​

本地模型（Ollama） ​

启动自动发现 ​

预配置模型 ​

安装 Ollama ​

拉取模型 ​

注意事项 ​

模型参数调整 ​

常见问题 ​

模型配置

支持的模型提供商

协议支持

数据模型

模型提供商表（mate_model_provider）

模型配置表（mate_model_config）

通过 UI 管理模型

添加提供商

测试连接

模型发现

添加模型

单模型测试

活跃模型切换

在 Agent 中使用模型

配置 API Key

方式一：环境变量（推荐）

方式二：UI 配置

方式三：application.yml

内置搜索集成

配置方式

搜索策略

Kimi $web_search

模型管理界面

本地模型（Ollama）

启动自动发现

预配置模型

安装 Ollama

拉取模型

注意事项

模型参数调整

常见问题