mateclaw/mateclaw-server/src/main/resources/docs/zh/models.md

模型配置

先配一个。后面随时加。

MateClaw 不关心你用哪个 LLM。它通过五个协议适配器跟所有主流供应商对话，支持 15+ 个云端供应商和 4 个本地运行时，你可以在运行时不动 Agent 配置直接切模型。MateClaw 唯一的意见是——从一个开始，需要再加，不是第一天就把所有东西配好。

---

支持什么

云端供应商

供应商	示例模型	协议	说明
DashScope（阿里云）	Qwen-Max、Qwen-Plus、Qwen-Turbo、Qwen-VL、Qwen-Long	dashscope	默认开箱即用
DashScope（兼容模式）	Qwen3.5-Plus、Qwen3.6-Plus、Qwen3 VL Plus 等点号版本号系列	openai	见下方"两个 DashScope 区别"
百炼 Token Plan	阿里百炼 token 包月套餐	dashscope	7 个种子模型；支持长 token
OpenAI	GPT-4o、GPT-4o-mini、GPT-5.5、o1、o3、o4-mini	openai	标准 OpenAI API
OpenAI OAuth（ChatGPT Plus/Pro）	通过订阅用 GPT-4o、o3、o4-mini	openai	浏览器 OAuth，不需要 API Key
Anthropic	Claude Opus 4.8 / 4.8 Fast（1.5.0+）、Claude 4.7、Claude 4.6 Sonnet、Claude 4.5 Haiku	anthropic	原生 Messages API；4.8 两个变体都支持 xhigh 思考档
Anthropic Claude Code OAuth	通过 Claude Pro/Max/Team 订阅用 Claude Opus 4.8 / 4.7 / 4.6	anthropic	浏览器 OAuth + 手动粘贴流，不需要 API Key
Google Gemini (原生)	gemini-2.5-flash、gemini-3-pro-image-preview、gemini-2.5-flash-image	gemini	原生 generateContent API（非 OpenAI 兼容）——见下方"原生 Gemini"
xAI / Grok	Grok 3、Grok 4	openai	OpenAI 兼容（base URL + API Key）；UI 带 xAI 品牌图标
DeepSeek	deepseek-chat、deepseek-coder、DeepSeek V4 flash + pro（支持思考模式）	openai	OpenAI 兼容
Kimi（Moonshot）	moonshot-v1-8k/32k/128k	openai	OpenAI 兼容
智谱 AI	GLM-5-Turbo、GLM-5V-Turbo、GLM-5、GLM-5.1、GLM-5.2	openai	OpenAI 兼容；中国区 + 国际区各一个 standard 端点，外加两个 Coding Plan 订阅端点
火山方舟 Agent Plan (1.8.0+)	GLM-5.2（主模型）等	openai	OpenAI 兼容；agent-plan 端点（/api/plan/v3）
MiniMax	abab6.5、abab5.5；扩展视频模型目录 + 国内端点	anthropic	Anthropic Messages API 兼容（端点 /anthropic）
SiliconFlow CN/INTL	托管路由推理	openai	双端点，OpenAI 兼容
OpenCode	代码场景路由	openai	OpenAI 兼容
OpenRouter	200+ 模型含免费档	openai	一个 key 路由到任何上游
小米 MiMo (1.3.0+)	MiMo V2.5 Pro / V2.5 / V2 Pro / V2 Omni / V2 Flash	openai	小米 MiMo 平台
任何 OpenAI 兼容服务	你自己的 vLLM 等	openai	自定义 base URL

本地运行时

运行时	示例模型	协议	说明
Ollama	Gemma 3/4、Qwen 3、Llama 3.1、DeepSeek R1、Mistral	ollama	启动时在 localhost:11434 自动检测
LM Studio	任何 GGUF 模型	openai	OpenAI 兼容服务器
llama.cpp	任何 GGUF 模型	openai	通过 llama-server
MLX	Apple Silicon 上的 mlx-lm	openai	OpenAI 兼容服务器

