# 模型连接与调用排错

分清服务连接、模型调用和工具执行三个阶段。

## 先找失败发生在哪一步

服务测试、模型测试和真正执行任务检查的内容不同。保存配置只说明配置被接受；一次文本响应也不足以证明工具调用可用。

| 失败位置 | 先核对 | 验证方法 |
| --- | --- | --- |
| 保存配置 | 必填字段、协议和地址格式 | 重新打开条目检查保存值 |
| 测试服务 | 网络、认证、服务地址 | 在供应商页测试服务 |
| 测试模型 | 模型 ID、账号模型权限和额度 | 测试具体模型 |
| 开始任务 | Agent 或会话选中的模型 | 用一句普通文本请求测试 |
| 读取图片 | 输入类型和视觉模型 | 提供一张教学图片 |
| 使用工具 | 模型的工具能力与运行引擎 | 读取一份无敏感信息的文件 |

## 根据错误继续检查

401 通常指向凭据，403 指向授权，404 需要同时核对地址、协议和模型名称，429 要检查额度和频率。错误正文比状态码更具体，先保留正文再修改配置。

地址应填写服务要求的基础地址。不要在不知道接口规则时反复追加 `/v1`，也不要把网页聊天地址填成 API 地址。兼容服务的模型 ID 以该服务实际提供的名称为准。

## 保存一份最小复现

先使用一句普通文本请求，再测试一份教学文件读取。两次只改变输入类型或工具需求，保持 Agent、模型和引擎相同。

```text
第一步只回复“模型调用正常”，不使用工具。
```

```text
第二步读取工作区中指定的教学文件，回复其中的第一行。
如果找不到文件或工具不可用，说明具体停在哪一步。
```

第一步失败时继续查服务、模型与网络；第一步成功而第二步失败时，重点检查工具能力、权限和路径。这样能避免用一项复杂业务任务同时测试所有配置。

## 错误码后还要读正文

| 错误 | 进一步区分 | 恢复动作 |
| --- | --- | --- |
| 401 | 令牌错误、过期或使用了错误账号 | 更新凭据，再测试同一模型 |
| 403 | 账号或资源未获授权 | 确认该账号实际可用范围 |
| 404 | 模型 ID、基础地址或接口格式不匹配 | 对照提供方文档逐项核对 |
| 429 | 额度不足或请求过密 | 按错误正文恢复额度或降低并发 |
| 5xx / 超时 | 服务暂时失败、网关或出站网络异常 | 检查服务状态与原调用结果后再试 |

这些是诊断方向，最终以服务返回的错误正文为准。超时发生在工具写入之后时，应先核对文件或外部记录，不能直接假定整项任务未执行。

## 只有某个 Agent 失败

到联系人中检查该 Agent 是否指定了模型，再检查当前会话选择。常规设置里的默认模型不会覆盖所有显式选择。修改后在新一轮任务验证，不用同时改动多个服务。

## 电脑能访问，Web 版却超时

Web 版由服务器发起模型请求。请管理员检查服务器的 DNS、代理与出站连接。浏览器能打开服务首页，不能证明服务器能调用模型接口。

## 提供可复现的信息

记录 Nexus 版本、运行引擎、模型 ID、失败步骤、时间与错误正文。API Key、请求中的私人材料和完整身份令牌不应出现在反馈中。

配置入口见[模型服务](/docs/providers)，引擎选择见[运行设置](/docs/runtime)。修复后从失败的阶段开始复测，再完成一次小任务。