OpenCode 安装配置教程：接入 API、Copilot 与 VS Code/Cursor 的避坑指南

📚 本文隶属于 AI 工具完全指南（2026）系列，聚焦 AI 编程工具这一支。想系统了解 ChatGPT / Gemini / Kimi 等主流大模型怎么选，先看总览页。

Claude Code 配置太麻烦？来试试 OpenCode。

如果你最近在折腾 Claude Code，大概率已经发现一个很现实的问题：

它本身不送模型，想真正用起来，前面还得先把 provider、API Key、模型这些东西配明白。

对老手来说，这不算什么。

但对大部分刚上手的人来说，真正劝退的，往往不是能力不够，而是还没开始写代码，就先被一堆配置劝退了。

OpenCode 在这点上会友好很多。

它官方首页直接写了 Free models included，你可以先把工具跑起来，再决定后面是继续用它推荐的接入方案，还是切到 Copilot、第三方 API、中转站这些更灵活的配置。

也就是说，OpenCode 更像是那种“先上手、再折腾”的工具，而不是一开始就逼你把所有配置都研究明白。

当然，真到实际安装的时候，坑还是有，而且大多都集中在后半段：

装完以后不知道怎么接模型
配了 API 和 KEY，结果一直报错
VS Code 里能搜到插件，但就是跑不起来
明明教程照着抄了，命令、配置路径、接入方式却和现在版本对不上

我这两天重新把 OpenCode 走了一遍，顺手把旧教程里最容易过时的地方都对了一遍。你如果只想用 10 分钟把 OpenCode 配到能正常开工，这篇直接照着做就行。

这篇文章重点讲 4 件事：

OpenCode 怎么安装
怎么接入你自己的 API 和 KEY
怎么用 Copilot 账号直接登录
VS Code / Cursor 里怎么接起来，以及哪些地方最容易踩坑

一、先说结论：现在最稳的配置顺序

别一上来就手改一堆配置文件，最稳的顺序其实是：

先安装 OpenCode
终端里先跑起来
优先用 /connect 接入账号或提供商
需要自定义中转站时，再补 opencode.json
最后再接 VS Code / Cursor

这样做的好处是：你能先确认到底是安装问题、账号问题，还是配置文件问题，不会一上来全混在一起。

二、OpenCode 下载与安装

官方安装命令：

curl -fsSL https://opencode.ai/install | bash

如果你本机已经有 Node / npm，也可以直接全局安装：

npm i -g opencode-ai

装完后，在终端执行：

opencode

只要能正常进入界面，说明第一步已经过了。

如果这里就进不去，先别继续折腾配置。优先检查两件事：

opencode 命令有没有进环境变量
你的终端是不是刚装完还没重开

跑免费模型测试一下：输入 /models 进行选择

打招呼：

三、现在最推荐的接入方式：先用 `/connect`

这一步是很多老教程最容易过时的地方。

现在官方文档更推荐你先在 OpenCode 里直接输入：

/connect

然后按照界面提示去选择接入方式。常见有两类：

直接登录账号，比如用 Copilot 这类现成账号体系
接入自定义 provider，也就是你自己的 API / 中转站

为什么我建议你先走 /connect？

因为它能先把“有没有接上”这件事验证掉。很多人一开始就打开 JSON 手搓，最后其实错的是 KEY、Base URL，甚至只是模型名写错了。

接好以后，再输入：

/models

切换到你刚刚接入的模型，随便打一段招呼测试一下。只要能正常回复，这条链路就已经通了。

四、如果你用 CC Switch 或其他中转站，配置文件这样写

如果你已经习惯用 CC Switch 管理 API 和 KEY，那也完全没问题。

打开 CC Switch，找到 OpenCode 相关配置，新增一个 provider

把你的 API、KEY 和可用模型填进去。如下图所示：

这里有 3 个非常高频的坑，我建议你直接记住：

4.1 `baseURL` 很多时候要带 `/v1`

如果你接的是 OpenAI 兼容接口，中转站一般不是填到域名根路径，而是要写到 /v1 这一层。

这就是为什么很多人 API 和 KEY 都没错，但还是一直报错。

4.2 模型名不要想当然

配置里写的模型名，必须和你中转站真实暴露出来的模型名一致。

