OpenCode完全指南：国内直连全球API大模型

OpenCode 接入 QuickRouter API 教程

OpenCode 是一款面向开发者的终端 AI 编程工具，支持 CLI 与 TUI 两种交互方式。你可以直接在终端中通过自然语言完成代码生成、项目分析、文件编辑等操作。

如果你希望不使用默认模型提供方，也可以通过 OpenAI 兼容模式 将 OpenCode 接入 QuickRouter API(一个API Key接入全球大模型) https://quickrouter.ai 配置完成后，你就可以通过 QuickRouter 调用对应模型，在本地获得更稳定、更灵活、性价比更高的编程辅助体验。

一、接入前需要准备什么

开始之前，请先登录 QuickRouter API 控制台，准备好以下 3 项关键信息：

配置项	推荐填写内容	注意事项
API Key	`sk-xxxxxxxxxxxxxxxx`	请直接填写原始 Key
Base URL	`https://api.quickrouter.ai/v1`	需要包含 `/v1`
模型名称	例如 `gpt-5`	请填写 QuickRouter 实际支持，且你的账号有权限调用的模型

二、安装 OpenCode

请先确认你的电脑已经安装 Node.js 18 或更高版本。

如果本机还没有安装 Node.js，请先完成安装后再继续。

如果环境里没有 Node.js，可以先前往官网下载安装。

打开终端后执行安装命令：

官方一键安装脚本（推荐 macOS / Linux）

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

NPM 全局安装（推荐 Windows）

npm install -g opencode-ai

安装完成后，可以执行下面命令检查是否安装成功：

opencode --version

如果终端能够正常输出版本号，说明 OpenCode 已经安装完成。

三、配置 QuickRouter API 并启动 OpenCode

OpenCode 支持 OpenAI 兼容接口，因此最直接、最省事的接入方式，就是配置环境变量后直接启动。

方式一：快捷启动（推荐首次测试）

这种方式只在当前终端窗口中生效，适合第一次验证是否配置成功。

注意：设置环境变量和启动 opencode，最好在同一个终端窗口内完成。

Windows（PowerShell）

$env:OPENAI_API_KEY="sk-你的QuickRouter API密钥"
$env:OPENAI_BASE_URL="https://api.quickrouter.ai/v1"
opencode

macOS / Linux

export OPENAI_API_KEY="sk-你的QuickRouter API密钥"
export OPENAI_BASE_URL="https://api.quickrouter.ai/v1"
opencode

方式二：永久配置（推荐长期使用）

如果你不想每次打开终端都重新输入环境变量，可以改成长期配置。

方案 A：使用登录方式配置

先运行：

opencode auth login

然后按顺序完成下面几步：

在列表中选择 openai
选择 Manually enter API Key
粘贴你准备好的 QuickRouter API Key
按回车确认即可

方案 B：手动配置 `opencode.json`

找到或创建配置文件：

macOS / Linux：

~/.config/opencode/opencode.json

Windows：

C:\Users\你的用户名\.config\opencode\opencode.json

将下面内容写入并保存：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "quickrouter": {
      "api": "https://api.quickrouter.ai/v1"
    }
  }
}

然后再编辑系统环境变量并保存，重启终端后生效。

新增以下两个变量：

OPENAI_API_KEY=sk-你的QuickRouter API密钥
OPENAI_BASE_URL=https://api.quickrouter.ai/v1

四、开始使用与模型切换

成功进入 OpenCode 的交互界面后，你还需要指定要使用的模型。

1）查看模型列表

在输入框中输入：

/models

然后回车，在列表中选择你当前要使用的模型即可。

2）开始第一次对话

例如你可以直接输入：

你好

或者输入更实用的测试内容：

请帮我分析当前项目的目录结构

如果模型能够正常读取项目内容，并且流式返回回答，就说明 QuickRouter API 已经成功接入 OpenCode。

五、常见问题排查（FAQ）

Q1：为什么提示认证失败 / Invalid API Key？

可以优先检查以下几项：

API Key 是否复制完整
是否误带了多余空格或换行
环境变量名是否写错
OpenCode 识别的变量名应为 OPENAI_API_KEY

Q2：为什么提示连接超时或 Fetch Failed？

最常见的原因通常有这几个：

OPENAI_BASE_URL 填写错误
Base URL 没有带上 /v1
在新的终端窗口里运行，但没有重新设置环境变量
当前网络环境或代理设置异常

请重点确认下面这个地址是否填写正确：

https://api.quickrouter.ai/v1

Q3：为什么提示模型不存在（Model not found）？

通常是因为当前选择的模型并不在你账号可用范围内。

建议你直接通过：

/models

在 OpenCode 内查看和选择模型。

一般来说，能正常显示并可选中的模型，就是当前可以使用的模型。

六、总结

如果你想让 OpenCode 通过 QuickRouter API 来运行，核心步骤其实并不复杂：

安装 OpenCode
配置 OPENAI_API_KEY 和 OPENAI_BASE_URL
启动 opencode
在 /models 中选择可用模型
开始正常对话和使用

建议你第一次先用“快捷启动”方式测试，确认 OpenCode 能正常连通 QuickRouter API 之后，再改成“永久配置”。这样更稳，也更方便排查问题。