AB
AB
AiBoss站

全部分类

教程

OpenCode

教程

OpenCode 多模型接入与默认模型固定指南

OpenCode 支持接入大量 LLM 提供商，但安装后默认会连到哪个模型并不直观。本文从安装讲起，逐步说明如何用 providers list、models、debug config 查清当前可用的提供商与模型，如何用 -m 参数或配置文件固定模型，如何接入 Ollama 等 OpenAI 兼容端点，以及环境变量名不一致等常见问题的排查思路。

OpenCode 是一个在终端里运行的 AI 编程代理，采用 MIT 许可证，支持接入大量 LLM 提供商。可选范围广是它的优势，但也带来一个实际问题：装完之后直接执行一次非交互运行，你未必知道它究竟连到了哪个提供商的哪个模型。选择越多，越需要先有一套确认「我现在连到哪里」的手段。这篇教程面向已经用过其他命令行编程代理、希望在 OpenAI、Google、Anthropic 以及本地模型之间自由切换的开发者，重点讲清楚三件事：当前能连上哪些提供商、当前能选哪些模型、以及如何把模型固定下来而不是交给自动选择。站内可参考 OpenCode 工具页。

准备工作

开始之前需要确认几项前置条件。

  • 运行环境：一个可以正常访问 npm 仓库的终端环境。Node.js 与 npm 的版本以官网当前要求为准，本文示例环境为 Node.js v22 与 npm 10 系列。
  • API 密钥：至少准备一个提供商的密钥。密钥可以来自环境变量，也可以通过 OpenCode 自身的登录流程写入本地凭据文件。
  • 网络条件：如果所在网络对 GitHub API 有限制，安装脚本方式可能失败，需要改用 npm 安装（后文会说明）。
  • 本地模型（可选）：如果打算接本地推理服务，需要先让该服务在某个端口上以 OpenAI 兼容接口的形式跑起来。

需要提醒的是，OpenCode 会读取当前 shell 中已经存在的环境变量。也就是说，你为别的工具设置的密钥，可能被 OpenCode 自动识别并用于调用 API。这一点在后面的排查环节会反复出现，建议在第一次运行前就先做一次检查。

操作步骤

第一步：安装 OpenCode

常见的安装方式有三种，按环境选择即可。

# 安装脚本
curl -fsSL https://opencode.ai/install | bash

# npm / bun
npm i -g opencode-ai@latest
bun install -g opencode-ai

# Homebrew（macOS / Linux）
brew install anomalyco/tap/opencode

安装完成后确认版本与可执行文件位置：

which opencode
opencode --version

如果安装脚本报出「Failed to fetch version information」之类的错误，通常是因为脚本需要向 GitHub API 查询最新版本号，而当前网络无法访问该接口。这种情况下改用 npm 安装即可绕过：

npm install -g opencode-ai

通过 opencode --help 可以看到可用的子命令，包括非交互执行一次的 run、列出模型的 models、处理凭据的 providers（别名 auth）、列出代理的 agent、查看内部状态的 debug，以及 serve、web、mcp、session、stats 等。模型通过 -m（即 --model）以 provider/model 形式传入，代理通过 --agent 切换。不带参数执行 opencode 会启动终端交互界面。

第二步：确认配置与凭据的存放位置

OpenCode 把配置和凭据分开存放，实际路径可以用一条命令查出来：

opencode debug paths

输出会列出 home、data、bin、log、repos、cache、config、state、tmp 等目录。其中配置目录下是 opencode.jsonc，扩展名说明它支持注释。刚安装完时，这个文件里通常只有一行 schema 声明：

{
  "$schema": "https://opencode.ai/config.json"
}

多个配置文件会被合并，而不是互相替换，后读取的优先级更高。想看合并之后的最终结果，用：

opencode debug config

凭据则存放在 data 目录下的 auth.json。通过交互界面里的 /connect 注册的密钥不会写进配置文件，因此把项目里的 opencode.json 提交到仓库时不会连带泄露密钥。

第三步：查看当前能连上的提供商

opencode providers list

这条命令的输出分成上下两部分，含义完全不同，是最容易读错的地方。

上半部分标为 Credentials，列出的是保存在 auth.json 里的凭据。刚装好时这里通常是 0 条。

下半部分标为 Environment，列出的是当前 shell 中确实存在值的环境变量，而不是「你可以设置哪些环境变量」的对照表。它的判断逻辑是：读取模型目录中每个提供商定义的环境变量名，逐个检查当前进程环境里是否有值，只把有值的那些打印出来。所以如果某个提供商的环境变量一个都没设置，它就不会出现在这个列表里。

由此带来一个直接后果：即使 auth.json 是空的，只要你的 shell 里存在别的工具留下的密钥，OpenCode 就会把它当作已检测到的提供商。例如为其他用途设置过的 OpenAI 或 Google 密钥，会被自动拾取。这意味着在第一次运行之前先看一眼这个列表，有助于判断接下来调用 API 时会用哪个账号计费。

第四步：列出实际可选的模型

opencode models

输出格式是每行一个 provider/model。想统计数量或看有哪些提供商，可以配合管道：

opencode models | wc -l
opencode models | cut -d '/' -f1 | sort -u

需要注意，这个列表并不是全部受支持提供商的目录，而是被筛过的结果——大致只包含「凭据已被检测到」的提供商，外加 OpenCode 自身提供的 opencode 提供商。因此它和宣传中「支持 75 个以上提供商」的口径并不一致，后者指的是模型目录里能读取到的提供商总数，两者计数方式不同。

只想看某一个提供商的模型时，直接过滤即可：

opencode models | grep '^openai/'

第五步：固定模型后执行