不是你觉得它叫 gpt-5.4 就一定能用，有些站点会改名、映射，甚至同一个模型会带不同后缀。最稳的方法不是猜，是直接看你后台里给的实际名字。

4.3 先验证终端，再接编辑器

很多人喜欢先装扩展，再回头查 CLI 为什么不通。顺序反了。

正确做法是：先确认终端里 opencode 能正常对话，再去接 VS Code / Cursor。这样出了问题也能很快定位。

测试自定义的供应商模型：/modes 选择对应供应商模型

打招呼：

五、Copilot 集成：有账号的话，真的是最快方案

如果你手上本来就有 Copilot 账号，那它其实是 OpenCode 非常省事的一条路。

在 OpenCode 里直接走登录流程，接入以后，你就可以直接调用这个账号下可用的模型，不用自己折腾单独的 API 分发。

这一套最大的优点就两个字：省心。

尤其你只是想先体验一下 OpenCode 的工作流，而不是立刻把自定义 provider 打磨到完美，那 Copilot 登录通常是最快能跑起来的方案。

六、VS Code / Cursor 配置：先跑通 CLI，再谈插件

这一段也是最容易踩坑的。

很多人以为去插件市场搜一下 OpenCode，点安装，就万事大吉了。实际上不是。

更稳的做法是：

先在插件中心搜索并安装 OpenCode
打开编辑器的集成终端
在终端里直接执行 opencode
如果提示安装配套扩展或依赖，按提示完成
再回到编辑器里测试快捷调用

配置文件会不会自动读取？

会。并且是分层合并读取。

常见配置路径：~/.config/opencode/opencode.json

你配置了 CC Switch 或 opencode.json 后，OpenCode 会按优先级自动加载（全局配置 + 项目配置），不需要手动“再导入一次配置”。

最小可用配置示例（opencode.json）

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ccs": {
      "npm": "@ai-sdk/openai",
      "options": {
        "apiKey": "你的_KEY",
        "baseURL": "https://你的中转站地址/v1"
      },
      "models": {
        "gpt-5.4": {
          "name": "gpt-5.4"
        },
        "claude-sonnet-4": {
          "name": "claude-sonnet-4"
        }
      }
    }
  },
  "keybinds": {
    "input_paste": "alt+v"
  }
}

图片粘贴快捷键，建议放到 tui.json

很多旧教程把 keybinds 写在 opencode.json。

新版本更推荐写在：~/.config/opencode/tui.json，示例：

{
  "$schema": "https://opencode.ai/tui.json",
  "keybinds": {
    "input_paste": "alt+v"
  }
}

这样你在实际写提示词、贴截图的时候会顺手很多。

七、10 分钟避坑清单

如果你没时间看完整篇，至少把下面这份清单过一遍：

安装完先在终端执行 opencode
优先用 /connect 做第一次接入
接好以后立刻用 /models 切换并测试
自定义中转站时，先检查 baseURL 是否写了 /v1
模型名必须按实际提供名称填写
发现配置不生效时，优先怀疑“被其他层级配置覆盖”
VS Code / Cursor 只装插件不够，还要在集成终端里真正跑一次
先让 CLI 正常，再折腾编辑器集成

八、我更推荐哪种方案？

如果你是第一次上手，我建议你按这个优先级选：

方案 A：先用 Copilot 登录

适合：

你想最快跑起来
你不想现在就折腾 API
你主要是先体验 OpenCode 工作流

方案 B：用 CC Switch / 中转站统一管理

适合：

你手里有多个模型源
你想把 API、KEY、模型列表统一收口
你后面还会接别的工具，不只 OpenCode

九、最后总结

OpenCode 真正难的，从来不是安装，而是“到底该先配哪一步”。

你只要记住一句话：先跑通，再美化；先验证 CLI，再接编辑器；先 /connect，再改 JSON。

这样基本就能避开 99% 的坑。

觉得这篇有用，可以先收藏着，真要配置的时候照着一步一步做，基本不会翻车。

补充阅读

还在 Claude Code 和 OpenCode 之间犹豫？先看那篇的完整对比，它更适合想深入折腾配置的人
想系统了解 AI 编程工具、ChatGPT / Gemini / Kimi 怎么选，回 AI 工具完全指南（2026）总览页
用中转站之前先确认 baseURL 要不要带 /v1、模型名对不对，这两点是绝大多数报错的根源