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

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

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

AionUi（融合自原文档）

AionUi 教程 — 免费开源桌面办公 Agent，支持 Gemini CLI、Claude Code、Codex 等多种 AI 代理。对接 青云 TOP API 实现多模型工作流。

🚀 AionUi 是一款免费、本地、开源的Cowork，支持 Gemini CLI、Claude Code、Codex、OpenCode、Qwen Code、Goose CLI、Auggie 等多种 AI 代理。它提供了完整的 GUI 界面和 WebUI 远程访问功能，是 Cowork 的开源替代方案。

AionUi Logo

核心特性

💬 多会话聊天

  • 多会话 + 独立上下文 - 可同时打开多个聊天会话，每个会话拥有独立的上下文记忆
  • 本地存储 - 所有对话数据保存在本地 SQLite 数据库中，不会丢失

🤖 多模型支持

  • 多平台支持 - 支持 Gemini、OpenAI、Claude、Qwen 等主流模型，灵活切换
  • 本地模型支持 - 支持 Ollama、LM Studio 等本地模型部署

🤝 多代理模式

  • 同时运行多个 AI 代理 - 可同时运行多个 AI 代理（如 Gemini CLI、Claude Code、Codex、OpenCode、Qwen Code、Goose CLI、Auggie 等）
  • MCP 统一管理 - 通过 Model Context Protocol (MCP) 统一管理和配置所有代理，简化操作流程
  • Skills 配置 - 支持为不同代理配置专属的 Skills，扩展代理能力
  • 助手自定义 - 支持自定义助手配置，打造个性化的 AI 工作流
  • 独立配置 - 每个代理可独立配置和使用，互不干扰
  • 灵活切换 - 在不同代理之间灵活切换，满足不同场景需求

🗂️ 文件管理

  • 文件树浏览 + 拖拽上传 - 像文件夹一样浏览文件，支持拖拽文件或文件夹一键导入
  • 智能整理 - 可让 AI 帮助整理文件夹，自动分类

📄 预览面板

  • 9+ 格式预览 - 支持 PDF、Word、Excel、PPT、代码、Markdown、图片等格式
  • 实时跟踪 + 可编辑 - 自动跟踪文件变化，支持实时编辑和调试 Markdown、代码、HTML

🎨 AI 图像生成与编辑

  • 智能图像生成 - 支持 Gemini 2.5 Flash Image Preview、Nano、Banana 等多种图像生成模型
  • 图像识别与编辑 - AI 驱动的图像分析和编辑功能

🌐 多渠道访问

  • WebUI 远程访问 - 可通过浏览器从网络上的任何设备访问，支持移动设备
  • Telegram 集成 - 支持通过 Telegram 机器人进行交互
  • 飞书集成 - 支持通过飞书进行访问和交互
  • 本地数据安全 - 所有数据存储在本地 SQLite 数据库中，适合服务器部署

青云 TOP API 接入方法

参数填写

提供商类型：青云 TOP API 支持的类型
API 密钥：于 青云 TOP API 获取
API 地址：青云 TOP API 站点地址（例如：https://top.qingyuntop.ai/v1）

请使用您自己部署的 青云 TOP API，或确认服务方具备合法上游授权和合规义务的 青云 TOP API 服务。不要将来源不明的 API 地址或密钥接入生产环境。

配置步骤

  1. 在 青云 TOP API 中复制 API key !复制 API 密钥
  1. 打开 AionUi 设置

在 AionUi 中进入设置页面 找到 模型配置 Tab
* 点击"添加模型" !打开设置

  1. 添加新的提供商

点击"添加模型" 选择 青云 TOP API !添加 青云 TOP API 提供商

  1. 配置 API 信息

API 地址：填写您的 青云 TOP API 站点地址（格式：`https://top.qingyuntop.ai/v1`） API 密钥：粘贴从 青云 TOP API 控制台复制的 API Key

  1. 添加模型

下拉选择需要添加的模型 模型名称应与 青云 TOP API 中配置的模型名称一致
* 选择合适的请求协议

  1. 开始使用

返回聊天页面 选择已配置的 青云 TOP API 模型开始对话

相关链接

接入检查

  • API 地址填写青云 TOP API 的 Base URL：https://top.qingyuntop.ai/v1；应用若要求不带 /v1 的站点地址，请按页面说明填写对应格式。
  • API Key 只使用环境变量 $QINGYUN_TOP_API_KEY 或应用的安全密钥存储，不要把真实密钥提交到代码仓库。
  • 模型名称必须与控制台可用模型完全一致；遇到 401/403 检查密钥、分组和模型权限，遇到 404 检查 Base URL 是否重复填写 /v1。

