本页将青云 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 的开源替代方案。

核心特性

💬 多会话聊天

  • 多会话 + 独立上下文 - 可同时打开多个聊天会话，每个会话拥有独立的上下文记忆
  • 本地存储 - 所有对话数据保存在本地 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 原生首次运行页

2\. 完成 AionUI 自身登录

AionUI 2.1.55 在进入设置前要求登录 AionUI 账号，并提供 Google 登录入口。本教程没有代替用户选择 Google 账号，也没有把 Google 身份传给 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
API Key:  sk-••••••••••••
模型：    从模型广场复制的完整模型 ID

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

名称：    青云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、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 和验证说明已统一到本页开头与本节。