协议适配器

五个协议覆盖一切：

协议	谁在用
OpenAI	OpenAI、Kimi、DeepSeek、智谱、OpenRouter、LM Studio、llama.cpp、MLX
Anthropic	Claude 家族、MiniMax
DashScope	Qwen 家族
Gemini	Google Gemini 家族
Ollama	通过 Ollama 跑的本地模型

任何 OpenAI 兼容服务都能接——把 base-url 指过去就行。

---

两个 DashScope 区别

阿里云 DashScope 同一把 sk- API Key，两个端点面向不同模型族：

项	DashScope	DashScope（兼容模式）
端点	dashscope.aliyuncs.com/api/v1（native）	dashscope.aliyuncs.com/compatible-mode/v1（OpenAI-compatible）
协议	DashScope 原生协议	OpenAI 协议（同 GPT-4 / DeepSeek / Kimi 一样）
内置 web 搜索（enable_search）	✅ 支持	❌ 不支持
适用模型	Qwen-Max / Plus / Turbo / Long、Qwen-VL、Qwen3-Max、DeepSeek-V3.2 等	带点号版本号的新模型族：Qwen3.5-Plus、Qwen3.6-Plus、Qwen3 VL-Plus 等

为什么分两个：阿里把 dot-versioned 新模型族（qwen3.5-* / qwen3.6-* / qwen3-vl-*）只放在兼容模式端点上发布；用 native 协议调它们会返回 400 InvalidParameter。两个 provider 可以共用同一把 sk- Key，复制粘贴一次就好。

怎么选：

• 想用 Qwen-Max / Plus / Turbo + 内置搜索 / DeepSeek-V3.2 → DashScope
• 想用 Qwen3.5-Plus / Qwen3.6-Plus / Qwen3 视觉理解 → DashScope（兼容模式）
• 两个都启用也可以——同一把 Key，只是模型出现在不同卡片下

---

原生 Gemini

::: tip 1.4.0 新增 Gemini 不再走 OpenAI 兼容层——MateClaw 直接对接 Google 的原生 generateContent API。 :::

很多产品把 Gemini 当成"又一个 OpenAI 兼容端点"来接，结果在系统指令、函数调用、内联图片这些地方处处碰壁。MateClaw 走的是 Gemini 自己的协议：

• 原生 chat builder —— 正确映射 systemInstruction（系统指令）、functionCall / functionResponse（工具调用回合）、以及内联图片 part（多模态输入）
• 流式 SSE 解析 —— 按 Gemini 的流式响应格式逐块解析
• JSON Schema 清洗 —— 自动剥掉 Gemini 不接受的 JSON Schema 关键字，避免工具定义被拒
• 启动探活 —— 启动时发一个轻量请求确认凭证与模型可用

配置方式：设置 → 模型 → 添加供应商，选 Gemini 供应商，填 API Key。示例模型：gemini-2.5-flash、gemini-3-pro-image-preview、gemini-2.5-flash-image。图像生成走原生路径，详见 多模态创作 → 图像生成。

---

添加一个供应商

新装的 MateClaw 主列表是空的。这是故意的。

你不需要看见 16 个供应商，你需要一个能跑的。

设置 → 模型 → 添加供应商——按钮打开一个抽屉，里面是完整目录。本地运行时（Ollama、LM Studio、llama.cpp、MLX，不需要 API Key）排在前面，云端供应商（DashScope、OpenAI、Anthropic、DeepSeek 等）在后面。

三步：

1. 找到要的那一行，点启用——这个供应商进入主列表
2. 填 base URL（已知供应商预填）+ 粘贴 API Key——加密存储，UI 脱敏
3. 保存 → 测试连接——系统发一个轻量请求验证

抽屉关掉之后，主列表只显示你启用过的供应商。模型选择器、聊天页、Agent 编辑器——所有看得到模型的地方，都只看得到你启用过的。

