平时做技术实践时，很多问题不是概念不会，而是细节没串起来。拿“OpenCode 2026上手指南：安装、订阅、免费模型和自定义模型接入……”来说，它看着像小点，放到项目里常会牵出环境、配置、兼容性和维护成本。下面按实际采用顺序，把思路、关键写法和容易踩坑的地方讲清楚，便于大家直接对照操作。

理解这一步时，OpenCode 是 OpenCode 团队开源的终端 AI 编程智能体，GitHub 仓库 anomalyco/opencode 截至 2026 年 11 月已有约 22.5 万 Star，最新版本 v1.19.5 发布于 10 月 28 日。它不绑定任何一家模型厂商：能够用官方 Console 按量付费、订阅 10 美元/月起的 OpenCode Go、直接白嫖十余款限时免费模型，也能登录 ChatGPT 或 GitHub Copilot 账号复用已有订阅，或者借助 OpenAI 兼容协议接入自己的模型服务。本文按"装上 → 连上 → 选模型 → 接自定义模型"的顺序走一遍，重点提醒两个容易踩的坑：网上大量教程仍是旧版命令和旧版设置字段，照抄会报错；免费模型各有数据保留条款，不适合直接喂公司代码。

先说结论：OpenCode 用模型的四条路

落到代码里，OpenCode 本身免费开源，花钱的只有模型。按成本从低到高，接入方式能够分成四类：

下面逐个展开。

第一步：安装（注意新旧两套命令）

结合项目来看，OpenCode 现在的官方安装命令已经换成 v2 通道，npm 包名也从 opencode-ai 改成了 @opencode/cli。 从实现思路看，2026 年 10 月以前的教程大多还写着 sst/opencode、opencode-ai，装出来是旧版本。

当前官方文档给出的安装方式：

# 一键脚本（安装到 $HOME/.opencode/bin）
curl -fsSL https://opencode.ai/v2/install | bash
# Homebrew（macOS / Linux，官方推荐，更新最及时）
brew install anomalyco/tap/opencode-v2
# npm
npm install -g @opencode/cli
# mise（需 2026.10.9 及以上，旧版 mise 装的是 OpenCode 1）
mise use -g opencode

几个细节：

• Windows 用户：官方文档写明不兼容 Windows 包管理器，需按官方文档下载 opencode-windows-x64.zip 独立二进制（ARM 设备选 opencode-windows-arm64.zip），或到 opencode.ai/download 装桌面版 opencode-desktop-win-x64.exe。
• 桌面版：macOS 可用 brew install --cask opencode-desktop，目前仍是 Beta。
• 老版本残留：README 提示安装前先删掉 0.1.x 之前的旧版本。

装好后在项目目录执行 opencode 进入终端界面。按 Tab 能够在两个内置智能体之间切换：build 拥有完整读写权限，plan 默认只读、执行命令前会先询问，适合先让它读懂陌生代码库再动手。

第二步：零成本起步，用好免费模型

实际处理时，OpenCode 官方 Console 目前提供 13 款限时免费模型，装好即可在 /models 里选用，无需充值。 理解这一步时，截至 2026 年 11 月文档列出的免费模型包括 Big Pickle、GLM-5.3-Flash Free、DeepSeek V4.1 Flash Free、LongCat 2.5 Free、MiMo-V2.6-Flash Free、Nemotron 3 系列等。

但免费模型的数据条款差别很大，官方文档逐一做了标注：

• 零保留、不用来训练：GLM-5.3-Flash Free、DeepSeek V4.1 Flash Free；LongCat 2.5 Free 同样零保留，但每天限 100 次请求。
• 数据可能用来改进模型：Big Pickle、Iceman Free（两款"隐身"模型）、MiMo-V2.6-Flash Free，Flint 40B Free 保留 30 天。
• 数据会被记录：Nemotron 三款按 NVIDIA 试用条款，官方明确提醒不要提交个人或机密数据。

实操建议：写公司代码时优先选前两款零保留模型；只想看界面效果、跑个人 demo，再试其他免费模型。另外两条限制要知道：免费模型全部"限时"、没有公布截止日期；免费聊天模型只能在 OpenCode 客户端内采用，其他工具调用不到。如果团队不希望成员误选，能够设置环境变量 OPENCODE_DISABLE_FREE_MODELS=1 把它们隐藏。

第三步：订阅 OpenCode Go，还是按量付费？

结合项目来看，OpenCode Go 是官方的月费订阅，基础档 10 美元/月，覆盖 32 款以开源编程模型为主的模型。 结合项目来看，另有 Go Plus（40 美元/月，各模型额度更高）和 Go Teams（20 美元每人每月）。

它的额度设计和常用的"总 token 包"不一样，按每个模型单独给出月度美元额度，再分三层限流：

