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 模型配置中选择正确的协议覆盖。
  • 已保存但对话中看不到模型：确认模型已启用，并核对能力选项。

官方资料

发布前检查

以下检查适用于客户端中选择 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 判定成功。