::: tip 老用户升级（V55 迁移） 已经在用的供应商不会被关掉。V55 把符合以下任意一种条件的供应商自动标记为启用：

• 配过真实 API Key
• 有 OAuth token
• 最近 30 天被聊天会话使用过
• 是当前默认模型所在的供应商

没用过、留在数据库里占位的供应商，会回到抽屉里——你下次需要时再启用。 :::

---

启用 / 禁用一个供应商

主列表上每张供应商卡片都有启用 / 禁用开关。先启用，才可用——这是 v1.1.0 之后整个产品契约的核心。

• 禁用——供应商从模型选择器、聊天页、Agent 编辑器里立刻消失。配置不丢，重新启用后原样恢复
• 如果你禁用的是当前默认模型所在的供应商，系统会自动把默认模型切到一个还启用着的供应商上的模型——不会让下一条消息直接报错
• 启用——供应商重新出现在所有看得到模型的地方。从未填过 API Key 的话，会提示你去配

这把"我有这个供应商的 Key 但今天不想用它"和"我没这个供应商"分开。临时切供应商不需要删配置。

ChatGPT OAuth —— 不需要 API Key

有 ChatGPT Plus 或 Pro 账号？MateClaw 可以通过浏览器 OAuth 对接 OpenAI 的 chat 端点——你按平常方式登录，你的订阅被直接使用。GPT-4o、o3、o4-mini 立刻可用。

设置 → 模型 → 添加供应商 → OpenAI OAuth。浏览器窗口弹出。Token 交换在后端完成，凭证不离开你的机器。

设备授权（Device Authorization Grant）—— 远程 / 无头部署专用

浏览器回调式 OAuth 要求 IDP 的重定向能落回 你的浏览器 能访问的某个 localhost 端口。这事儿在 MateClaw 跑你笔记本上时没问题，一旦你把它放到服务器、容器、或任何不向客户端暴露 loopback socket 的宿主上，就立刻坏掉。

针对这种情况，OpenAI OAuth 会自动切到 设备授权（RFC 8628）——和 ChatGPT 桌面端、gh auth login 用的是同一个流程。不需要回调，不需要端口映射。

非 localhost 宿主下，设置 → 模型 → 添加供应商 → OpenAI OAuth 会弹出一个对话框，里面有：

• 一个短的用户码（等宽字体，可复制）
• 一个验证 URL：auth.openai.com/codex/device——任何设备的任何浏览器都能打开
• 一个实时倒计时，显示设备码还剩多久过期（默认 15 分钟）

把用户码填进浏览器、授权完成，对话框会在后端轮询拿到 COMPLETED 的瞬间自动关闭。

MateClaw 怎么决定走哪个流：

mateclaw.oauth.openai.deployment-mode	行为
auto （默认）	localhost / 127.0.0.1 / ::1 → 浏览器回调；其它 host → 设备授权
local	强制走浏览器回调（loopback 服务器）
device_code	强制走设备授权
manual_paste	强制走旧的"复制回调 URL 粘回来"流

如果 local 模式起不来 loopback 端口（端口被占、沙箱拒绝），会自动降级到 manual_paste。

后端端点：

Method	Path	用途
POST	/api/v1/oauth/openai/device/start	开一个会话，返回 deviceAuthId / userCode / verificationUrl / intervalSeconds / expiresInSeconds
POST	/api/v1/oauth/openai/device/poll	按 deviceAuthId 轮询，返回 PENDING / COMPLETED / EXPIRED
POST	/api/v1/oauth/openai/device/cancel	丢弃会话（比如用户关了对话框）

前端按 OpenAI 返回的 intervalSeconds（一般 5 秒）轮询；服务端再设一个最小轮询间隔（默认 3 秒）兜底，避免被打。过期的会话每 5 分钟扫一次清掉。

token 持久化和刷新走的是和浏览器回调流完全相同的代码路径，所以对话框关了之后行为没有任何差别。

Anthropic Claude Code OAuth

