接入 OpenCode

OpenCode 是终端里的 AI 编程助手。它和 Claude Code、Codex 一样适合在项目目录里直接提问、读代码和执行任务，但它的官方配置方式更偏向 JSON 配置文件，而不是只靠几个环境变量硬顶到底。

想把模型、Provider 和轻量模型一起管理清楚时，OpenCode 这套配置方式会更省事。

下载与安装

官方入口：

• 官网：https://opencode.ai/
• 配置文档：https://opencode.ai/docs/config/
• npm 包：https://www.npmjs.com/package/opencode-ai
• GitHub：https://github.com/anomalyco/opencode

OpenCode 官方 README 当前给出的安装方式比较多：

• npm i -g opencode-ai@latest
• bun add -g opencode-ai@latest
• pnpm add -g opencode-ai@latest
• brew install anomalyco/tap/opencode
• Windows 用 Scoop / Chocolatey
• 官方安装脚本 curl -fsSL https://opencode.ai/install | bash

国内用户一般建议按这个顺序选：

1. 已经装好 Node.js 和 npm：直接 npm 全局安装
2. Windows 用户已经在用 Scoop / Chocolatey：走系统包管理器
3. macOS / Linux 用户本来就用 Homebrew：走 brew
4. 其他情况再考虑官方安装脚本

Node.js 还没装时，先看 Windows Node 安装、macOS Node 安装 或 Linux Node 安装。

最常见的一条安装命令是：

npm install -g opencode-ai@latest
opencode --version

如果 npm 下载慢，先确认你已经把 npm registry 切到了镜像：

npm config set registry https://registry.npmmirror.com
npm config get registry

为什么建议写配置文件

OpenCode 官方文档把 provider、model、small_model 都放进了 JSON / JSONC 配置里。这样做有两个好处：

1. 主模型和轻量模型可以明确分开，不用每次靠记忆切换
2. 你能一眼看出当前到底走的是哪个 Provider、哪个模型，而不是只靠环境变量猜

对长期使用来说，这比只设置 OPENAI_BASE_URL 和 OPENAI_API_KEY 更稳定。

配置文件在哪里

OpenCode 官方配置页当前把配置来源分成几层，而且这些配置是合并关系，不是“后者把前者整份替换掉”。

第一次接入最常用的是这两层：

• 全局配置：~/.config/opencode/opencode.json
• 项目级配置：项目根目录的 opencode.json
• 凭证存储：~/.local/share/opencode/auth.json（只在你使用 /connect 保存凭证时出现）

有两个地方特别容易写错：

1. .opencode/ 目录主要放 agents、commands、plugins 这类内容，不是主配置文件位置
2. 项目级配置要放在仓库根目录，OpenCode 会从当前目录往上找，直到最近的 Git 根目录

第一次接入建议先把 Provider 和默认模型写进全局配置。这样你换到任何项目目录启动 OpenCode，都能先确认 小蓝中转站 这条链路已经通了。
等全局配置稳定以后，再按仓库需要在项目根目录补一份 opencode.json，只覆盖这个项目想单独调整的部分。

已经在某个项目里写过一份旧 opencode.json 时，那一份项目级配置通常会比全局配置更先生效。
很多“我明明改了全局配置却没反应”，最后都不是 OpenCode 没读取，而是当前仓库里还压着另一份旧值。

配置 小蓝中转站 Provider

下面是一份适合第一次接入的 opencode.json 示例：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "xiaolan": {
      "npm": "@ai-sdk/openai-compatible", // OpenAI 兼容网关用这个适配器
      "name": "小蓝中转站", // 这里只是本地显示名称
      "options": {
        "baseURL": "https://xiaolan.ainb.plus/v1", // OpenCode 这里要写 /v1
        "apiKey": "{env:小蓝中转站_API_KEY}" // 从环境变量读取，避免把 Key 写进文件
      },
      "models": {
        "替换成模型广场里的主模型名": {
          "name": "主力模型" // 这个名字会出现在模型选择列表里
        },
        "替换成模型广场里的轻量模型名": {
          "name": "轻量模型"
        }
      }
    }
  },
  "model": "xiaolan/替换成模型广场里的主模型名", // 默认主模型
  "small_model": "xiaolan/替换成模型广场里的轻量模型名" // 轻任务和次级调用走这里
}

这段配置里有几个关键点：

• xiaolan 是你给这个 Provider 起的名字，后面的 model / small_model 前缀要和它一致
• models 下面的 key 本身就是实际模型 ID，不是再额外写一层 id
• baseURL 这里必须是 https://xiaolan.ainb.plus/v1
• @ai-sdk/openai-compatible 适合 OpenAI 兼容的 /v1/chat/completions 链路

模型名继续从模型广场复制，不要手打。
模型 ID 里常见的大小写、日期后缀、连字符，只要少一个字符，OpenCode 就会把它当成另一条模型。

主模型和 small_model 怎么选

第一次接入时，不需要一上来就追求“最强模型”。更稳的做法是分成两类来选：

• model：你准备长期拿来正式编码、改文档、做复杂分析的主力模型
• small_model：更便宜、更快，适合标题生成、轻量总结、短问题验证的模型

这样分开的好处不是为了凑配置项，而是为了让 OpenCode 在不同场景下自动走更合适的模型。
把两个位置都写成同一个大模型时，也不是不能用，但整体成本和响应速度通常都不如“主力模型 + 轻量模型”这套组合稳定。

第一次拿不准时，可以按这个思路选：

1. 先在模型广场找一款你准备长期使用的编程模型，填到 model
2. 再选一款同系列、更快或更便宜的模型，填到 small_model
3. 先让 OpenCode 做一条只读任务，确认会话能正常返回
4. 确认稳定以后，再按你的成本和速度偏好继续替换

