xAgent 模型配置：Provider、工具调用与任务路由
版本范围：下文当前字段与行为按 2026-10-01 源码
43d2698核对。较早公开二进制可能不同；遇到界面或操作差异时，先核对自己的安装版本。
适用对象
本文适合管理员或维护者。普通用户通常不需要进入模型配置页面。
入口： 管理后台 > 系统配置 > 模型配置（/admin/models）。模型角色分工在 /admin/config/agent-roles 维护，普通用户在会话中使用已配置模型。
这是什么
模型配置用于维护 xAgent 可以使用的模型。管理员在这里配置模型名称、服务地址、密钥、能力开关和默认策略。配置完成后，普通用户在会话中直接使用，不需要自己填写这些信息。
当前版本开放模型配置页面，主要是为了方便部署、试用和评估，让管理员可以先把可用模型接入进来。这是一个过渡期入口，不代表后续最终的模型使用方式。
以下统一模型管理与自动路由属于后续方向，不是当前页面已保证的自动选模能力。后续在内置 Agent 小脑能力完善后，模型计划逐步交给统一模型管理接管。xAgent 不会局限于某一个模型或某一家供应商。不同模型各有所长，有的适合快速总结，有的适合复杂推理，有的适合工具协作，有的适合图片或文件理解。
xAgent 会根据持续测试和实际使用结果优化模型路由，结合任务类型、成本、速度、工具协作需求和上下文情况，选择更适合当前任务的模型组合，以更稳定、更高质量地完成工作。普通用户不需要关心具体该选哪个模型，只需要说明任务目标。
图例说明：这张
v005图片展示旧版左右分栏。当前页面以模型表格配合新建 / 编辑抽屉操作；文生图已使用独立 Provider，不能按旧图在聊天模型中直接开启。
什么时候使用
下面情况需要进入模型配置：
- 初次部署后，需要添加可用模型。
- 模型服务地址、密钥或真实模型名发生变化。
- 需要测试某个模型是否能连通。
- 需要调整模型是否支持聊天、图片生成、图片或文件输入、音频与工具调用。
- 需要为不同任务准备不同模型。
页面怎么看
从模型列表点击新建或编辑，打开对应配置抽屉；列表还提供连接测试、设为默认和适用的删除入口。常见字段包括：
| 字段 | 用途 |
|---|---|
| 模型名 | 在 xAgent 页面中显示的名称 |
| 真实模型名 | provider 实际使用的模型标识 |
| 上游模型候选 | OpenAI 兼容 Provider 可按当前连接草稿读取上游目录并筛选，也可手工输入真实模型名；它不是用户端 /api/models 已配置模型列表 |
| Provider 类型 | 模型服务类型 |
| Base URL | 模型服务地址 |
| API Key | 模型服务密钥 |
| 请求超时 | 单次请求最长等待时间 |
| 最大并发数 | 控制同一模型配置的请求并发；应与上游限额和服务器容量相匹配 |
| 上下文上限与最大输出 | 按模型服务公布的实际限制设置，避免请求预算超过窗口 |
| 推理与思考参数 | 按模型兼容性设置推理强度、思考开关、思考 token 和思考温度 |
| 说明 | 给管理员看的用途备注 |
| 模型能力 | 聊天 Provider 配置聊天、工具调用、视觉、音频和文件；独立文生图 Provider 只声明文生图 |
| 默认策略 Raw JSON | 维护高级默认策略 |
| HTTP Headers | 维护额外请求头 |
普通用户不需要理解这些字段。管理员只要保证模型能连通、能力开关准确、说明清楚即可。
先选择正确的 Provider
当前 Provider 列表包含 OpenAI Chat Completions、OpenAI Responses、OpenAI Images、Gemini 和 Anthropic。前两种是不同聊天协议，应按上游实际接口选择，不能仅凭服务名称判断。
OpenAI Images 属于独立文生图协议：
- 不能设为默认聊天模型，也不进入聊天或流式输出链路。
- 需要在 Agent 角色配置中为“文生图 Agent”选择对应模型。
- 文生图请求策略可维护上游支持的
size、quality、output_format等参数；提示词、模型和单图数量由系统设置。
聊天模型的视觉输入与文生图是不同能力。模型能理解图片，不代表它能生成图片。
基本用法
新建模型
- 点击 新建模型。
- 填写页面显示的模型名。
- 填写真实模型名。
- 选择 Provider 类型。
- 填写 Base URL 和 API Key。
- 按实际能力勾选模型能力。
- 点击 测试连接。
- 测试通过后点击 创建；修改已有模型时点击 保存当前模型。
模型名建议面向使用场景命名，例如“通用写作模型”“代码与工具模型”“轻量快速模型”。不要只写内部缩写，避免普通用户无法判断用途。
从 v0.0.18.beta 起，OpenAI 兼容 Provider 可列出上游模型候选，仍可手工填写模型 ID。上下文上限、最大输出和思考参数有独立字段，其他 Provider 扩展参数继续使用 Raw JSON；不要把不支持的参数强行加给模型。会话用量优先展示 Provider 返回的实测值，未返回时才使用估算。
测试连接
保存前建议先测试连接。测试失败时，优先检查：
- Base URL 是否正确。
- API Key 是否有效。
- 真实模型名是否存在。
- Provider 类型是否选对。
- 当前服务器是否能访问模型服务。
- 请求超时时间是否过短。
连接测试使用当前配置草稿发起请求，不代表草稿已保存，也不能证明所有声明能力都通过验证。保存后，再分别用普通对话、一次可控工具调用，以及实际需要的图片 / 文件输入做验证；文生图应单独测试。
调整能力开关
能力开关要按模型真实支持情况配置。不要为了“看起来更强”而全部打开。
| 能力 | 影响 |
|---|---|
| 聊天 | 是否可用于普通对话和任务 |
| 生成图片 | 由独立 OpenAI Images 配置和文生图角色支持 image_generate；不是聊天 Provider 的可选开关 |
| 视觉 | 是否可处理图片输入 |
| 音频 | 是否可处理音频输入或输出 |
| 文件 | 是否可处理文件输入 |
| 工具调用 | 是否能配合工具完成动作 |
流式输出仍是接入模型时需要实测的运行行为，但它不再是模型能力开关。
当前聊天模型固定为文本输出；保存配置时会移除原生结构化输出字段。不要把 Raw JSON 当成绕过 Provider 兼容性与产品约束的入口。
如果某个模型不支持工具调用，就不适合承担需要读取文件、调用外部系统或执行动作的任务。
管理建议
- 当前模型配置页面是过渡期开放能力，适合先完成部署验证和模型接入，不建议把它理解为长期最终的模型治理界面。
- 至少准备一个稳定通用模型，给普通任务使用。
- 为需要工具调用的任务准备支持工具调用的模型。
- 为成本敏感任务准备轻量模型。
- 不要把系统能力绑定到单一供应商。不同模型适合不同任务，后续模型路由会基于测试结果持续优化。
- 模型说明要写给管理员和使用者看，不要只写供应商内部信息。
- API Key 不要出现在截图、文档、聊天消息或提交记录中。
- 修改公共模型前，确认是否影响正在使用的会话。