本页将青云 TOP API 客户端接入资料按使用场景合并整理，适合第一次接入的用户，也适合需要核对协议和路径的 API 开发者。青云 TOP API 基于 New API 部署，因此 New API 官方应用教程中的兼容配置可以直接复用。
快速判断：我应该看哪一段？
- 只想聊天：先看桌面端的基础配置。
- 要接入 MCP、知识库或工作流：看 Agent/自动化章节。
- 要在终端写代码：看 CLI、Provider 和环境变量章节。
- 遇到 401、403、404 或模型不兼容：先检查本文末尾的接入检查清单，再查看对应来源章节。
LangBot（融合自原文档）
LangBot 对接教程 — 面向飞书、钉钉、Telegram、Discord 等平台的 AI 聊天机器人开发框架。支持知识库、Agent、MCP，兼容 青云 TOP API。
LangBot 是一个开源的即时通信机器人开发平台，支持多种即时通信平台，如飞书、钉钉、微信、QQ、Telegram、Discord、Slack 等。接入全球主流的 AI 模型，支持知识库、Agent、MCP等多种 AI 应用能力，并完美适配 青云 TOP API。
- 官网地址：https://langbot.app
- 下载地址：https://github.com/langbot-app/LangBot/releases
- 官方文档：https://docs.langbot.app
- 开源地址：https://github.com/langbot-app/LangBot
接入 青云 TOP API
LangBot 支持接入本地部署的 青云 TOP API 和第三方使用 青云 TOP API 搭建的 青云 TOP API 服务。
使用方式
- 从 青云 TOP API 中获取 API key !获取 API key
若是本地部署的 青云 TOP API 请自行配置 API 地址（可参考容器网络连接），若使用第三方 青云 TOP API 服务，可在页面上复制地址。注意，地址后需要添加/v1。
- 在 LangBot 中添加模型，选择使用 青云 TOP API 供应商，填写对应的 API key 和 API 地址 !添加 青云 TOP API 模型
- 在流水线中选择使用模型
!选择模型
- 在对话调试中对话或与绑定至流水线的机器人对话即可使用
!对话
!微信对话
部署配置机器人请参考部署机器人。
使用 LangBot 知识库
LangBot 支持使用 青云 TOP API 的嵌入模型，并将其作为知识库的向量模型。
- 在 LangBot 中添加嵌入模型，选择使用 青云 TOP API 供应商 !添加嵌入模型
- 在新建知识库时选用嵌入模型 !使用嵌入模型
更多使用方式请查看 LangBot 官方文档：https://docs.langbot.app
接入检查
- API 地址填写青云 TOP API 的 Base URL：
https://top.qingyuntop.ai/v1；应用若要求不带/v1的站点地址，请按页面说明填写对应格式。 - API Key 只使用环境变量
$QINGYUN_TOP_API_KEY或应用的安全密钥存储，不要把真实密钥提交到代码仓库。 - 模型名称必须与控制台可用模型完全一致；遇到 401/403 检查密钥、分组和模型权限，遇到 404 检查 Base URL 是否重复填写
/v1。
LangBot 配置（融合自原文档）
LangBot 是一个开源的即时通信机器人开发平台，支持多种即时通信平台，如飞书、钉钉、微信、QQ、Telegram、Discord、Slack 等。接入全球主流的 AI 模型，支持知识库、Agent、MCP等多种 AI 应用能力，并完美适配 NewAPI。
官网地址：https://langbot.app/
下载地址：https://github.com/langbot-app/LangBot/releases
官方文档：https://docs.langbot.app/
开源地址：https://github.com/langbot-app/LangBot
使用 LangBot 对话
1、从 NewAPI 中获取 API key
2、在 LangBot 中添加模型，选择使用 NewAPI 供应商，填写对应的 API key 和 API 地址，如下图：
请求URL https://top.qingyuntop.ai/v1
3、在流水线中选择使用模型
4、在对话调试中对话或与绑定至流水线的机器人对话即可使用
部署配置机器人请参考部署机器人。
使用 LangBot 知识库
LangBot 支持使用 NewAPI 的嵌入模型，并将其作为知识库的向量模型。
1、在 LangBot 中添加嵌入模型，选择使用 NewAPI 供应商
2、在新建知识库时选用嵌入模型
更多使用方式请查看 LangBot 官方文档：https://docs.langbot.app/
接入检查
- API Key 使用
$QINGYUN_TOP_API_KEY占位符保存，不要直接粘贴到公开代码或截图。 - OpenAI 兼容客户端通常使用
https://top.qingyuntop.ai/v1；如果客户端要求完整接口路径，再按其界面说明追加路径，避免重复填写/v1。 - 先用客户端的“测试连接”或发送一条短消息验证，再到控制台调用日志核对模型和状态。
统一接入检查与故障排查
- 401/403：确认 API Key 未过期、令牌分组允许目标模型，且没有把示例占位符原样提交。
- 404：核对应用要求的 Base URL 形式；
https://top.qingyuntop.ai/dashboard/、https://top.qingyuntop.ai/v1和完整路径不能重复拼接。 - 模型为空或不可用：调用
GET /v1/models，复制返回的完整模型 ID，并确认应用使用的协议（OpenAI Chat Completions、Responses 或 Anthropic Messages）。 - 切换 Provider 后仍访问旧地址：完全退出并重启客户端，检查环境变量、代理和 CC Switch 路由是否覆盖了新配置。
- 生产环境安全：不要把真实密钥放进前端代码、截图、公开仓库、Deep Link 或工作流导出文件；先用低额度测试令牌验证。
> 本页保留每个来源教程的具体字段、命令、截图和高级选项；重复的 API Key、Base URL 和验证说明已统一到本页开头与本节。
发布前检查
以下检查适用于客户端中选择 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 判定成功。