OpenCode 配置教程

添加 OpenAI 兼容供应商,在 OpenCode 中选择 QuickRouter 模型。

先安装 OpenCode,并创建 QuickRouter API Key。

推荐用 QuickRouter Switch 一键配置。已安装 CC-Switch 的用户也可选择备选方式。

使用 QuickRouter Switch 配置

还没安装?下载并安装 QuickRouter Switch。

  1. 添加供应商

    打开 QuickRouter Switch,在左边选「OpenCode」,点「添加供应商」。

  2. 填写 API Key

    把自己的 API Key 粘贴到同名输入框。地址和接口格式已经填好。模型可换成自己实际要用、当前 Key 能调用的模型。

    核对 OpenCode 的接口格式、API Key 和 Base URL。
    图 11 核对 OpenCode 的接口格式、API Key 和 Base URL。
    可换成自己实际要用的模型;填写当前 API Key 可调用的模型 ID。
    图 12 可换成自己实际要用的模型;填写当前 API Key 可调用的模型 ID。
  3. 添加并打开工具

    点右下角「添加」。若 QuickRouter 卡片还在「可添加」区,点卡片上的加号。重开 OpenCode,在模型列表里选 QuickRouter 和你要用的模型。

    若卡片在「可添加」,点击加号写入 OpenCode 配置。
    图 13 若卡片在「可添加」,点击加号写入 OpenCode 配置。
    如需设为默认,使用 QuickRouter 卡片的更多菜单。
    图 14 如需设为默认,使用 QuickRouter 卡片的更多菜单。
查看具体参数和更多操作

「供应商标识」保留 quickrouter,「Base URL」用 https://api.quickrouter.ai/v1。接口格式保留「OpenAI Compatible」。 「模型配置」预填 claude-sonnet-5-5。预填模型仅作示例,可换成自己实际要用的模型。请填写当前 API Key 可调用的完整模型 ID。

填好后点右下角「添加」。如果 QuickRouter 仍在「可添加」区,再点卡片上的「添加」,使其进入「已添加」。 重新打开 OpenCode,从 QuickRouter 供应商选择目标模型。需要设为默认时,可在「已添加」卡片的「更多」菜单选择「设为默认」。

使用 CC-Switch 配置

还没安装?下载并安装 CC-Switch。

查看 OpenCode 专题:配置、排错和可复跑案例

  1. 添加供应商

    打开 CC Switch,在左侧选择OpenCode,点击添加供应商,选择自定义配置。

  2. 填写连接信息
    • 供应商标识填 quickrouter,名称填 QuickRouter。
    • 接口格式选 OpenAI Compatible,API Key 填自己的令牌,Base URL 填 https://api.quickrouter.ai/v1。
    OpenCode 的 OpenAI Compatible 接口与 gpt-6-sol 模型配置
    OpenCode:接口格式选 OpenAI Compatible,供应商标识 quickrouter。
  3. 设置模型
    • 找到模型区,点击「手动添加」新增一行。
    • 添加模型:ID 填 gpt-6-sol,显示名称填 gpt-6-sol。

    示例模型可以换成自己实际要用的模型,使用 模型价格页中的完整模型 ID,并确认 API Key 有权限。

  4. 保存供应商

    在表单底部点添加,回到 OpenCode 的供应商列表,确认出现 QuickRouter 卡片。

  5. 启用并打开工具

    本节直接写入客户端配置。

    如果卡片在「可添加」,点卡片上的添加,确认移到「已添加」。重新打开 OpenCode。终端版运行 opencode,输入 /new 新建会话,再输入 /models,选择 quickrouter/gpt-6-sol。桌面版新建会话后,用模型选择器选 QuickRouter 下的同一模型。若填写了其他模型 ID,请选择实际填写的模型。

    OpenCode 的 CC Switch 供应商界面截图
    在「可添加」里点 QuickRouter 右侧的「添加」,再打开 OpenCode 选模型。
  6. 发送消息验证

    发送「请只回复 OK」。收到回复后,到 QuickRouter 使用日志核对这次请求的时间和模型 ID。

查看配置细节与排错

配置写入 ~/.config/opencode/opencode.json,已有 opencode.jsonc 时优先使用它;供应商使用 @ai-sdk/openai-compatible。新增供应商不会替你修改全局默认模型,需在 OpenCode 中选择模型。本节直接调用 Chat 接口,无需 CC Switch 本地路由。

确认配置生效

打开 OpenCode 的新会话,选择刚配置的模型,发送「请只回复 OK」。在 QuickRouter 使用日志核对发送时间和实际请求模型。遇到 401 或 403 时,先检查令牌和模型权限。