已经知道某个仓库只能用固定模型时，也可以把默认模型放在全局配置里，再在项目根目录用项目级配置单独覆盖。

再补上环境变量

把下面这一项追加到你的 ~/.zshrc、~/.bashrc 或其他 shell 配置里：

export 小蓝中转站_API_KEY="sk-你给 OpenCode 单独创建的 Key"

为什么建议单独放环境变量：

• Key 不直接写进项目仓库
• 同一份 opencode.json 可以在多台机器复用
• 以后轮换 Key 时，不用再回头翻配置文件

模型名更适合直接写在 opencode.json 里。
原因不是偷懒，而是 OpenCode 的 models 用的是“模型 ID 作为 key”的结构。把主模型和轻量模型明明白白写出来，后面你再看配置时，一眼就能知道当前到底会调用哪两个模型。

保存后重新打开终端，或者执行：

source ~/.zshrc

用的是 Bash 时，就改成对应的 ~/.bashrc 或 ~/.bash_profile。

也可以把 Key 交给 /connect

更习惯在 OpenCode 界面里保存密钥时，也可以先启动一次：

opencode

然后在输入框里执行：

/connect

按 OpenCode 官方自定义 Provider 的做法，往下选择 Other，把 Provider ID 填成 xiaolan，再粘贴你的 Key。
这样 Key 会交给 OpenCode 的认证存储管理，opencode.json 里就可以只保留 baseURL 和 models 这部分配置。

要注意一件事：在 /connect 里填的是 xiaolan 时，配置文件里也必须继续写 provider.xiaolan。
Provider ID 一旦不一致，OpenCode 虽然能启动，但会像“看不到这把 Key”一样表现得很奇怪。

走的是 /connect 路线时，OpenCode 会把凭证写进本机的认证存储。
官方当前文档给出的常见位置是 ~/.local/share/opencode/auth.json。这意味着：

• 适合个人电脑长期使用
• 不适合把这类文件直接同步进代码仓库
• 共用机器上不用时最好及时清理旧凭证

第一次测试

进入一个你熟悉的小项目目录，先让 OpenCode 做一件很短的事：

opencode models xiaolan --refresh
opencode

启动后可以先问：

请先概括一下当前目录是做什么的，不要修改任何文件。

第一次不急着让它大改代码。先确认三件事：

1. opencode models xiaolan --refresh 能列出你刚写进去的模型
2. 进入会话后能正常返回回复
3. 当前使用的模型前缀是 xiaolan/

确认无误后，再继续让它分析更多文件或执行复杂任务。

想在会话里直接切模型时，OpenCode 官方当前支持在 TUI 里用 /models 进入模型选择，也支持通过启动参数覆盖默认模型。
第一次接入建议先把默认模型写稳，再去切换。这样一旦切错模型，你也更容易判断到底是“当前会话切错了”，还是“底层 Provider 配置本来就没写对”。

使用建议

small_model 不只是可有可无

OpenCode 官方文档专门区分了 model 和 small_model。轻量模型常用在标题生成、轻任务和一些不需要最强推理的场景里。

把它单独配出来，通常能让整体体验更稳，成本也更容易控制。

项目级配置适合团队仓库

当你已经有一套稳定的全局配置后，如果某个仓库只允许使用固定模型，可以再补一份：

项目根目录/opencode.json

例如全局配置里已经写好了 provider.xiaolan、Key 和常用模型，这个仓库只想强制切到另一组主模型，那项目级配置里只改 model / small_model 就够了。
因为 OpenCode 的配置是合并关系，所以你不用把整份 Provider 再复制一遍。

不想手写配置也可以走 CC-Switch

更习惯图形界面时，也可以用 CC-Switch 先把地址和 Key 写进去，再回头细化 opencode.json。两种方式并不冲突。

常见问题

opencode 命令不存在

先确认安装本身成功：

opencode --version
which opencode

如果版本命令都找不到，问题还停留在安装层，不是 小蓝中转站 配置层。

启动了，但看不到你配置的 Provider

优先检查：

• opencode.json 是否真的放在 ~/.config/opencode/ 或项目根目录下
• 你是不是把主配置误写进了 .opencode/
• provider.xiaolan、model、small_model 前缀是否一致

例如 model 写成 xiaolan/qwen3-coder，那 provider.xiaolan.models 下面就必须真的有一项 key 叫 qwen3-coder。

模型名报错

回到模型广场重新复制模型名，覆盖 models 里的 key，以及上面的 model / small_model。

很多“模型不存在”并不是 OpenCode 不支持，而是模型名沿用了别的教程里的旧值。

想快速核对当前加载到 OpenCode 里的模型时，也可以直接执行：

opencode models xiaolan

配置改了没生效

OpenCode 读取的是启动时的配置和变量。改完配置文件或环境变量后，先完全退出当前终端会话，再重新启动一次。

同时写了全局配置和项目级配置时，项目级配置会更靠前，需要确认当前仓库根目录里是不是还留着另一份旧 opencode.json。

走的是 /connect 路线时，还可以顺手检查一下：

opencode auth list

这条命令能帮助你确认 xiaolan 这把凭证到底有没有真的存进去。

模型能列出来，但实际对话还是走错模型

这类问题通常不是 Key 失效，而是“默认模型”和“当前会话模型”不是同一个值。

优先检查这三层：

1. opencode.json 里的 model / small_model 是否已经改成新值
2. 当前仓库根目录是不是还有另一份项目级 opencode.json
3. 你是不是在当前会话里手动切过模型

只要先把这三层拆开看，排障会比反复重装快很多。