OpenCode模型不显示？应该这样配置

很多开发者在使用 OpenCode 时，都会遇到类似问题：配置文件看起来没有明显错误，API Key 也能正常使用，但进入 OpenCode 后模型不显示，或者一调用就出现 404、认证失败、Provider 不可用、模型名不存在等报错。出现这些问题，很多人第一反应是怀疑密钥、模型名或中转地址有问题，但从实际排查经验看，更多时候是没有理解 OpenCode 的模型加载机制。

根据 OpenCode 官方文档，OpenCode 通过 AI SDK 和 Models.dev 支持 75 个以上的大模型 Provider，并且也支持本地模型；模型的选择并不是单独依赖一个模型名称，而是通过 provider_id/model_id 的方式完成绑定。也就是说，OpenCode 中真正生效的不是“某个模型名”，而是 Provider、SDK 适配层、baseURL、apiKey 与 models 映射关系共同组成的调用链路。

一、先理解 OpenCode 的核心逻辑

想要配好 OpenCode 自定义模型，首先要纠正一个认知：OpenCode 不是直接识别模型本身，而是通过 Provider 去挂载模型。可以把它理解成：

模型可用 = Provider ID + SDK 协议 + baseURL + apiKey + models.id

其中任何一项配置错误，都会导致模型无法显示或调用失败。比如 GPT 类接口如果走 OpenAI 兼容协议，通常需要使用 @ai-sdk/openai-compatible；Claude 通常需要 Anthropic Provider；Gemini 则需要 Google Provider。Vercel AI SDK 官方文档也明确说明，AI SDK 的核心价值就是抽象不同模型服务商之间的差异，让开发者通过统一接口调用不同 Provider。

这也是很多 404 问题的来源：模型名本身可能没错，但 SDK 与接口协议不匹配，或者 baseURL 缺少必要路径后缀，OpenCode 就无法把请求发送到正确接口。

二、确认配置文件位置

OpenCode 的全局配置文件路径是：

~/.config/opencode/opencode.json

官方文档也说明，全局配置适合存放用户级别的 Provider、模型和权限配置；项目根目录下的 opencode.json 则可以覆盖全局配置，用于项目级定制。

如果你希望使用自定义配置路径，可以通过环境变量指定：

export OPENCODE_CONFIG_DIR=~/.opencode
export OPENCODE_CONFIG=~/.opencode/opencode.json

需要注意的是，OPENCODE_CONFIG 指向的是具体配置文件，而 OPENCODE_CONFIG_DIR 指向的是配置目录。官方文档中也提到，自定义配置文件可通过 OPENCODE_CONFIG 指定，自定义目录可通过 OPENCODE_CONFIG_DIR 指定。

三、完整可用的多模型 Provider 配置

下面是一份可直接参考的 OpenCode 多模型配置示例，兼容 Token173 中转服务，并分别挂载 GPT、Claude 与 Gemini 三类模型。配置重点不是简单堆模型名，而是给不同协议使用正确的 SDK Provider。

{
  "$schema": "https://opencode.ai/config.json",
  "theme": "opencode",
  "autoupdate": true,
  "tools": {
    "write": true,
    "bash": true,
    "read": true,
    "edit": true,
    "glob": true,
    "grep": true
  },
  "permission": {
    "webfetch": "allow",
    "bash": "ask",
    "edit": "ask",
    "skill": "allow"
  },
  "provider": {
    "token173-openai": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Token173 OpenAI",
      "options": {
        "baseURL": "https://token173.com/v1",
        "apiKey": "{env:TOKEN173_API_KEY}"
      },
      "models": {
        "gpt-5": { "id": "gpt-5", "name": "GPT-5" },
        "gpt-5.1": { "id": "gpt-5.1", "name": "GPT-5.1" }
      }
    },
    "token173-anthropic": {
      "npm": "@ai-sdk/anthropic",
      "name": "Token173 Claude",
      "options": {
        "baseURL": "https://token173.com/anthropic/v1",
        "apiKey": "{env:TOKEN173_API_KEY}"
      },
      "models": {
        "claude-sonnet-4.5": {
          "id": "claude-sonnet-4.5",
          "name": "Claude Sonnet 4.5"
        }
      }
    },
    "token173-gemini": {
      "npm": "@ai-sdk/google",
      "name": "Token173 Gemini",
      "options": {
        "baseURL": "https://token173.com/gemini/v1beta",
        "apiKey": "{env:TOKEN173_API_KEY}"
      },
      "models": {
        "gemini-3.5-flash": {
          "id": "gemini-3.5-flash",
          "name": "Gemini 3.5 Flash"
        }
      }
    }
  }
}

