本节汇总模型接入过程中最常见的连接失败、鉴权错误及切换异常，按现象直接给出排查步骤。
1. 状态栏显示红色感叹号 / "连接失败"
| 可能原因 | 排查与解决 |
|---|---|
| 网络不通 | 云端模型：浏览器能否打开对应服务商官网；私有化模型：ping 或 curl 一下 Base URL 所在 IP。 |
| Base URL 填写错误 | 检查末尾是否缺少或多余 /v1。例如：Ollama 应填 http://localhost:11434/v1；vLLM 与 OpenAI 兼容接口通常也是 http://<IP>:8000/v1。 |
| 代理/防火墙拦截 | 公司内网或海外模型需要代理时，在 OpenCode 设置页的「网络代理」填入 http://代理地址:端口；若使用系统代理，确认 IDE 已勾选「使用系统代理」。 |
| 模型服务未启动 | 本地模型确认 Ollama / vLLM / llama.cpp 进程已在后台运行，且监听端口正确。 |
2. 测试连接返回 401 / 403
- Key 复制不全：检查 API Key 前后是否有空格或换行，建议粘贴后手动删除首尾空白。
- Key 已过期或被撤销：登录对应云厂商控制台重新生成 Key 并替换。
- 权限不足：部分企业账号的 Key 仅开放了特定模型，调用未授权模型会报 403；联系管理员确认该 Key 的模型权限范围。
- 私有化部署开了鉴权：如果服务端配置了 Token 验证，插件里随意填写的占位符（如
sk-local）会触发 401；需向管理员索要真实 Key。
3. 本地模型连接正常，但补全或对话无响应
- 模型没加载到显存：Ollama 首次运行某模型时需要拉取并加载，可能耗时数十秒；观察系统显存占用是否有波动。
- 显存溢出（OOM）：本地 GPU 显存不足时，模型可能直接崩溃或无输出。解决方案：换更小的模型（如 7B 代替 14B）、缩短 OpenCode 里的
Max Tokens与上下文长度、关闭其他占用显存的程序。 - 补全模型与对话模型未分别指定：参考 2.2.3 节，确认「补全模型」和「对话模型」下拉框都已选中有效条目，而非空选。
- 日志定位：VS Code 按
Ctrl+Shift+U打开 Output 面板，选择OpenCode查看实时报错；JetBrains 在Help→Show Log in Explorer/Finder中检索OpenCode关键字。
4. 切换模型后不生效
- 补全与对话是两套系统：在状态栏或侧边栏顶部切换的是「当前对话模型」，不影响代码补全模型；如需更换补全模型，必须进入 OpenCode 设置页修改。
- 工作区设置覆盖全局：检查项目根目录下的
.vscode/settings.json（VS Code）或.idea目录相关文件，确认是否硬编码了旧的模型配置。 - 旧对话上下文未清理：切换模型后，已开启的聊天窗口可能仍沿用原模型，新建一个对话页再试。
**5. 响应慢、频繁超时
- 超时阈值过低：海外模型（OpenAI、Anthropic 官方）在国内访问延迟较高，可将「请求超时」从默认 30 秒调至 60–120 秒。
- 模型本身较重：补全场景建议切到轻量模型（如
gpt-4o-mini、deepseek-coder或本地 7B 模型），仅把大模型留给复杂对话。 - 网络抖动：开启本地模型做日常补全，可彻底消除网络延迟问题。
**6. 多模型配置混乱，想恢复初始状态
- 进入 OpenCode 设置 →「模型列表」，删除不再使用的模型条目。
- 点击设置页底部的「重置模型配置」或「恢复默认」，可清空所有自定义 API 设置，回到插件初始状态（不会删除 IDE 其他配置）。
- 若项目级设置导致冲突，直接删除工作区配置文件中的 OpenCode 相关字段，回退到全局默认。