返回工具教程列表

查看原有安装、手动配置与排错
官方入口:OpenCode 官网

更新于

适用范围:先看 opencode --version。2.x 用下方 v2 路线;1.x 保留原有 Responses 配置。

版本与验证:v2 步骤按官方文档整理;2026-09-28 的真实调用记录对应 macOS 上的 v1.2.15。

配置速查

配置项填写内容注意事项
Base URLhttps://api.quickrouter.ai/v1填到 /v1,应用按配置的协议拼接请求路径。
模型 IDgpt-6-sol换成当前令牌支持所选协议的实际模型 ID。
配置入口opencode.json(c)v2 原生用 providers,v1 用 provider。

还没有 API Key?注册获取免费体验额度 · 已注册:进入控制台创建 API Key

为此工具单独创建令牌,并设置合理额度和模型权限。截图中的模型仅作示例,以账号当前可用模型为准;不要公开密钥或上传含密钥的配置文件。

先确认版本:opencode --version。2.x 看这里 · 1.x 看原有步骤。

OpenCode v2 使用 providers 和 package;v1 使用 provider 和 npm
版本选择示意。迁移时先备份现有配置。

OpenCode v2:添加 QuickRouter

1. 确认版本、准备令牌

尚未安装可看 官方安装指南。确认运行的是 2.x,再创建 QuickRouter API Key。

2. 添加提供商与模型

把下面配置合并到测试项目根目录的 opencode.json,或用户级 ~/.config/opencode/opencode.json。已有 JSONC 时编辑原文件,不要同时创建另一份。将两处模型 ID 和同一条显示名称一起换为实际值。

{
  "$schema": "https://opencode.ai/config.json",
  "model": "quickrouter/gpt-6-sol",
  "providers": {
    "quickrouter": {
      "name": "QuickRouter",
      "env": [
        "QUICKROUTER_API_KEY"
      ],
      "package": "@opencode/ai/providers/openai-compatible",
      "settings": {
        "baseURL": "https://api.quickrouter.ai/v1"
      },
      "models": {
        "gpt-6-sol": {
          "name": "gpt-6-sol"
        }
      }
    }
  }
}

上面的包走 Chat Completions。需要 Responses 时,使用 @opencode/ai/providers/openai-compatible/responses 并选择支持 Responses 的模型。先核对 官方运行时包 和令牌权限。

3. 设置 API Key、发送测试消息

macOS / Linux:

printf 'QuickRouter API Key: '; read -rs QUICKROUTER_API_KEY; printf '\n'
export QUICKROUTER_API_KEY

Windows PowerShell 7.2+:

$env:QUICKROUTER_API_KEY = Read-Host -MaskInput "QuickRouter API Key"

在同一终端启动客户端。打开新终端后需要重新设置变量。

在同一终端运行 opencode,进入 /models 选 QuickRouter 模型,发送「请只回复 OK,不要读取或修改任何文件。」;回复后在控制台使用日志核对实际模型。若还在使用旧模型,检查当前项目的配置是否覆盖了用户配置。

已有 v1,怎么迁移?

先备份 v1 配置。v2 会读取仍受支持的 v1 字段,可以先启动验证,再决定是否改成原生 v2 格式。v1 插件不能直接搬到 v2,见 官方迁移说明。

OpenCode v1:原生 Responses 配置

第 1 步:记录正在运行的版本

command -v opencode
opencode --version

本机有两个安装:Homebrew 路径为 1.2.15,用户目录另有 1.3.13。下面只绑定 /opt/homebrew/bin/opencode 1.2.15;不能把公开包最新版当成实测版。

第 2 步:创建令牌并选择 Responses 提供商

进入 QuickRouter 控制台 → API 令牌 → 新建,选择支持目标模型及协议的分组,设置额度后复制令牌。已有令牌可继续使用;模型目录和权限不是同一回事。查看创建分组令牌的图文步骤。

v1 合并到 ~/.config/opencode/opencode.json 或测试项目 opencode.json。本次用 @ai-sdk/openai 走 Responses,避免把 Chat 与 Responses 返回格式混用。

{
  "$schema": "https://opencode.ai/config.json",
  "model": "quickrouter/gpt-6-sol",
  "provider": {
    "quickrouter": {
      "npm": "@ai-sdk/openai",
      "name": "QuickRouter",
      "options": {
        "baseURL": "https://api.quickrouter.ai/v1",
        "apiKey": "{env:QUICKROUTER_API_KEY}"
      },
      "models": {
        "gpt-6-sol": {
          "name": "gpt-6-sol"
        }
      }
    }
  }
}