这段配置的核心是把不同协议拆成不同 Provider，而不是把所有模型都塞进同一个 Provider。OpenAI 兼容接口使用 @ai-sdk/openai-compatible，它适合接入实现 OpenAI API 规范的模型服务，官方文档中也说明该包用于调用实现 OpenAI API 的兼容 Provider，并且需要配置 baseURL 与 apiKey。

Claude 使用 @ai-sdk/anthropic 更稳妥，因为 Anthropic Provider 对应的是 Anthropic Messages API，官方文档也列出了 baseURL、apiKey、headers 等可配置项。 Gemini 则使用 @ai-sdk/google，Google Provider 官方默认 API 前缀为 https://generativelanguage.googleapis.com/v1beta，因此中转服务如果兼容 Gemini，也要确保路径后缀与实际接口保持一致。

四、三个最容易出错的字段

第一是 npm 字段。它决定 OpenCode 最终使用哪个 AI SDK Provider 去发起请求。如果 GPT 使用 OpenAI 兼容协议，可以配置 @ai-sdk/openai-compatible；如果 Claude 或 Gemini 强行也走同一个 OpenAI 兼容层，部分基础文本调用可能能跑，但工具调用、结构化输出、多模态能力和错误格式都可能出现兼容问题。更稳妥的方式是按协议拆分 Provider。

第二是 options.baseURL。这是 404 问题最高发的位置。GPT 接口通常要带 /v1，Claude 中转接口在本文示例中为 /anthropic/v1，Gemini 示例为 /gemini/v1beta。少一个路径后缀，OpenCode 仍然会正常发请求，但请求会落到错误路由，自然就会返回 404。

第三是 models 下的 id 和 name。id 是真实请求时传给后端的模型标识，必须与中转服务实际支持的模型名完全一致；name 只是 OpenCode 前端展示名称，可以写得更友好。OpenCode 官方文档也说明，自定义 Provider 场景下，provider_id 来自配置中 provider 的 key，model_id 来自 provider.models 的 key。

五、密钥不要写死，统一用环境变量

生产环境中不建议把 API Key 明文写进 opencode.json。正确做法是先在终端写入环境变量：

export TOKEN173_API_KEY="your_api_key_here"

然后在配置文件中使用：

"apiKey": "{env:TOKEN173_API_KEY}"

OpenCode 官方支持通过 {env:VARIABLE_NAME} 在配置中引用环境变量，如果变量不存在，会被替换为空字符串。这样做可以避免密钥进入 Git 仓库，也方便在本地、测试环境和服务器环境之间切换。

如果团队同时维护官方 API、中转服务和备用模型入口，可以把 koalaapi 作为额外的 API 聚合接入备选项，用于验证不同模型在 OpenCode Provider 配置下的兼容性、对比延迟与成本，并在主接口不可用时手动切换到备用 baseURL；它不改变 OpenCode 的 Provider 加载机制，也不应被描述成自动调度或自动选择最优模型的组件，真正决定调用是否成功的仍然是 SDK、路径、密钥和模型 ID 的匹配关系。

六、常见故障排查

如果模型列表不显示，先检查 JSON 是否有效：

jq . ~/.config/opencode/opencode.json

如果 JSON 语法正常，再检查 Provider 名是否重复、models 是否为空、当前配置文件路径是否正确。还可以在 OpenCode 中执行：

/models

确认模型是否已经被加载。

如果请求不通，优先检查环境变量：

echo $TOKEN173_API_KEY

如果输出为空，说明当前 Shell 没有加载密钥。此时即使配置文件写了 {env:TOKEN173_API_KEY}，实际传入的也会是空值。

如果 GPT 可用但 Claude 或 Gemini 固定 404，通常不是密钥问题，而是 baseURL 路径或 SDK Provider 不匹配。Claude 要确认是否走 Anthropic 协议，Gemini 要确认是否走 Google Provider，并检查 /anthropic/v1、/gemini/v1beta 等路径是否与中转服务文档一致。

七、总结

OpenCode 的优势不在于内置多少模型，而在于它提供了一套可扩展的 Provider 架构。只要理解 Provider + SDK + baseURL + apiKey + model id 这条链路，就能把 GPT、Claude、Gemini 以及其他中转或私有化模型稳定接入同一个开发入口。

对开发者来说，最重要的不是记住某个模型名，而是建立正确的排查顺序：先看配置文件路径，再看 JSON 语法，然后看 Provider SDK，接着检查 baseURL 后缀、环境变量和真实模型 ID。只要这几个环节对应准确，模型不显示、404、请求失败等问题基本都能快速定位并解决。