同样的套路、同样的结果：有 Claude Pro / Max / Team 订阅？走 Claude Code 自己用的那套 OAuth 流程 登录——不需要 sk-ant-… 的 API Key。Claude 4.7 / 4.6 / 4.5 Haiku 通过订阅上线。

设置 → 模型 → 添加供应商 → Anthropic Claude Code OAuth。支持两种流程：

• 浏览器回调 —— 本地安装，浏览器弹窗，点完授权 token 落到 MateClaw
• MANUAL_PASTE —— 远程服务器部署、浏览器到不了后端时，本地浏览器完成授权后把 token 粘回来

通过 anti-abuse 反滥用门：注入 Claude Code 身份到系统 prompt，请求形态（UA / accept 头 / system 数组形式 / mcp_ 工具名前缀）与 Claude Code 在线协议完全对齐，请求不会被拒绝。

---

模型发现

提供模型列表的供应商（OpenAI、Ollama、LM Studio、OpenRouter 等）支持模型发现——一键让 MateClaw 拉取这个供应商下的所有模型。

• 设置 → 模型 → [供应商卡片] → 发现模型
• 系统查询供应商的 /v1/models 端点
• 发现的模型带名字、上下文窗口、价格
• 逐个或批量添加

对 OpenRouter 特别有用——让 200+ 免费档模型全都可见。挑一个免费模型零成本有一套能用的环境。

自建供应商的模型发现

自己「添加供应商」建的兼容端点（vLLM / Xinference / LocalAI / 各类兼容网关）默认按协议开启发现：openai-compatible、dashscope-native、gemini-native、anthropic-messages 会自动带上「发现模型」按钮；OAuth 类协议（ChatGPT OAuth、Claude Code OAuth）不带（它们的发现走专属登录回调，与 baseUrl 无关）。

如果端点的模型列举路径不是标准的 /v1/models（例如反向代理加了前缀 /openai/v1/models），在「生成参数(JSON)」里加一行 modelsPath 覆盖即可：

{ "modelsPath": "/openai/v1/models" }

同一个 JSON 里的 completionsPath 用来覆盖对话补全路径（默认 /v1/chat/completions），两者互不影响。若端点根本不提供 OpenAI 风格的列举接口，直接用「添加模型」手动录入模型 id。

Ollama 启动时自动检测

不用手动配。启动时：

1. Ping http://127.0.0.1:11434
2. 发现——通过 /v1/models 拉取已拉的模型
3. 注册——加进 mate_model_config
4. 启用——自动启用匹配的预配置模型
5. 标签重写——把种子里的 :latest 重写为实际安装的版本（deepseek-r1:latest → deepseek-r1:7b），不再因为 model not found 报 404

Ollama 没跑就静默跳过。

::: tip 默认行为

• 无工具支持的模型（deepseek-r1、gemma*、phi3/4 等）不会被意外激活为默认——它们进入黑名单
• 在 native DashScope 协议下不可用的模型在启动时自动清理；带点号版本号的 Qwen 系列改由 DashScope（兼容模式）provider 承载
• DashScope 模型发现做协议感知探测，跳过非聊天模态 :::

预配置的 Ollama 模型（默认禁用，发现后自动启用）：

模型	model_name
Gemma 3	gemma3:latest
Gemma 4	gemma4:latest
Qwen 3	qwen3:latest
Llama 3.1	llama3.1:latest
DeepSeek R1	deepseek-r1:latest
Mistral	mistral:latest

配置：

# 从 ollama.com 安装 Ollama，然后：
ollama pull gemma3
ollama pull qwen3

重启 MateClaw。自动发现、添加、启用。

---

数据库 schema

mate_model_provider

列	用途
id	主键
name	供应商标识符
display_name	人类可读的名字
protocol	dashscope / openai / ollama / anthropic / gemini
base_url	API 基础 URL
api_key	加密的 API Key
oauth_tokens	OAuth tokens（ChatGPT Plus/Pro）
is_local	本地运行时为 true
enabled	供应商总开关——禁用后从所有模型选择器消失，配置保留（v1.1.0+）

