OpenCode 综合配置

本页将青云 TOP API 客户端接入资料按使用场景合并整理，适合第一次接入的用户，也适合需要核对协议和路径的 API 开发者。青云 TOP API 基于 New API 部署，因此 New API 官方应用教程中的兼容配置可以直接复用。

快速判断：我应该看哪一段？

• 只想聊天：先看桌面端的基础配置。
• 要接入 MCP、知识库或工作流：看 Agent/自动化章节。
• 要在终端写代码：看 CLI、Provider 和环境变量章节。
• 遇到 401、403、404 或模型不兼容：先检查本文末尾的接入检查清单，再查看对应来源章节。

OpenCode 配置（融合自原文档）

先安装opencode

官方文档

使用nodejs

npm install -g opencode-ai

配置提供者

https://opencode.ai/docs/providers/

##### 配置两个地方#

###### 提供者配置(没有这个文件就新建)#

###### ~ 代表用户的工作目录 如windows上 C:\\Users\\admin#

~/.config/opencode/opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://top.qingyuntop.ai/v1"
      }
    }
  }
}

##### 这里我替换了现有的 anthropic 地址#

###### 密钥配置#

###### 这里我们配置一个 claude 平台的，在我们网站控制台，创建key 并选择我们claude相关分组 如claude 专属#

~/.local/share/opencode/auth.json

{
  "google": {
    "type": "api",
    "API_KEY" : "$QINGYUN_TOP_API_KEY"
  },
  "anthropic": {
    "type": "api",
    "API_KEY" : "$QINGYUN_TOP_API_KEY"
  }
}

##### 打开终端#

##### 输入 /models#

##### 选择 anthropic 中的一个模型#

##### 开始使用#

接入检查

• API Key 使用 $QINGYUN_TOP_API_KEY 占位符保存，不要直接粘贴到公开代码或截图。
• OpenAI 兼容客户端通常使用 https://top.qingyuntop.ai/v1；如果客户端要求完整接口路径，再按其界面说明追加路径，避免重复填写 /v1。
• 先用客户端的“测试连接”或发送一条短消息验证，再到控制台调用日志核对模型和状态。

CherryStudio 配置 Claude Code、Gemini CLI、OpenCode（融合自原文档）

客户端下载地址: https://www.cherry-ai.com/
请保证你是最新版本,老版本不兼容

1、安装后，在设置-模型服务-New api：按下图设置你的密匙、API地址、添加最新模型。
API地址为：https://top.qingyuntop.ai/dashboard/

2、选择code工具

3、选择你需要的编程工具以及模型，点击启动，就可以愉快的编程了

接入检查

• API Key 使用 $QINGYUN_TOP_API_KEY 占位符保存，不要直接粘贴到公开代码或截图。
• OpenAI 兼容客户端通常使用 https://top.qingyuntop.ai/v1；如果客户端要求完整接口路径，再按其界面说明追加路径，避免重复填写 /v1。
• 先用客户端的“测试连接”或发送一条短消息验证，再到控制台调用日志核对模型和状态。

OpenCode（融合自原文档）

按“安装 → 创建专用令牌 → 写入 Provider → 选择模型 → 启动对话”的顺序配置。

第一步：安装并检查 OpenCode

按照 OpenCode 官方安装文档完成安装，然后在终端运行：

opencode --version
opencode debug paths

debug paths 会显示配置、数据、缓存和状态目录。下文修改的是其中的配置目录，不要凭系统类型猜路径。

第二步：创建 OpenCode 专用 API 密钥

1. 登录 青云TOP API 控制台。
2. 打开“令牌管理”，新建一个只供 OpenCode 使用的令牌。
3. 选择需要使用的模型分组。
4. 复制令牌并妥善保存；截图或分享配置时必须保持掩码。

第三步：确认可用模型

使用刚创建的令牌获取模型列表：

export QINGYUN_TOP_API_KEY="你的 青云TOP API API 密钥"

curl "https://top.qingyuntop.ai/v1/models" \
  -H "Authorization: Bearer $QINGYUN_TOP_API_KEY"

从响应中复制一个准确的模型 ID。截图中的模型只用于展示界面，如果你的令牌没有该模型，请使用列表中实际返回的 ID。

第四步：新增 青云TOP API Provider

方法 A：使用 CC Switch

1. 在 CC Switch 顶部选择 OpenCode。
2. 点击“添加供应商”→“自定义配置”。
3. 接口格式选择 OpenAI Compatible。
4. 填入 青云TOP API API 密钥，Base URL 填 https://top.qingyuntop.ai/v1。

CC Switch 中填写 青云TOP API OpenCode Provider；API 密钥在界面中保持掩码

在“模型配置”中添加令牌实际可用的模型 ID。下图使用已通过 青云TOP API 请求验证的 gpt-4o-mini；不要直接照抄一个不在你模型列表中的名称。

在 CC Switch 的 OpenCode Provider 中添加 青云TOP API 模型

点击“添加”，返回 Provider 卡片后再点击“添加”将它写入 OpenCode 配置。按钮变成“移除”且出现“已添加到配置”，才表示当前 Provider 已启用。

青云TOP API Provider 已添加到 OpenCode 配置

方法 B：手工配置并引用环境变量

在 opencode debug paths 显示的配置目录中创建或编辑 opencode.json。如果文件已经存在，只合并 model 和 provider.青云TOP API，不要覆盖其他 Provider、MCP 或权限配置。

