模型配置
适用对象
本文适合管理员或维护者。普通用户通常不需要进入模型配置页面。
这是什么
模型配置用于维护 xAgent 可以使用的模型。管理员在这里配置模型名称、服务地址、密钥、能力开关和默认策略。配置完成后，普通用户在会话中直接使用，不需要自己填写这些信息。
当前版本开放模型配置页面，主要是为了方便部署、试用和评估，让管理员可以先把可用模型接入进来。这是一个过渡期入口，不代表后续最终的模型使用方式。
后续在内置 Agent 小脑能力完善后，模型会逐步交给统一模型管理接管。xAgent 不会局限于某一个模型或某一家供应商。不同模型各有所长，有的适合快速总结，有的适合复杂推理，有的适合工具协作，有的适合图片或文件理解。
xAgent 会根据持续测试和实际使用结果优化模型路由，结合任务类型、成本、速度、工具协作需求和上下文情况，选择更适合当前任务的模型组合，以更稳定、更高质量地完成工作。普通用户不需要关心具体该选哪个模型，只需要说明任务目标。
什么时候使用
下面情况需要进入模型配置：
- 初次部署后，需要添加可用模型。
- 模型服务地址、密钥或真实模型名发生变化。
- 需要测试某个模型是否能连通。
- 需要调整模型是否支持图片、文件、工具调用或流式输出。
- 需要为不同任务准备不同模型。
页面怎么看
左侧是模型列表，右侧是当前模型的编辑区域。常见字段包括：
| 字段 | 用途 |
|---|---|
| 模型名 | 在 xAgent 页面中显示的名称 |
| 真实模型名 | provider 实际使用的模型标识 |
| Provider 类型 | 模型服务类型 |
| Base URL | 模型服务地址 |
| API Key | 模型服务密钥 |
| 请求超时 | 单次请求最长等待时间 |
| 说明 | 给管理员看的用途备注 |
| 模型能力 | 标记是否支持聊天、视觉、音频、文件、流式输出、工具调用 |
| 默认策略 Raw JSON | 维护高级默认策略 |
| HTTP Headers | 维护额外请求头 |
普通用户不需要理解这些字段。管理员只要保证模型能连通、能力开关准确、说明清楚即可。
基本用法
新建模型
- 点击 新建模型。
- 填写页面显示的模型名。
- 填写真实模型名。
- 选择 Provider 类型。
- 填写 Base URL 和 API Key。
- 按实际能力勾选模型能力。
- 点击 测试连接。
- 测试通过后点击 保存当前模型。
模型名建议面向使用场景命名，例如“通用写作模型”“代码与工具模型”“轻量快速模型”。不要只写内部缩写，避免普通用户无法判断用途。
测试连接
保存前建议先测试连接。测试失败时，优先检查：
- Base URL 是否正确。
- API Key 是否有效。
- 真实模型名是否存在。
- Provider 类型是否选对。
- 当前服务器是否能访问模型服务。
- 请求超时时间是否过短。
调整能力开关
能力开关要按模型真实支持情况配置。不要为了“看起来更强”而全部打开。
| 能力 | 影响 |
|---|---|
| 聊天 | 是否可用于普通对话和任务 |
| 视觉 | 是否可处理图片输入 |
| 音频 | 是否可处理音频输入或输出 |
| 文件 | 是否可处理文件输入 |
| 流式 | 是否支持边生成边显示 |
| 工具调用 | 是否能配合工具完成动作 |
如果某个模型不支持工具调用，就不适合承担需要读取文件、调用外部系统或执行动作的任务。
管理建议
- 当前模型配置页面是过渡期开放能力，适合先完成部署验证和模型接入，不建议把它理解为长期最终的模型治理界面。
- 至少准备一个稳定通用模型，给普通任务使用。
- 为需要工具调用的任务准备支持工具调用的模型。
- 为成本敏感任务准备轻量模型。
- 不要把系统能力绑定到单一供应商。不同模型适合不同任务，后续模型路由会基于测试结果持续优化。
- 模型说明要写给管理员和使用者看，不要只写供应商内部信息。
- API Key 不要出现在截图、文档、聊天消息或提交记录中。
- 修改公共模型前，确认是否影响正在使用的会话。
常见问题
普通用户需要自己配置模型吗？
通常不需要。管理员配置好后，普通用户直接在会话中使用。
后续统一模型管理和任务路由完善后，普通用户会更少感知具体模型选择，只需要说明任务目标。
测试连接成功就代表所有任务都能完成吗？
不一定。测试连接只说明模型服务可用。任务能否完成还取决于能力开关、工具、Skill、外部连接和审批策略。
为什么会话里要切换模型？
不同模型适合不同任务。比如有的适合快速总结，有的适合复杂推理，有的适合工具协作。切换模型不代表要重新开始整个会话。
截图能不能保留 Base URL 和 API Key？
不建议。公开文档或公开渠道中的截图应遮盖内部地址、密钥和账号信息。