mate_model_config

列	用途
id	主键
provider_id	外键到 mate_model_provider
model_name	实际的模型标识符
display_name	人类可读的名字
temperature	默认温度（0.0–2.0）
max_tokens	最大输出 token
top_p	top-p 采样
group_name	UI 分组（"Reasoning"、"Fast"、"Vision" 等）
enabled	模型开关

嵌入模型

不用配 EMBEDDING_API_KEY 环境变量。嵌入模型就是 mate_model_config 里 model_type='embedding' 的普通行。设置 → 模型 里和聊天模型列在一起。知识库从下拉里选它的嵌入模型。

::: tip 1.4.0 新增（issue #79） 任意供应商都能提供嵌入模型。 在 设置 → 模型 的嵌入区域里，配一个来自任何供应商的嵌入模型——直接复用那家供应商的 API Key，不再单独要 EMBEDDING_API_KEY。每个知识库从下拉里挑自己的嵌入模型。无密钥的本地代理用一个空操作占位 key；协议从该供应商的聊天模型 / protocol 设置里自动解析，不用再手填。 :::

Anthropic prompt 缓存

系统 prompt、Agent 人格、工具定义——在 Anthropic 兼容端点上自动带 cache_control: ephemeral。第一次请求热身，之后每次缓存命中。Dashboard 里有 cache_read_tokens / cache_write_tokens 日维度统计。

思考深度 / reasoning_effort

哪些模型会看这个参数：reasoning_effort 只对 OpenAI reasoning 族（gpt-5* / o1* / o3* / o4*）有效，且只通过 OpenAI / Azure-OpenAI 两家 provider 下发。任何别的 provider（DeepSeek、Kimi、DashScope、Ollama、自托管 OpenAI-兼容网关等）收到这个参数都会报错或触发异常行为。

三点产品契约：

1. Chat 类不带思维链的模型，即使用户在前端 UI 选择"深度思考 = high"，系统也不执行 thinking——不是 UI 问题，是能力属性。模型选择器换到不支持的模型后"思考深度"选项自动灰掉。
2. Provider 的 generateKwargs.reasoningEffort 配置只对白名单 provider 有效。在 DeepSeek / Kimi / 其他 OpenAI-兼容 provider 上配它会被无条件丢弃并打 WARN，不会实际下发。
3. Failover 切换时会再次校验：如果 primary 是 GPT-5 而 fallback 是 DeepSeek，reasoning_effort 会在出站前被剥除，泄漏到 DeepSeek 的不会触发 400。

DeepSeek thinking 的正确用法：DeepSeek 的 thinking 模式不接受 reasoning_effort 参数。

• deepseek-reasoner：模型本身自带 thinking，无需任何配置。
• deepseek-chat 想开启 thinking：按 DeepSeek 官方文档在 provider 的 generateKwargs.extra_body 里加 {"thinking": {...}}，不要填 reasoningEffort。

Kimi K2.5 thinking：模型自带 thinking，也不接受 reasoning_effort。

多轮 tool call + thinking：带 thinking 的模型（DeepSeek-Reasoner / GPT-5 / Kimi K2.5 / 小米 MiMo）在 ReAct 多轮 tool call 场景下，历史消息的 reasoning_content 会正确回传给 provider；跨用户问题边界时自动清除，同一问题内的子轮次全部保留——符合 DeepSeek 的"同问题子轮必须回传、跨问题时清"契约。

小米 MiMo 思考模式多轮修复（issue #189）：MiMo 思考模式的 reasoning_content 现在能在多轮对话里正确保留，不再在后续轮次丢失。

---

分组模型选择器

当你部署里配了一堆模型之后，聊天界面上的模型选择器按供应商和标签分组。带搜索的下拉框允许你按名字、供应商、分组过滤——"所有 Qwen"、"所有 reasoning 模型"、"所有 7B 以下"。分组通过 group_name 列定义。

