OpenCode | 青云TOP API 文档

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

第一步：安装并检查 OpenCode

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

opencode --version
opencode debug paths

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

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

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

第三步：确认可用模型

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

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

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

CC Switch OpenCode 分支中的青云TOP API Provider 配置

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

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

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

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

CC Switch 已启用青云TOP API 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 配置

在 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，确认编辑的是当前进程实际使用的文件。

发布前检查

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

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