QuickRouter API 大模型API聚合中转平台QuickRouter API
opencode 报错修复

opencode model not found 报错修复

opencode 的 model not found 重点看当前项目配置是否覆盖了全局模型名。

获取 QuickRouter API Key查看 API 文档

先看错误信息

model not found

这类报错先不要反复重装工具。按顺序核对 API Key、Base URL、模型名和 provider 类型，通常可以直接定位。

常见表现

  • 认证成功但模型调用失败
  • 只在某个项目目录失败
  • 错误包含 model not found

这个报错是什么意思

model not found 表示 opencode 已经进入模型调用或配置读取阶段，但请求没有被正确完成。这个错误通常不要先归因到工具安装问题，优先按 API Key、Base URL、模型名、provider 类型、账户余额和当前网络顺序排查。对中文开发者来说，最容易出错的是把不同工具的接口地址混用：Claude Code 通常使用 Anthropic 兼容根地址，Cursor、opencode、Codex、Cherry Studio、Trae 这类 OpenAI 兼容场景通常使用 /v1 端点。

先判断是哪一类问题

判断 01

先确认错误是否稳定复现。如果每次启动 opencode 都立刻失败，优先检查 API Key 和配置文件；如果短任务正常、长任务失败，优先检查额度、限流和上下文长度。

判断 02

再看后台是否有请求记录。QuickRouter 后台没有记录时，问题通常还停留在本地配置、Base URL、网络或 provider 选择；后台有记录但返回失败时，再看模型名、余额和上游状态。

判断 03

最后确认当前页面对应的工具类型。opencode 的正确端点是 https://api.quickrouter.ai/v1，模型建议先用 claude-sonnet-4-6 做连通性测试，等跑通后再切换其他模型。

3 分钟修复

01

项目和全局配置都改为 claude-sonnet-4-6

02

确认 baseURL 是 /v1

03

删除旧模型别名

04

重新启动 opencode

详细修复步骤

Step 01

重新复制 API Key

到 QuickRouter 后台重新复制一个可用令牌，只保留 sk- 开头的 Key。不要把 Bearer、引号、空格或换行一起复制进 opencode。复制后先保存，再重新打开会话测试，避免旧配置缓存继续生效。

Step 02

核对 Base URL

opencode 当前应使用 https://api.quickrouter.ai/v1。如果把官网地址、文档地址、/chat/completions 完整路径，或者另一个工具的端点填进去，就会出现 401、404、provider error、model not found、empty content 等看起来不一样但根因相同的错误。

Step 03

固定一个模型名测试

先把模型名统一改成 claude-sonnet-4-6。不要同时测试多个模型，也不要用旧教程里的过期 Claude 名称。模型名跑通后，再根据价格、速度和上下文需求切换到其他模型。

Step 04

清理覆盖配置

很多 AI 编程工具同时支持全局配置、项目配置和环境变量。若全局配置正确但某个项目仍失败，通常是项目目录里的 settings、config、auth 或 provider 文件覆盖了新配置。先用最小配置跑通，再逐步恢复个性化设置。

Step 05

降低并发后重试

Agent、Composer、Builder 或自动修复模式会连续发起多次请求。遇到限流、overloaded、request failed 时，先停止当前任务，拆成更小的 prompt，等待 30 到 120 秒后重试，避免工具自动重试把问题放大。

正确配置

{
  "model": "claude-sonnet-4-6",
  "baseURL": "https://api.quickrouter.ai/v1"
}

常见原因

  • 项目 opencode.json 写了旧模型
  • 模型名拼写错误
  • provider 和模型不匹配
  • baseURL 指向错误服务

怎么确认已经修好

  1. 保存配置后完全关闭并重新打开 opencode，不要只刷新当前聊天窗口。
  2. 发送一个极短测试问题，例如“只回复 OK”，确认不是长上下文导致失败。
  3. 打开 QuickRouter 后台请求记录，确认请求是否到达、返回码是什么、使用了哪个模型。
  4. 如果短问题成功，再回到原任务；如果原任务仍失败，优先拆分上下文或切换到 claude-sonnet-4-6 重试。

避免下次再报错

  • 团队内统一一份 Base URL 和模型名，不要让每个人从不同教程复制配置。
  • 给生产任务和个人调试任务分开 API Key，方便定位是谁触发了限流或余额消耗。
  • 工具升级后先保留旧配置备份，再用一个短 prompt 验证连通性。
  • 把正确配置写进团队文档，尤其标明 Claude Code 和 OpenAI 兼容工具的 Base URL 差异。

为什么建议用 QuickRouter 排查

QuickRouter 用统一后台管理多种大模型 Key、余额和调用记录，排查报错时能直接看到请求是否到达。

对 opencode 这类工具，QuickRouter 可以减少国内网络访问、支付和上游账号限制带来的不确定性。

统一 OpenAI 兼容接口后，Cursor、opencode、Codex、Cherry Studio、Trae 等工具可以复用同一套接入方式，迁移成本更低。

当官方账号限流、余额不足或不可访问时，可以更快切换模型和端点，减少开发中断时间。

注册并获取 API Key

相关报错

Claude Code API Key 配置教程Cursor 配置 Claude API 教程OpenAI 兼容接口接入教程全部报错修复

FAQ

opencode 出现 model not found 一定是接口不可用吗？

不一定。多数情况是 Base URL、API Key、模型名或接口协议填错，先用本文配置核对一遍，再判断是否是服务端异常。

为什么换成 QuickRouter 后还要改模型名？

不同工具会把模型名原样传给上游接口。模型名不存在或拼写不一致时，即使 API Key 正确也会返回 model not found、provider error 或调用失败。

Claude Code 和 OpenAI 兼容工具的 Base URL 为什么不一样？

Claude Code 走 Anthropic 兼容路径，通常使用 https://api.quickrouter.ai；Cursor、opencode、Cherry Studio、Trae、Codex 等 OpenAI 兼容场景通常使用 https://api.quickrouter.ai/v1。

后台没有请求记录时应该查哪里？

后台没有请求记录说明请求大概率没有到达 QuickRouter。优先检查 Base URL、网络代理、provider 类型、环境变量是否生效，以及工具是否仍在读取旧配置。

后台有请求记录但 opencode 仍然失败怎么办？

这种情况说明本地连通性基本正常，继续看返回码、模型名、余额、上下文长度和限流状态。先用短 prompt 和推荐模型验证，再回到原任务。

可以直接复制别的工具配置吗？

不建议。Claude Code、Cursor、opencode、Codex、Cherry Studio、Trae 的配置字段和端点规则不完全相同，尤其是 /v1 是否需要保留，必须按当前工具核对。