{
  "$schema": "https://opencode.ai/config.json",
  "model": "青云TOP API/deepseek-v4-flash-免费",
  "provider": {
    "青云TOP API": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "青云TOP API",
      "options": {
        "baseURL": "https://top.qingyuntop.ai/v1",
        "apiKey": "{env:QINGYUN_TOP_API_KEY}"
      },
      "models": {
        "deepseek-v4-flash-免费": {
          "name": "青云TOP API deepseek-v4-flash-免费"
        }
      }
    }
  }
}

在 Ghostty 中写入 OpenCode 的 青云TOP API Provider；密钥只引用环境变量，不写入配置文件

配置要点：

• baseURL 填 https://top.qingyuntop.ai/v1，不要追加 /chat/completions。
• 亚太地区可使用 https://top.qingyuntop.ai/v1。
• Chat Completions 使用 @ai-sdk/openai-compatible；只有确认模型使用 Responses API 时才改用对应适配器。
• apiKey 引用环境变量，不把真实令牌写入配置文件。
• Provider ID 是 青云TOP API，完整模型名因此是 青云TOP API/模型ID。

第五步：检查 Provider 与模型

保持 QINGYUN_TOP_API_KEY 已导出，依次运行：

opencode debug config
opencode models 青云TOP API

输出中应出现：

青云TOP API
青云TOP API/deepseek-v4-flash-免费

如果模型没有出现，先检查 JSON 结构、Provider ID 和模型 ID，不要反复重装客户端。

第六步：启动 OpenCode 并选择模型

进入要处理的项目目录，再启动 OpenCode：

cd /path/to/your/project
export QINGYUN_TOP_API_KEY="你的 青云TOP API API 密钥"
opencode --model '青云TOP API/deepseek-v4-flash-免费'

进入原生界面后，确认当前模型和 Provider 显示为 青云TOP API deepseek-v4-flash-免费 与 青云TOP API。如果需要切换模型，输入 /models，或按默认快捷键 Ctrl+X 后再按 M。

OpenCode 原生命令面板中打开 /models，下方同时显示当前 青云TOP API 模型

OpenCode 原生 TUI 已显示当前 青云TOP API 模型与 Provider

第七步：发送第一条消息

先在空的临时目录发送一条短消息。确认普通对话成功后，再让 OpenCode 读取真实项目或启用更多工具。 也可以用非交互命令检查同一配置：

opencode run --pure --format json \
  --model '青云TOP API/deepseek-v4-flash-免费' \
  "只回复 OPENCODE_青云TOP API_OK，不要添加其他内容。"

debug config 只确认配置可解析，models 只确认模型已注册。收到正文回复后，再到 青云TOP API 控制台核对对应请求。

常见问题

• 模型列表为空：检查 Provider ID、models 对象、令牌分组和模型 ID。
• 提示 401：确认密钥已导出到启动 OpenCode 的同一个终端进程。
• 提示 404：确认 Base URL 只有一个 /v1，并重新请求 /v1/models 核对模型 ID。
• 请求格式错误：Chat Completions 与 Responses 的适配器不能混用。
• 修改后仍读取旧配置：重新运行 opencode debug paths，确认编辑的是当前进程实际使用的文件。

统一接入检查与故障排查

1. 401/403：确认 API Key 未过期、令牌分组允许目标模型，且没有把示例占位符原样提交。
2. 404：核对应用要求的 Base URL 形式；https://top.qingyuntop.ai/dashboard/、https://top.qingyuntop.ai/v1 和完整路径不能重复拼接。
3. 模型为空或不可用：调用 GET /v1/models，复制返回的完整模型 ID，并确认应用使用的协议（OpenAI Chat Completions、Responses 或 Anthropic Messages）。
4. 切换 Provider 后仍访问旧地址：完全退出并重启客户端，检查环境变量、代理和 CC Switch 路由是否覆盖了新配置。
5. 生产环境安全：不要把真实密钥放进前端代码、截图、公开仓库、Deep Link 或工作流导出文件；先用低额度测试令牌验证。

> 本页保留每个来源教程的具体字段、命令、截图和高级选项；重复的 API Key、Base URL 和验证说明已统一到本页开头与本节。

发布前检查

以下检查适用于客户端中选择 OpenAI 兼容 或 Responses 提供商的场景；如果你选择的是 Anthropic、Gemini 等原生协议，请按对应协议的接口和返回结构配置。

1. 模型 ID：先用目标 API Key 请求 GET https://top.qingyuntop.ai/v1/models，把返回的 data[].id 原样填入客户端。截图、教程和历史配置中的模型名不保证仍可用。
2. 协议选择：新 OpenAI 集成优先选择 Responses；只有客户端或模型明确要求 Chat Completions 时才选择 Chat。Responses 的返回从 output 读取，Chat 的返回从 choices[].message 读取。
3. Base URL：通常填写 https://top.qingyuntop.ai/v1，也就是只保留一个 /v1。要求完整接口地址的客户端才追加 /responses 或 /chat/completions，不要重复追加。
4. 流式与重试：流式响应必须按所选协议解析事件；连接中断后不要盲目重放可能已被服务端接受的生成请求。对 429 和 5xx 使用带抖动的退避，并设置连接、读取和总超时。
5. 上线前验证：分别验证普通文本、流式文本、工具调用或结构化输出中实际用到的能力，并记录 request id、HTTP 状态、业务状态和完成原因，避免只根据 HTTP 200 判定成功。