第 3 步:设置环境变量并核对模型

export QUICKROUTER_API_KEY="YOUR_QUICKROUTER_API_KEY"
/opt/homebrew/bin/opencode models quickrouter
/opt/homebrew/bin/opencode run --model quickrouter/gpt-6-sol "Reply exactly QUICKROUTER_OK. Do not use tools."

提供商 ID、models 内部 ID 与 quickrouter/gpt-6-sol 三处对应。只列出模型不能证明调用成功;用户配置、项目配置和 OPENCODE_CONFIG_CONTENT 会合并,检查覆盖来源。

第 4 步:按协议选择包与鉴权

协议v1 运行时包基址 / 最终路径
Responses@ai-sdk/openaihttps://api.quickrouter.ai/v1 → /responses
Chat Completions@ai-sdk/openai-compatiblehttps://api.quickrouter.ai/v1 → /chat/completions
Anthropic Messages@ai-sdk/anthropic按包要求设置 /v1 基址 → /messages

切换包时同步更换支持该协议的模型。v2 使用 providers/package/settings,必须按独立 v2 官方文档;不要把这些字段混进本机 v1 配置。

真实调用记录与验证范围

测试日期:2026-09-28(Asia/Shanghai);macOS 26.3。查看脱敏记录、软件版本和真实生成图片。一次文本成功仅证明本次请求,不代表其他模型、工具执行、多轮上下文或桌面版均已通过。

OpenCode 1.2.15
provider: quickrouter
npm: @ai-sdk/openai
model: gpt-6-sol
{"type":"text","part":{"text":"QUICKROUTER_OK"}}
{"type":"step_finish","part":{"reason":"stop"}}

本次真实运行使用测试目录,关闭工具权限;验证了文本生成与客户端响应解析。代码读写、MCP、长会话未验证。能列出模型但调用失败时的检查步骤。

接下来:核对模型 ID 与支持协议 · 计算费用 · 创建令牌。

历史界面参考

打开终端
历史界面参考,截图版本未核实;提供商、模型与协议按本文实测 v1 配置填写。
输入 /models
历史界面参考,截图版本未核实;提供商、模型与协议按本文实测 v1 配置填写。
选择模型
历史界面参考,截图版本未核实;提供商、模型与协议按本文实测 v1 配置填写。
开始使用
历史界面参考,截图版本未核实;提供商、模型与协议按本文实测 v1 配置填写。

连接失败时按这几步排查

Base URL 为 https://api.quickrouter.ai/v1;@ai-sdk/openai-compatible 使用 Chat Completions,@ai-sdk/openai 的 Responses 用法需要服务端支持 Responses;不能仅改模型 ID 就切换协议。

  1. 先运行 opencode --version,按该版本 schema 检查配置。使用 provider/npm/options 的配置,不混入其他版本字段。
  2. 核对 provider ID、SDK 包、options.baseURL 和 models 键;当前模型引用使用 provider ID/模型 ID。
  3. 检查全局、项目配置及 OPENCODE_CONFIG_CONTENT 的覆盖关系,保留备份,仅修改实际生效的条目。

容易混淆的情况

  • provider package error 先查依赖和配置加载;请求尚未发出时更换 API Key 没有帮助。
  • AI_APICallError 是外层错误,需展开 HTTP 状态和正文;auth.json 存有凭据不等于当前 provider 正在使用它。

怎样确认修复成功

启动新会话先测试短文本,核对实际 endpoint 和 provider;随后在测试目录授权读取 README,分别记录两项结果。

记录所装客户端版本、模型 ID、请求时间、最终路径与脱敏状态。本节为配置核对指南,未新增客户端付费调用实测;保留原文已有验证记录的适用范围。

打开 OpenCode 交互排错并下载检查记录 · 官方配置参考

怎样确认配置已生效

  1. 执行 opencode --version,确认安装的主版本。
  2. 在 /models 选择模型,发送短消息并在 QuickRouter 使用日志核对。

接入失败时逐项检查

现象检查与处理
No model is available先声明 models,保存配置后重新进入 /models 选择。
API key 未找到/connect 中的提供商 ID 须与配置 key 相同。
配置报未知字段确认主版本,v1 使用 provider/npm/options,v2 使用 providers/package/settings。

资料与下一步

遇到问题时保留软件版本、请求时间、模型 ID、错误码和请求 ID,联系支持时先隐藏 API Key。

在线客服