AionUI（融合自原文档）

AionUI 可以在同一个桌面界面中使用内置 Agent、Claude Code 和其他模型工具。本教程按 AionUI 官方的 设置 → 模型 → 添加模型 流程配置 青云TOP API。

1\. 下载并安装 AionUI

从 AionUI 官方下载页 获取与你的系统和 CPU 架构匹配的安装包。

  • Windows
  • macOS
  • Linux
  1. 下载 Windows x64 或 arm64 安装包。
  2. 运行 .exe，按安装向导完成安装。
  3. 从开始菜单启动 AionUI。

下载 Apple Silicon 或 Intel 对应的 .dmg；也可以使用官方 Homebrew Cask：

brew install --cask aionui

下载 amd64 或 arm64 的 .deb，再运行：

sudo dpkg -i AionUi-*-linux-*.deb
sudo apt-get install -f

启动后先确认当前版本的首次运行页。AionUI 2.1.55 的 macOS 原生界面会先让用户选择内置 AionCLI 或已检测到的 Agent；这一步还没有配置 青云TOP API。

AionUI 2.1.55 首次运行与 Agent 选择页面

AionUI 2.1.55 原生首次运行页

2\. 完成 AionUI 自身登录

AionUI 2.1.55 在进入设置前要求登录 AionUI 账号，并提供 Google 登录入口。本教程没有代替用户选择 Google 账号，也没有把 Google 身份传给 AionUI。

AionUI 2.1.55 要求先登录 AionUI 账号

AionUI 设置页之前的账号登录边界

3\. 在 青云TOP API 准备 API 密钥

  1. 登录 青云TOP API 控制台，进入 模型广场。
  2. 找到要使用的模型，记下完整模型 ID 和它所属的分组。
  3. 进入 API 密钥，点击 创建 API 密钥。
  4. 名称填写 AionUI；分组必须能够访问上一步选定的模型。
  5. 保存后立即复制密钥。完整密钥只显示一次，不要放进公开截图。

![青云TOP API 创建 API 密钥窗口和分组选择](https://docs.qingyuntop.ai/images/青云TOP API-api-key-form.png)

在 青云TOP API 创建 AionUI 专用密钥，并选择包含目标模型的分组

4\. 打开模型配置

  1. 启动 AionUI。
  2. 点击左侧 设置。
  3. 打开 模型（部分版本显示“LLM 配置”）。
  4. 点击 添加模型。

5\. 选择平台

当前版本优先选择 New API。如果旧版本中没有该项，选择 自定义（Custom），按 OpenAI-compatible 方式配置。

6\. 填写 青云TOP API 参数

  • New API（推荐）
  • 自定义 OpenAI
名称：    青云TOP API
Base URL: https://top.qingyuntop.ai/dashboard/
API Key:  sk-••••••••••••
模型：    从模型广场复制的完整模型 ID

亚太线路使用 https://top.qingyuntop.ai/dashboard/。

名称：    青云TOP API
Base URL: https://top.qingyuntop.ai/v1
API Key:  sk-••••••••••••
模型：    从模型广场复制的完整模型 ID

亚太线路使用 https://top.qingyuntop.ai/v1。

7\. 添加模型并设置协议

  1. 点击模型输入框旁的刷新或添加按钮。
  2. 选择第 3 步记录的准确模型 ID。
  3. 使用 New API 时，按模型能力选择协议：OpenAI-compatible 选 OpenAI，Claude 原生消息选 Anthropic，Gemini 原生接口选 Gemini。
  4. 仅启用模型实际支持的函数调用、视觉输入或图片生成能力。
  5. 点击 保存。

8\. 选择模型并开始使用

  1. 返回主界面并新建对话。
  2. 点击输入框附近的模型选择器。
  3. 选择 青云TOP API 下刚保存的模型。
  4. 输入一条简短消息并发送。

能够看到模型只说明配置已保存；收到正常回复才说明模型调用成功。

常见问题

  • 模型列表为空：检查密钥分组是否包含目标模型，再核对 Base URL。
  • 401：密钥错误、过期或已禁用。
  • 404：通常是 Custom 漏写 /v1，或 New API 重复写了 /v1。
  • Claude/Gemini 协议错误：在 New API 模型配置中选择正确的协议覆盖。
  • 已保存但对话中看不到模型：确认模型已启用，并核对能力选项。

官方资料

统一接入检查与故障排查

  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 判定成功。