AI 模型管理
“AI 模型”用于统一维护提供商、认证方式、API Base URL、接口格式和可用模型。面板可以集中保存配置，但各 Agent 能否直接复用仍取决于对应应用、登录方式和版本。
AI 模型提供商、认证方式和可用模型开始前准备
- 准备服务商提供的 OAuth 账号或 API Key。
- 从服务商官方文档确认 Base URL、接口格式和模型 ID。
- 确认网络或代理可以访问目标接口。
- 了解模型计费规则；面板免费不代表模型调用免费。
凭据安全
不要在对话、截图、日志或导出文件中公开完整 API Key。反馈问题时只保留服务商名称、错误码和必要的 Key 前后少量字符。
配置一个提供商
- 点击左侧“AI 模型”。
- 从“选择提供商”列表选择服务商；没有预设项时再使用 Custom。
- 打开该提供商右侧的启用开关。
- 根据服务商支持情况选择 OAuth 或 API Key。
- 填写 API Key 和“API Base URL”。
- 在“API 格式”中选择 OpenAI 兼容或 Anthropic 兼容；必须与服务商文档一致。
- 点击“测试连接”。
- 确认可用模型列表加载完成，再到对话页选择模型。
完成状态
页面顶部显示“已开启”，测试连接成功，可用模型列表中至少有一个模型，并能在新建对话的模型选择器中看到它。
添加模型
当接口已经连接，但服务商没有自动返回目标模型时：
- 点击可用模型列表右侧“添加模型”。
- 按服务商文档填写准确的模型 ID 和显示名称。
- 保存后重新测试连接。
- 新建一个只包含简单问答的对话，确认该模型能够返回结果。
不要把市场名称当作模型 ID。一个多余空格、错误大小写或不存在的版本号都可能导致调用失败。
导入与导出
页面顶部的“导入”和“导出”用于迁移模型配置。导出前先确认文件是否包含凭据；导入后不要直接用于真实任务，应重新测试连接和模型列表。
多 Agent 兼容性
| Agent / 组件 | 需要核对 |
|---|---|
| OpenClaw / Hermes Agent | 是否读取面板提供商配置，目标模型是否支持所需工具调用 |
| Claude Code | 当前版本使用面板配置、OAuth，还是自身配置目录 |
| Codex | 当前版本使用面板配置、账号登录，还是自身配置文件 |
| Skill / MCP | 模型是否具备任务需要的上下文、工具调用或多模态能力 |
配置集中管理不代表四类 Agent 的认证方式、模型名称和工具能力完全相同。第一次接入时应逐个 Agent 做一次测试。
常见错误
| 现象 | 优先检查 |
|---|---|
| 401 / 403 | Key 是否有效、账号权限、额度和请求区域限制 |
| 404 | Base URL、接口路径或模型 ID 是否正确 |
| 429 | 余额、速率限制和并发量 |
| 连接超时 | 网络、代理、DNS、防火墙和服务状态 |
| 测试成功但对话失败 | 对话选择的提供商/模型、Agent 兼容性、上下文或工具要求 |
| 模型列表为空 | 提供商是否启用、接口格式是否匹配；必要时手动添加模型 |
排查时先记录错误码和发生时间，再到 日志中心 查看对应请求。