当 Agent 可以按任务绑定不同模型之后，这变成了刚需——Plan-Execute 用 reasoning 模型、Chat 用便宜快速的、图像理解用视觉模型。

---

运行时切换活跃模型

MateClaw 用一个活跃模型作为全局默认。没有指定自己模型的 Agent 都用它。

• UI： 设置 → 模型 → [模型卡片] → 设为活跃
• API： PUT /api/v1/models/active

立刻生效——不需要重启。下一条消息用新模型。进行中的对话不受影响。

也支持按 Agent 覆盖：把某个 Agent 绑定到特定模型配置。

::: tip 1.4.0 新增

• 按会话选模型（issue #150）：在聊天界面里可以为当前这一条会话临时切换模型，不影响全局活跃模型和别的会话。详见 聊天与消息。
• 单个坏模型 id 不再连累整个供应商：发现 / 探活时遇到一个无效的模型标识符，只跳过那一个模型，供应商下其余模型照常可用。 :::

---

单模型测试

每个模型卡片都有测试按钮。点一下，系统发一个简单 prompt，给你看：

• 实际响应文本
• 延迟
• Token 用量
• 错误

加了新供应商或怀疑 key 过期时用它。

---

多模态旁路（系统级）

::: tip 1.3.0 新增 让纯文本主模型也能"看图回答"，参见 issue #87。 :::

入口：设置 → 模型 → 多模态旁路。两个独立的卡片：

卡片	用途	状态
视觉旁路模型	用户上传图片时调用一次，把图片转成结构化描述，再交给主对话模型	已上线
视频旁路模型	同样的思路用于视频	预留（v1 不接路由，仅持久化配置）

数据库存的是 mate_model_config.id（不是 modelName）——同一 model_name 在不同 provider 下都能存在（如 qwen-vl-max 同时挂 DashScope 和 OpenAI-Compatible），存名字会撞。两条 setting key：

• default.vision_model
• default.video_model

下拉只列支持对应 modality 的模型——筛选逻辑走后端 ModelCapabilityService.supports(...)，未启用 / 没声明 vision 能力的模型都不会出现在选项里。每张卡片有独立的"保存"按钮，互不干扰。

什么时候触发？运行时由 MultimodalRouter 决策（源码）：

• 主模型已支持图片 → 不路由（走原 native multimodal 路径）
• 主模型不支持图片 + 配了视觉旁路 → SIDECAR 策略，视觉模型转描述
• 主模型不支持图片 + 没配视觉旁路 → 跳过附件 + 文本提示让用户去配

具体的用户流程、徽章、提示条详见 聊天与消息 → 主模型不支持图片？走"多模态旁路"。

---

多模型 Failover

::: tip OpenAI 挂了 30 分钟，我的 AI 没停过一秒 上次 DashScope 限流抽风的 30 分钟里，我们的服务可用率是 100%。

用户看到的是回答正常说完——没有红色 error，没有"服务暂时不可用，请稍后再试"。主 provider 在用户那一句话回答的中途自动切到下一个健康的 provider，断点之后的 token 直接接上。

不是工程师讲的"自动重试"——是用户感知不到的故障转移。 :::

每个 provider 加进来都进入 AvailableProviderPool，启动时探活，配置变更自动重探。

• 自动 fallback —— 主 provider 返回 AUTH_ERROR / BILLING / MODEL_NOT_FOUND / NETWORK / 5xx 时，运行时滚到下一个 provider，而不是把错误抛到 UI
• 每个 agent 自定义优先级 —— 在 设置 → 模型 的拖拽编辑器里把某个 agent 锁成 "OpenAI 优先 → Anthropic → DashScope"
• 池子状态实时可见 —— 每个 provider 用绿/琥珀/红徽章标健康状态
• 5 协议探活 —— DashScope、OpenAI 兼容、Anthropic、Gemini、Ollama 风格
• 手动重探 + 配置变更自动重探 —— 换 key 不用重启
• 出口 sanitizer —— provider 专属选项（如 OpenAI 推理模型的 reasoning_effort）在 failover 到不支持的 provider 时被剥离，泄漏的选项不会让 fallback 报 400
• UI 区分 401 与会话过期 —— provider 认证错误和用户会话过期现在显示不同消息、不同处置

