为什么 GPT-5.6 Sol 在 OpenCode 中提示模型不可用？
GPT-5.6 Sol 已经出现在 OpenCode 的模型生态中，并不等于任何 OpenCode 项目、任何提供商账户都能立刻调用它。出现“模型不可用”时，最常见的原因不是模型名称写错这么简单，而是本地模型目录仍是旧缓存、配置中的提供商与模型不属于同一条调用链、当前提供商没有向该账户开放模型，或者旧会话仍保留着失效的模型选择。正确的处理顺序是先刷新并查看当前项目真正可见的模型，再使用列表返回的完整标识，最后检查提供商凭据与上游权限。
先理解“已支持”和“可调用”的区别
OpenCode 需要同时解决两个问题：它是否认识某个模型，以及当前配置能否向某个上游提供商发送请求。Models.dev 等模型目录提供模型名称、能力和变体等元数据；具体提供商则负责鉴权、套餐、区域、配额和实际 API 路由。目录中已经有 GPT-5.6 Sol，只能说明 OpenCode 可以识别相关模型信息，不能证明你当前连接的提供商已经开放该模型。
因此，“发布帖里说已经上线，但我的 OpenCode 仍提示不可用”并不矛盾。发布可能先完成目录合并，随后不同提供商再逐步开放；本地还可能保留合并前的缓存。即使两名用户运行相同版本的 OpenCode，他们连接的提供商、项目配置、账号权限和模型缓存也可能不同，最终看到的列表自然不同。
第一步：让 OpenCode 告诉你真实模型标识
不要根据展示名称猜测配置值，也不要只写 gpt-5.6-sol 就假定 OpenCode 能自动选择正确提供商。OpenCode 使用的选择值是完整的 provider/model 形式。同一个上游模型可能被多个提供商收录，而每个提供商的权限、价格和路由彼此独立。
先在出错的同一个项目目录中刷新模型缓存：
opencode models --refresh然后列出当前配置可见的模型：
opencode models如果只想检查某个提供商，可以把其标识作为参数：
opencode models openai
opencode models opencode这里的提供商名称只是示例，应以自己的列表和配置为准。检查输出中是否存在以 /gpt-5.6-sol 结尾的条目，并完整复制列表给出的值。假设输出确实包含 openai/gpt-5.6-sol，可以用一次非交互调用验证模型解析：
opencode run --model openai/gpt-5.6-sol "只回复：模型连接成功"若列表没有该模型，继续修改默认模型没有意义。此时问题发生在模型目录、提供商配置或上游可见性阶段。若列表存在而调用失败，则模型解析已经通过，排查重点应转向鉴权、账户权限、配额或上游接口响应。
第二步：清理过期缓存和旧会话状态
新模型刚加入目录时，本地缓存是最常见的时间差来源。opencode models --refresh 会更新模型缓存，因此应当在手工编辑配置前先运行它。刷新后重新执行 opencode models，不要只观察已经打开的模型选择界面。
另一个容易忽略的状态是会话选择。已有会话可以继续保留此前选中的模型；修改配置中的默认模型，只影响随后按默认规则选择模型的工作流，不一定重写当前会话。完成刷新和配置修改后，应关闭并重新启动 OpenCode，再新建会话或在模型选择器中重新选择列表里的条目。
可以把这一阶段归纳为三个动作：刷新模型目录、重启 OpenCode、在新会话中重新选择。若旧会话报错而新会话正常，问题就是会话保存的旧标识或旧变体，而不是模型服务本身。
第三步：核对提供商、凭据和项目范围
OpenCode 的模型可用性具有项目范围。模型必须处于启用状态，提供商必须在当前项目可用，凭据和配置也不会因为另一个项目曾经成功就自动保证当前项目成功。排查时必须在实际报错的项目目录运行模型列表和测试命令。
如果使用内置提供商，先通过 OpenCode 的连接流程确认登录或 API Key 对应的是预期账户。只保存凭据但没有正确配置自定义提供商，也可能让模型无法出现。反过来，配置了提供商但运行进程读不到对应环境变量，同样会导致提供商处于不可用状态。
检查配置时重点关注以下关系：
- 默认模型中的提供商前缀，是否与已经连接的提供商一致；
- 模型是否被当前提供商的禁用列表或黑名单隐藏；
- API Key 所属账户是否有 GPT-5.6 Sol 的访问权限和可用额度；
- 启动 OpenCode 的终端或桌面进程，是否实际继承了所需环境变量；
- 项目级配置是否覆盖了用户级配置中的提供商或默认模型。
可使用下面的命令查看 OpenCode 最终解析出的配置：
opencode debug config查看输出时不要公开密钥。目标是确认最终的模型标识、提供商配置和覆盖关系，而不是把完整配置粘贴到公共问题中。
第四步：不要把模型、提供商和订阅混为一谈
GPT-5.6 Sol 是模型名称，OpenAI、OpenCode Zen 或其他兼容服务是可能的调用渠道，ChatGPT 订阅、OpenCode 套餐和 API 计费账户则是不同的授权关系。某个产品界面能够选择 GPT-5.6 Sol，不代表另一个提供商下的 API Key 自动具备同样权限。
如果刷新后能看到多个带有 GPT-5.6 Sol 的条目，应选择自己确实拥有凭据和权限的那一个。不要因为模型后缀相同，就把一个提供商的模型标识与另一个提供商的凭据拼在一起。完整标识中的前缀决定请求将走哪条提供商链路。
上游提供商也可能分阶段开放新模型，或者按账户层级、组织设置和区域限制访问。遇到列表中存在模型但上游返回“model not found”“access denied”或类似响应时，应登录对应提供商的控制台核对账户，而不是反复删除 OpenCode 缓存。目录刷新只能修复本地元数据，不能替账户增加权限。
第五步：检查自定义兼容接口的模型映射
使用自建网关或 OpenAI 兼容接口时，OpenCode 不可能凭展示名推断网关内部使用的真实模型 ID。自定义提供商需要明确声明可用模型；如果配置键是本地别名，还要保证它映射到上游实际接受的模型标识。
下面展示的是结构思路，其中提供商名称和模型 ID 都必须替换成网关真实值。接口地址应按服务商文档填入对应的 baseURL，不要照抄示例值：
{
"model": "company/gpt-sol",
"provider": {
"company": {
"npm": "@ai-sdk/openai",
"options": {
"baseURL": "YOUR_GATEWAY_BASE_URL",
"apiKey": "{env:COMPANY_API_KEY}"
},
"models": {
"gpt-sol": {
"name": "GPT-5.6 Sol"
}
}
}
}
}这个示例不保证任何网关都使用 gpt-sol。有些服务接受官方模型 ID，有些服务使用自己的别名，还有些虽然宣传支持某模型，却没有在模型列表接口中返回它。应以该网关的模型列表和文档为准。若上游使用 Responses 接口，应使用与该协议相匹配的 OpenAI 提供商包；若使用 Chat Completions 兼容接口，则按 OpenCode 文档选择相应的兼容包。协议包选错时，问题可能表现为参数错误或接口路径错误，而不只是“模型不可用”。
第六步：区分模型不可用和变体不可用
GPT-5.6 Sol 支持多个推理强度，但 OpenCode 中的变体来自当前模型目录元数据。模型本身存在，不代表你随手写的每个变体名称都存在。未知变体会产生模型解析错误，症状很容易被误认为整个模型不可用。
先选择不带变体的模型完成最小验证。模型可以调用后，再从 OpenCode 当前展示的变体中选择，不要凭经验猜测名称。若模型能运行而某个推理档位失败，就应检查变体元数据和配置，而不是重新配置 API Key。
还要留意配置中的旧默认值。假设之前使用了一个临时变体，目录更新后该变体被更名或取消，即使基础模型仍然有效，旧会话也会继续解析失败。去掉变体、重启并重新选择，能快速验证这一点。
按错误发生阶段快速定位
模型列表里完全没有 GPT-5.6 Sol
优先运行缓存刷新，确认当前 OpenCode 版本和当前项目读取到的配置，再检查对应提供商是否已经收录并开放该模型。此时不要直接测试 API 请求，因为 OpenCode 尚未形成可用的模型选择。
列表有模型，但选择时提示不可用
完整复制 provider/model 标识，排除只写模型名、提供商前缀错误、模型被禁用以及旧会话残留。随后用一次 opencode run --model 做最小调用，使问题脱离复杂的代理和项目任务。
请求已经发出，但上游拒绝
根据上游状态处理：鉴权失败检查凭据，权限拒绝检查套餐或组织授权，找不到模型检查上游模型 ID，限流或额度不足则检查配额。此阶段反复刷新 Models.dev 缓存通常无效，因为 OpenCode 已经能够解析并发送该模型。
只有某个项目或某个会话失败
比较项目级配置覆盖，并在失败项目内查看最终解析配置。新建会话后再次测试；如果其他项目使用的是不同提供商或不同环境变量，不能把其成功结果当作当前项目配置正确的证据。
一套可重复的最小排错流程
可以按下面顺序执行，每一步都根据结果决定下一步，而不是一次性改动多个配置：
# 1. 更新本地模型目录
opencode models --refresh
# 2. 查看当前项目真实可见的完整模型标识
opencode models
# 3. 查看最终合并后的配置
opencode debug config
# 4. 用模型列表中复制的完整标识做最小测试
opencode run --model PROVIDER/gpt-5.6-sol "只回复：连接成功"若第二步没有目标模型，处理目录和提供商可见性；若第二步有而第四步在本地解析阶段失败，处理完整标识、禁用规则、会话和变体；若第四步收到上游 HTTP 错误，处理凭据、权限、配额、协议和真实模型 ID。一次只改变一个变量，并保留错误原文和提供商前缀，通常能很快确定故障层。
结论
GPT-5.6 Sol 在 OpenCode 中提示模型不可用，核心原因通常是“目录支持、项目配置、提供商开放和账户权限”四者没有同时成立。先用 opencode models --refresh 更新缓存，再从 opencode models 复制当前项目真实返回的完整标识；随后检查提供商连接、项目覆盖、上游权限和变体。只要把错误定位到模型发现、本地解析或上游请求这三个阶段，就不需要靠反复重装或盲目更换模型名来碰运气。