不指定模型直接运行时，OpenCode 会自行挑选一个默认模型。挑选逻辑大致是：如果存在最近使用过的模型就沿用，否则按内部优先级排序后取第一个。因此，接入的提供商组合一变，被选中的模型就可能跟着变。

临时指定一次，用 -m 传入 provider/model，模型 ID 从 opencode models 的输出里挑：

opencode run -m openai/<模型ID> "说明这个仓库的目录结构"

希望长期固定，就写进配置文件：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

其中 model 是默认使用的模型，small_model 用于会话标题生成这类轻量任务。改完之后用 opencode debug config 确认输出里出现了 model 字段，就说明配置已经生效。

第六步：接入目录之外的提供商或本地模型

对于模型目录里没有的提供商，或者本地运行的推理服务，需要在配置文件的 provider 字段里自行定义。以本地 Ollama 为例：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "llama2": {
          "name": "Llama 2"
        }
      }
    }
  }
}

只要目标端点提供 OpenAI 兼容接口，都可以用同一个 @ai-sdk/openai-compatible 适配器接入。密钥建议通过 {env:变量名} 的写法从环境变量注入，避免把密钥直接写进配置文件：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "myprovider": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "My Provider",
      "options": {
        "baseURL": "https://example.com/v1",
        "apiKey": "{env:API_KEY}"
      },
      "models": {
        "model-id": {
          "name": "Model Display Name"
        }
      }
    }
  }
}

而像 Anthropic、OpenAI 这类已经在目录中的提供商，不需要写定义，注册密钥即可使用。交互界面里用 /connect 注册，密钥会落到 auth.json；命令行侧也提供了 opencode providers login 与 opencode providers logout。

关于 Anthropic 有一点需要留意：用 Claude Pro/Max 订阅额度接入的插件在较新版本中已不再随包提供，相关说明指出这与 Anthropic 方面的政策有关。具体可用性与版本情况请以官网当前信息为准。

第七步：查看代理与语言服务器状态

除了提供商，代理是另一个切换维度：

opencode agent list

默认包含两个主代理：build 拥有以通配符允许规则开头的权限集合，plan 则是偏只读的权限集合。运行时可以用 --agent plan 指定。

语言服务器相关的入口在 debug lsp 下，包含三个子命令：diagnostics <file> 取文件诊断、symbols <query> 搜索工作区符号、document-symbols <uri> 取文档符号。例如对一个文件取诊断：

opencode debug lsp diagnostics test.js

如果返回空结果但命令本身没有报错，通常说明对应语言的语言服务器没有安装或不可用。想让诊断真正生效，先确认目标语言的语言服务器处于可用状态，能省下不少排查时间。

一个完整示例

下面把上面的步骤串成一条最短路径，目标是在一台新机器上把模型固定到指定提供商。

1. 安装并确认版本

npm install -g opencode-ai
opencode --version

2. 查看凭据与配置路径

opencode debug paths

3. 检查当前 shell 里有哪些密钥会被自动拾取

opencode providers list

重点看 Environment 部分。如果这里出现了你并不打算给 OpenCode 使用的密钥，先决定是保留还是清理，再继续下一步。

4. 查看实际可选的模型

opencode models | cut -d '/' -f1 | sort -u
opencode models | grep '^openai/'

5. 用指定模型跑一次非交互任务

opencode run -m openai/<模型ID> "列出这个项目的顶层目录并说明各自用途"

6. 确认无误后写入配置固定下来

{
  "$schema": "https://opencode.ai/config.json",
  "model": "openai/<模型ID>",
  "small_model": "openai/<轻量模型ID>"
}

7. 验证合并后的配置

opencode debug config

输出中出现 model 字段即表示生效。此后直接执行 opencode run "..." 就会使用固定模型，不再依赖自动选择。

注意事项

环境变量名不一致导致调用失败

有一种情况值得单独说明：providers list 显示 Google 已通过某个环境变量被检测到，但实际运行时却报错说缺少另一个名字的密钥。原因大致如下：模型目录中 Google 提供商登记了多个环境变量名，OpenCode 只要发现其中任意一个有值就认为该提供商「已检测到」，但把密钥传给底层 SDK 的逻辑只对「只登记了一个环境变量名」的提供商生效。于是 Google 对应的 SDK 会去找它自己默认的那个变量名，找不到就报错。

规避方式有两种。一是让 SDK 能读到的名字上也有值：

export GOOGLE_GENERATIVE_AI_API_KEY="$GEMINI_API_KEY"

二是在配置里显式指定密钥来源：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "google": {
      "options": {
        "apiKey": "{env:GEMINI_API_KEY}"
      }
    }
  }
}

这类行为与具体版本相关，后续版本可能调整，遇到时以官网当前信息为准。

默认模型会随环境变化

不指定模型时，被选中的模型取决于当前检测到哪些提供商。仅仅是增删一个环境变量，就可能导致默认模型改变。如果对结果有稳定预期，就用 -m 或配置文件里的 model 固定下来。

注意区分同名项目

搜索资料时可能遇到另一个同名的 OpenCode 项目，那个项目已经归档，其后续项目名为 Crush。阅读配置或命令说明时，先确认讲的是不是当前这个仍在维护的版本，避免照着过时文档操作。

安装脚本依赖外部接口

安装脚本需要向 GitHub API 查询版本号。在公司代理等无法访问该接口的环境中会直接失败，此时改用 npm 安装即可。

语言服务器需要单独准备

debug lsp 系列命令本身可用，但诊断结果依赖对应语言的语言服务器是否已安装。返回空结果时，优先检查语言服务器，而不是怀疑命令本身。

价格与配额

各提供商的计费方式、免费额度与可用地区差异较大，且会随时调整。使用前请以各提供商官网与 OpenCode 官网的当前信息为准。

返回