偏好提供商决定主模型（1.5.0）

1.5.0 之前，"每个 agent 自定义优先级"只影响 failover 顺序——主模型仍是全局默认。1.5.0 让这个偏好真的决定主模型选择。完整优先级链是：

1. 会话钉选模型最高优先——聊天头部 ModelSelector 给这个会话单独绑了模型，就用它（见按会话选模型）
2. 其次是 per-agent 的模型覆盖（modelName）——员工自己钉死了某个模型
3. 再次是全局默认模型
4. 以上都没有时，才进入偏好提供商路由——按偏好挑提供商的主模型

偏好提供商路由里有一道能力门禁：如果员工绑定的技能声明了 requires-model: vision 这类需求，路由会先挑能满足这些模态的提供商；满足不了再无约束回退。偏好存在 mate_agent_provider_preference 表（按 sortOrder 升序，越小优先级越高）。

---

API 配置

# 列已启用的供应商（主列表看到的）
curl http://localhost:18088/api/v1/models \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# 列完整目录（含未启用项）——Add Provider 抽屉用的就是这个
curl http://localhost:18088/api/v1/models/catalog \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# 启用一个供应商
curl -X POST http://localhost:18088/api/v1/models/{providerId}/enable \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# 禁用一个供应商（如其下模型为当前默认会自动切换）
curl -X POST http://localhost:18088/api/v1/models/{providerId}/disable \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# 添加一个模型配置
curl -X POST http://localhost:18088/api/v1/models \
  -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,
    "groupName": "Fast",
    "enabled": true
  }'

# 设置活跃模型
curl -X PUT http://localhost:18088/api/v1/models/active \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"providerId": "openai", "model": "gpt-4o"}'

# 发现模型
curl -X POST http://localhost:18088/api/v1/models/{providerId}/discover \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# 测试连接
curl -X POST http://localhost:18088/api/v1/models/{providerId}/test-connection \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

---

所有配置都走 UI

::: tip 模型配置 100% 通过 UI 管理。 没有任何 spring.ai.* 的 YAML 需要你手动改。所有供应商、所有 API Key、所有模型配置、所有切换——全部在 设置 → 模型 里，底层存在 mate_model_provider 和 mate_model_config 数据库表。 :::

UI 处理了你原本在 YAML 里会做的一切，外加几件 YAML 做不到的事：

• 添加供应商——选类型、粘 key、保存。数据库加密存储，UI 里脱敏显示。
• 测试连接——上线前先验证供应商。
• 模型发现——支持 /v1/models 的供应商一键拉取整个列表。
• 单模型测试——发一个测试 prompt，看真实响应、延迟、token 用量。
• 运行时切换活跃模型——不重启、不重载配置，下一条消息生效。
• 按 Agent 覆盖——把某个 Agent 绑定到特定的模型配置。

LLM API Key 不再读取环境变量——DASHSCOPE_API_KEY / OPENAI_API_KEY 这类设置已经没有任何效果。所有供应商、Key、模型都住在 UI 里。新装的实例启动时数据库里没有供应商，到「设置 → 模型 → 添加供应商」加你的第一家即可。

参考：Qwen 模型怎么挑

如果你用 DashScope，大致阵容是这样：

模型	上下文	适合
qwen-max	32K	复杂推理、分析
qwen-plus	32K	通用
qwen-turbo	8K	快速响应
qwen-vl-max	32K	视觉 + 语言
qwen-long	1M	超长文档

---

下一步

• 配置说明——完整配置参考
• Agent 引擎——Agent 怎么使用模型
• 控制台——模型管理 UI