---
title: "OpenCode 免费模型报错排查：区分 1.x 停供、计数卡住与客户端限制"
description: "OpenCode 切到 v2 后，免费模型报错在社区集中爆发。本文按背景经过、具体报错文案和四种常见原因分段拆解，说明如何确认 2.x 版本、避开旧会话与 429 限制，以及何时需要订阅 Go。"
url: https://codingpass.ai/zh/blog/opencode-free-model-errors-v2-upgrade
language: zh-CN
updated: 2026-11-20
---
# OpenCode 免费模型报错排查：1.x 停供与 v2 升级

10 月下旬以来，OpenCode 仓库里关于免费模型不能用的反馈集中涌进总帖 #59387。很多人第一反应是额度用完准备充 Go，但报错背后至少有四种互不相干的原因。

[CodingPass 团队](https://codingpass.ai/zh/about) 发布于 2026年11月20日 更新于 2026年11月20日 阅读约 6 分钟

十月下旬，OpenCode 推出 2.x 并陆续收紧旧版客户端的免费模型权限。从那之后，GitHub 仓库里关于免费模型不能用的反馈堆了一大片，维护者直接把 [anomalyco/opencode#59387](https://github.com/anomalyco/opencode/issues/59387) 设成总帖，后续同类问题全部标为重复并指过去。

不少用户的经历如出一辙：原本用得好好的，会话底下突然冒出一行红字，第一反应是当天免费额度用超了；按网上教程升完级、或者干脆守到提示的重置时间再试，结果重置日期又往后跳了一天。表面上看大家都在说“免费额度用完了”，实际上撞上的往往不是同一件事。

排查顺序：先看弹窗里的英文原话，再对号入座排除版本、旧会话、服务端计数和客户端四个原因。前两种和后一种问题，直接订阅 OpenCode Go 也无法解决。

## 常见的报错长什么样

弹窗外观几乎一样，真正区分病因的线索全在文案和按钮里。社区反馈里最常出现的是这几句：

```
1. This version of OpenCode Desktop no longer supports free models.
2. Free usage exceeded, subscribe to Go
3. You've used today's free messages. They reset at Oct 22, 2026, 8:00 p.m.
4. FreeUsageLimitError (HTTP 429)
```

如果看到第三句，且弹窗底部带着 `Upgrade to OpenCode Go` 和 `Switch model` 两个按钮，说明当前客户端已经过了版本校验，问题出在额度侧；如果是前两句或第四句，原因根本不在额度上。

## 可能的原因（按排查顺序）

### 原因一：客户端还在 1.x，v1 已停供免费模型

看到 `no longer supports free models` 或 `Free usage exceeded, subscribe to Go`，基本可以确定是版本还停在 1.x。官方在 10 月 27 日的 issue 回复中明确表示，v1 已不再支持免费模型。

很多人卡在这里，是因为误以为自己“已经升到最新版”。这里有两个容易踩中的坑：第一，v1 桌面端内置的更新器只会把人留在 1.x（`#59482` 已确认应用内检查更新无法跨到 v2）；第二，OpenCode 在 npm 上有两个包，老包 `opencode-ai` 的 `latest` 停在 `1.19.5`，v2 的正式包名已经换成了 `@opencode/cli`（`latest` 为 `2.2.2` 及以上），继续敲 `npm i -g opencode-ai` 永远停在 1.x。

桌面端和命令行是两套独立程序，检查版本时需要分别核对，以下三处对应使用的入口看到 `2.x` 才算过关：终端运行 `opencode --version`、桌面端打开 `Settings → About`、Windows 安装目录查看 `.exe` 文件版本。确认升级可按平台选一种方式手动重装：

| 方式 | 适用平台 | 命令或做法 |
| --- | --- | --- |
| curl | macOS / Linux | `curl -fsSL https://opencode.ai/v2/install \| bash` |
| npm | 全平台 | `npm install -g @opencode/cli` |
| Homebrew | macOS | `brew install anomalyco/tap/opencode-v2` |
| 独立二进制 | Windows | 下载官方 x64 zip 包，解压后将目录加入系统 `PATH` |

官方明确说明 Windows 的包管理器不在支持范围内，Windows 用户建议直接走 npm 或独立二进制。装完之后，如果在 `/models` 里看不到任何免费模型，先运行 `/connect` 登录 OpenCode Console 账号——未登录时内置的 `opencode` provider 不会出现。

### 原因二：已经升到 v2，但还在用 v1 建的旧会话

升完 v2 之后，不少人第一时间打开之前写了一半的会话继续发消息，结果照样弹出 `no longer supports free models`，于是怀疑自己装错了包。

这是 `#60352` 记录的已知问题：哪怕 CLI 和桌面端都已升到 `2.2.2`、本地数据库迁移也完全正常，服务端依然会把 **v1 时代创建的历史会话** 当成过期客户端直接拒掉。同一个账号、同一个免费模型，只要**新建一个会话**就能正常跑通。升完 v2 的第一步应当是开新会话测试，而不是拿旧会话当升级失败的证据。

### 原因三：当天额度用完，或者服务端计数卡住

看到 `You've used today's free messages. They reset at <时间> · <日期>` 时，需要看一眼后面那个重置时间怎么变。如果时间固定在每天同一时刻（例如每天晚上八点），说明当天免费额度确实用满了，等到点重置即可。

如果倒计时归零后再打开，重置时间却一天天往后顺延（例如从 `Oct 22` 跳成 `Oct 23`），就属于服务端计数卡住。按 `#60328` 的官方回复，额度和重置时间由托管的 Console 服务端按“账号 + 网络”设定，客户端本地改不了。重装软件、删配置目录或清数据库不仅多半无效，还会把本地会话历史全部清掉，不建议尝试。社区实测有效的两个临时办法是：在 OpenCode 里登出 Console 账号后重新登录（部分人需要重复几次），或者切换网络出口（比如改用手机热点）。

### 原因四：在 OpenCode 之外的客户端里调用

如果报错是 `FreeUsageLimitError` 或直接返回 `HTTP 429`，且不是在 OpenCode 客户端里触发的，这和版本号、网络环境都没有关系。OpenCode 官方文档明确写了 `Free-tier chat models require OpenCode`——免费模型只允许在 OpenCode 客户端内使用，把它的 Key 接到其他编辑器或自己写脚本直连 API，服务端会一律返回 429 拒绝请求。换回 OpenCode 客户端或改用付费模型即可解决。

## 两个容易误判的边缘情况

排查时还有两类情况容易让人走弯路：

- **日志里的低价模型 402**：翻看本地日志时，有时会发现 OpenCode 在后台用 `GPT-6 Luna` 这类低价模型发请求生成会话标题，并被 402 拒掉。按 Console 官方文档设计，OpenCode 会用 Haiku、Nano、Flash 等低成本模型自动生成会话标题，走的是另一套通道，与免费聊天模型的额度无关，也不是在偷偷扣费。
- **老旧 CPU 直接崩溃**：十多年前的老 CPU 如果只支持到 SSE4.1、缺少 SSE4.2 和 POPCNT 指令集，跑 v2 会直接报 `Illegal instruction` 退出，而 v1 又已经停供免费模型。这是硬件指令集限制，无法通过配置解决。

如果按上述四步走完依然报错，可以去 `#59387` 下反馈，并一次性写清楚**版本号、操作系统、完整报错文案**三项信息。

## 什么时候才需要充 OpenCode Go

OpenCode Go 页面写着一句话：`If you reach the usage limit, you can continue using the free models.` 即使 Go 的付费额度用完了，免费模型依然可用——两者分开计算，充 Go 买的是额外额度，不是“解锁免费模型”。

卡在 1.x 版本、v1 旧会话或第三方客户端 429 时，充多少钱都解决不了报错。只有确认自己已经在用 v2 新会话、重置时间固定不动，且一周里有好几天在下午就把当天免费额度用到底时，订阅 Go 才算划算（Go `$10/月`、Go Plus `$40/月`、Go Teams `$20/人/月`，官方未公布每日免费消息的具体条数）。

**补充信息**：当前标注 `limited time` 的免费模型池包含 Big Pickle、GLM-5.3-Flash Free、DeepSeek V4.1 Flash Free、Beam Free、Flint 40B Free、MiMo-V2.6-Flash Free、Nemotron 3 Ultra Free、Nemotron 3.5 Lightning Free、Nemotron 3.5 Super VL Free 与 Jev 1.13 Free；其中 **Beam Free 在中国（含港澳）不可用**。如果想彻底隐藏免费模型，设置环境变量 `OPENCODE_DISABLE_FREE_MODELS=1` 即可。

作者 CodingPass 团队

CodingPass 由我们运营。每篇指南发布前，都会在对应工具的最新稳定版上实测一遍。发现内容过时了？写信到 [support@codingpass.ai](mailto:support@codingpass.ai)。

## 相关阅读。

指南

### [OpenCode 接入指南](https://codingpass.ai/zh/tools/opencode)

opencode.jsonc 的 provider 配置、各档位模型 ID 与常见报错排查。

规则

### [额度和上限怎么算](https://codingpass.ai/zh/usage-limits)

每个套餐、每个模型的额度和上限，以及 429 响应。

模型

### [全部模型](https://codingpass.ai/zh/models)

每个模型的 ID、所需档位和月度额度。
