OpenCode 配置教程
添加 OpenAI 兼容供应商,在 OpenCode 中选择 QuickRouter 模型。
先安装 OpenCode,并创建 QuickRouter API Key。
推荐用 QuickRouter Switch 一键配置。已安装 CC-Switch 的用户也可选择备选方式。
使用 QuickRouter Switch 配置
还没安装?下载并安装 QuickRouter Switch。
- 添加供应商
打开 QuickRouter Switch,在左边选「OpenCode」,点「添加供应商」。
- 填写 API Key
把自己的 API Key 粘贴到同名输入框。地址和接口格式已经填好。模型可换成自己实际要用、当前 Key 能调用的模型。
图 11 核对 OpenCode 的接口格式、API Key 和 Base URL。 图 12 可换成自己实际要用的模型;填写当前 API Key 可调用的模型 ID。 - 添加并打开工具
点右下角「添加」。若 QuickRouter 卡片还在「可添加」区,点卡片上的加号。重开 OpenCode,在模型列表里选 QuickRouter 和你要用的模型。
图 13 若卡片在「可添加」,点击加号写入 OpenCode 配置。 图 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。
- 添加供应商
打开 CC Switch,在左侧选择OpenCode,点击添加供应商,选择自定义配置。
- 填写连接信息
- 供应商标识填
quickrouter,名称填QuickRouter。 - 接口格式选 OpenAI Compatible,API Key 填自己的令牌,Base URL 填
https://api.quickrouter.ai/v1。

OpenCode:接口格式选 OpenAI Compatible,供应商标识 quickrouter。 - 供应商标识填
- 设置模型
- 找到模型区,点击「手动添加」新增一行。
- 添加模型:ID 填
gpt-6-sol,显示名称填gpt-6-sol。
示例模型可以换成自己实际要用的模型,使用 模型价格页中的完整模型 ID,并确认 API Key 有权限。
- 保存供应商
在表单底部点添加,回到 OpenCode 的供应商列表,确认出现 QuickRouter 卡片。
- 启用并打开工具
本节直接写入客户端配置。
如果卡片在「可添加」,点卡片上的添加,确认移到「已添加」。重新打开 OpenCode。终端版运行
opencode,输入/new新建会话,再输入/models,选择quickrouter/gpt-6-sol。桌面版新建会话后,用模型选择器选 QuickRouter 下的同一模型。若填写了其他模型 ID,请选择实际填写的模型。在「可添加」里点 QuickRouter 右侧的「添加」,再打开 OpenCode 选模型。 - 发送消息验证
发送「请只回复 OK」。收到回复后,到 QuickRouter 使用日志核对这次请求的时间和模型 ID。
查看配置细节与排错
配置写入 ~/.config/opencode/opencode.json,已有 opencode.jsonc 时优先使用它;供应商使用 @ai-sdk/openai-compatible。新增供应商不会替你修改全局默认模型,需在 OpenCode 中选择模型。本节直接调用 Chat 接口,无需 CC Switch 本地路由。
确认配置生效
打开 OpenCode 的新会话,选择刚配置的模型,发送「请只回复 OK」。在 QuickRouter 使用日志核对发送时间和实际请求模型。遇到 401 或 403 时,先检查令牌和模型权限。
查看原有安装、手动配置与排错
适用范围:先看 opencode --version。2.x 用下方 v2 路线;1.x 保留原有 Responses 配置。
版本与验证:v2 步骤按官方文档整理;2026-09-28 的真实调用记录对应 macOS 上的 v1.2.15。
配置速查
| 配置项 | 填写内容 | 注意事项 |
|---|---|---|
| Base URL | https://api.quickrouter.ai/v1 | 填到 /v1,应用按配置的协议拼接请求路径。 |
| 模型 ID | gpt-6-sol | 换成当前令牌支持所选协议的实际模型 ID。 |
| 配置入口 | opencode.json(c) | v2 原生用 providers,v1 用 provider。 |
还没有 API Key?注册获取免费体验额度 · 已注册:进入控制台创建 API Key
为此工具单独创建令牌,并设置合理额度和模型权限。截图中的模型仅作示例,以账号当前可用模型为准;不要公开密钥或上传含密钥的配置文件。
先确认版本:opencode --version。2.x 看这里 · 1.x 看原有步骤。
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_KEYWindows 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/openai | https://api.quickrouter.ai/v1 → /responses |
| Chat Completions | @ai-sdk/openai-compatible | https://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 与支持协议 · 计算费用 · 创建令牌。
历史界面参考




连接失败时按这几步排查
Base URL 为 https://api.quickrouter.ai/v1;@ai-sdk/openai-compatible 使用 Chat Completions,@ai-sdk/openai 的 Responses 用法需要服务端支持 Responses;不能仅改模型 ID 就切换协议。
- 先运行 opencode --version,按该版本 schema 检查配置。使用 provider/npm/options 的配置,不混入其他版本字段。
- 核对 provider ID、SDK 包、options.baseURL 和 models 键;当前模型引用使用 provider ID/模型 ID。
- 检查全局、项目配置及 OPENCODE_CONFIG_CONTENT 的覆盖关系,保留备份,仅修改实际生效的条目。
容易混淆的情况
- provider package error 先查依赖和配置加载;请求尚未发出时更换 API Key 没有帮助。
- AI_APICallError 是外层错误,需展开 HTTP 状态和正文;auth.json 存有凭据不等于当前 provider 正在使用它。
怎样确认修复成功
启动新会话先测试短文本,核对实际 endpoint 和 provider;随后在测试目录授权读取 README,分别记录两项结果。
记录所装客户端版本、模型 ID、请求时间、最终路径与脱敏状态。本节为配置核对指南,未新增客户端付费调用实测;保留原文已有验证记录的适用范围。
怎样确认配置已生效
- 执行 opencode --version,确认安装的主版本。
- 在 /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。