• 5 小时窗口内最多用掉该模型月额度的 20%；
• 一周内最多 50%；
• 一个月 100%。

从实现思路看，以 Go 基础档为例，DeepSeek V4.1 Flash 每月额度相当于 100 美元、GLM-5.3-Flash 为 60 美元、Kimi K3 为 15 美元。用超了不会断：能够切回免费模型，或在 Console 有余额时打开 Extra Usage 转按量计费。

订阅后的接入三步走：

1. 结合项目来看，登录 opencode.ai/console，订阅同时复制 API Key；
2. 落到代码里，在 OpenCode 里输入 /connect，选 OpenCode Go，粘贴 Key；
3. 输入 /models 选模型，设置文件里写作 opencode-go/<模型ID>。

怎么选：每天固定写几个小时代码、主力用开源模型，Go 的固定月费更省心；偶尔用、或者必须用某个特定商业模型，就走 Console 按量付费。Console 本身不加价，但每次充值另收"4.6% + 0.31 美元"的手续费。

第四步：接入自定义模型（v2 设置字段已改）

从实现思路看，OpenCode 兼容任何 OpenAI 兼容接口，在 opencode.jsonc 里新增一个 provider 即可。 设置文件能够放在全局 ~/.config/opencode/opencode.jsonc，也能够放在项目根目录或 .opencode/ 目录下，项目级会覆盖全局。

这里是最容易出错的地方：新版字段名已经变了，老教程里的 provider、npm、options 分别对应现在的 providers、package、settings。

落到代码里，以国内团队常用的企业订阅为例。七牛云 Token Plan 提供 OpenAI 兼容接口，地址为 （链接已移除），订阅内是 DeepSeek、Kimi、GLM、MiniMax 4 家厂商共 16 个模型，借助一个订阅专用 API Key 调用。按 OpenCode 当前文档的格式，设置如下所示：

{
  "$schema": "https://opencode.ai/config.json",
  "providers": {
    "qiniu": {
      "name": "Qiniu",
      "env": ["QINIU_API_KEY"],
      "package": "@opencode/ai/providers/openai-compatible",
      "settings": {
        "baseURL": "https://api.qnaigc.com/v1",
      },
      "models": {
        "z-ai/glm-5.3": { "name": "GLM 5.3" },
        "deepseek/deepseek-v4.1-flash": { "name": "DeepSeek V4.1 Flash" },
        "moonshotai/kimi-k3": { "name": "Kimi K3" },
      },
    },
  },
  "model": "qiniu/z-ai/glm-5.3",
}

然后在终端设置 Key 再启动：

export QINIU_API_KEY="<你的订阅专用 API Key>"
opencode

进入后用 /models 就能看到 qiniu 下的三个模型。模型 ID 以控制台模型广场显示为准。

实际处理时，这类企业订阅的计费规则和 OpenCode Go 不同，选型时值得对照看：Token Plan 月付 2,999 元起，按积分扣减、每周刷新一次额度；每天 08:00–18:00 以外的闲时调用按 0.3 倍折算积分，官网标注叠加包年折扣后最低 1.2 折；超出额度的请求直接被拒绝，不会产生额外扣费，月度成本是封顶的。前提是它面向企业与团队，个人用户用 Go 或免费模型更合适。

常用问题

OpenCode 能用本地模型吗？
从实现思路看，能够。本机运行 Ollama 时，OpenCode 会自动探测 （链接已移除） 同时列出模型，无需 /connect。只有具备 completion 能力的模型才会显示；连接远程 Ollama 时需在 settings.baseURL 里写完整地址并带上 /v1。

为什么照着教程设置后 provider 不生效？
理解这一步时，最常用的原因是用了旧版字段。v2 文档里顶层键是 providers（复数），包名字段是 package，接口地址写在 settings.baseURL 里。另外检查 env 里声明的环境变量是否已经 export。

ChatGPT Plus 订阅接进 OpenCode 有什么限制？
在 /connect 里选 OpenAI → Sign in with ChatGPT 后，用量计入订阅计划、界面不显示费用。OpenCode 默认会给这类模型的上下文窗口设上限，需时可在设置中关闭。

小结

理解这一步时，OpenCode 的核心价值是"客户端开源、模型自由选"：个人开发者用零保留的免费模型即可起步，高频用户用 10 美元/月的 Go 订阅控制成本，团队能够接入自己采购的 OpenAI 兼容服务统一管理。本文信息依据 OpenCode 官方文档（opencode.ai/docs）与 GitHub 仓库 anomalyco/opencode，截至 2026 年 11 月 10 日；免费模型名单和订阅额度变化较快，以官方页面为准。

从实现思路看，总的来说，OpenCode适合结合实际项目边做边理解。先抓住核心思路，再逐步补上细节和边界处理，最后效果会更稳定，也更容易复用。