本页参考 New API 官方 AI 应用文档，已按青云 TOP API（New API 兼容）环境整理。API 地址使用 https://top.qingyuntop.ai/v1，API Key 使用 $QINGYUN_TOP_API_KEY 占位符，请在青云 TOP API 控制台创建并妥善保存密钥。

AstrBot 配置教程 — 将开源 Agent 聊天机器人平台对接 青云 TOP API，为 QQ、飞书、钉钉、企业微信等即时通讯注入 AI 能力。

AstrBot 是一个开源的一站式 Agent 聊天机器人平台，可将大模型能力无缝接入 QQ、飞书、钉钉、企业微信等主流即时通讯软件，为个人、开发者和团队打造可靠、可扩展的对话式智能基础设施。无论是个人 AI 伙伴、智能客服、自动化助手，还是企业知识库，AstrBot 都能在你的即时通讯软件平台的工作流中快速构建生产可用的 AI 应用。

青云 TOP API 接入方法

AstrBot 支持接入 青云 TOP API 作为模型提供商，用户可以通过 青云 TOP API 来访问和使用各种 AI 模型服务。

配置步骤

获取 青云 TOP API API Key 密钥

在 青云 TOP API 注册并登录后，点击上方导航栏的「控制台」，点击「令牌管理」，然后点击「添加令牌」按钮，创建一个新的 API Key 密钥，选择适当的权限，然后点击「创建」。

create-api-key

创建成功后，点击复制密钥按钮，复制生成的 API Key 密钥。

copy-api-key

在 AstrBot 中配置 青云 TOP API 服务提供商

打开 AstrBot 管理面板，进入「模型提供商」页面，然后，点击「新增模型提供商」按钮。

青云 TOP API 完美地支持了 OpenAI Chat Completion 和 Responses 接口，我们点击 「OpenAI」，进入 OpenAI 提供商的配置页面。

在弹出的对话框中，将 API Base URL 设置为 青云 TOP API 的接口地址。请使用您自己部署的 青云 TOP API，或确认服务方具备合法上游授权和合规义务的 青云 TOP API 服务。如果您本地部署了 青云 TOP API，则填写本地地址，例如 https://top.qingyuntop.ai/v1。不要将来源不明的 API 地址或密钥接入生产环境。

然后，将 API Key 填入「API Key」字段中，点击「保存」按钮。

astrbot-provider-config

然后点击保存，完成 青云 TOP API 提供商的配置。

应用服务提供商

进入「配置文件」页面，找到模型一节，将「默认聊天模型」修改为刚刚创建的 青云 TOP API 提供商，点击「保存」按钮。

apply

至此，您已经成功配置了 青云 TOP API 作为 AstrBot 的模型提供商。现在，您可以通过 AstrBot 来访问和使用 青云 TOP API 提供的各种 AI 模型服务了。

接入检查

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

发布前检查

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