平台接入操作指南

在 KEDA 的「机器人工作室 → 选择机器人 → 平台接入」添加连接。本页按官方后台的实际操作说明如何创建平台机器人、取得凭据、保存连接和测试。官方入口与 API 文档核对日期：2026 年 10 月 23 日；平台可能调整菜单名称，请以链接中的官方页面为准。

开始之前

1. 在 KEDA 创建机器人，选择可用模型，填写提示词和预算，保存配置并完成 AI 审查。可以先保存平台连接；接收真实平台消息需要机器人已经发布、连接已经启用，托管服务可用。
2. 准备账户余额。平台消息触发的模型、工具和数据库操作沿用机器人预算与实际计费规则。
3. 选择使用范围。KEDA 默认仅允许名单内的用户；填写「允许的用户 ID」，多个 ID 用逗号分隔。也可以主动勾选「允许所有用户使用」。这会开放给平台上能访问该机器人的用户，相关调用使用你的余额和预算；平台自身的使用权限仍然生效。
4. QQ 默认填写 AppID、AppSecret，Discord 默认填写 Bot Token。KEDA 负责维持连接和重连。下面的高级 HTTP 模式供已有回调集成使用。
5. Token、AppSecret 和 Webhook 签名密钥只填入对应凭据栏，避免发进聊天或放进截图。KEDA 加密保存平台凭据，保存后不回显；更换凭据时移除旧连接，再使用新凭据添加。

QQ

官方入口：QQ 快速创建页 · QQ 机器人官方接入指南 · 接口鉴权 · 事件通知与 WebSocket。

在 QQ 官方页面操作

1. 打开 QQ 快速创建页，使用自己的 QQ 账户登录。
2. 在「我的机器人」区域点击「创建机器人」，按页面要求完成创建；已有机器人可直接使用。
3. 找到目标机器人卡片，复制 AppID；在 AppSecret 一栏点击「查看」后复制密钥。两项必须来自同一个机器人。
4. 可以在机器人卡片使用「扫码聊天」，用手机 QQ 打开与该机器人的会话。需要群聊时，使用最新版 QQ，由群主按 QQ 的机器人入口添加已创建的机器人，并核对群内权限。

在 KEDA 连接并测试

1. 进入该 KEDA 机器人的「平台接入」，点击「添加平台」，选择 QQ。
2. 将官方页面的 AppID 填入「应用 ID（AppID）」，AppSecret 填入「应用密钥（AppSecret）」。QQ 默认使用「长连接（推荐）」，无需配置回调地址。
3. 设置使用范围。私有名单填写 QQ 事件中的 user_openid 或 member_openid，它们与日常 QQ 号码不同。若没有 openid，可先核对 QQ 端可访问范围，再自行决定是否允许所有用户使用；KEDA 不会自动开放访问。
4. 点击「保存连接」。机器人通过审查后点击「发布」，并保持连接卡片上的开关开启。
5. 等待状态显示 「QQ 已连接」，然后在刚打开的 QQ 会话发送「你好」；群聊中发送「@机器人 你好」。在 KEDA「运行记录」检查是否产生运行、是否完成和是否发送。

QQ 页面没有回调地址设置

QQ 快速创建页面提供 AppID 和 AppSecret，适用默认长连接。保存并发布后，由 KEDA 获取 AccessToken、连接官方 WebSocket 并处理心跳与重连，无需寻找或填写回调地址。

若维护已有的传统 HTTP 事件集成，可展开 KEDA「高级设置（选填）」并选择「HTTP 回调」。只有 QQ 后台确实提供 HTTP 事件回调配置时，才把连接卡片显示的地址填入该应用的回调配置，并完成官方验证和消息事件订阅。快速创建页没有此配置时，保持默认方式。

QQ 常见问题

• 「灵魂不在线」或连接中： 确认 KEDA 机器人已发布、连接开关已启用，等状态变成「QQ 已连接」。检查 AppID 和 AppSecret 是否属于同一个机器人。
• 凭据无效： 从 QQ 官方页面重新复制当前密钥；如果重置过 AppSecret，用新密钥重新创建 KEDA 连接。
• 该 QQ 应用已由其他连接使用： 同一个 AppID 在本站只使用一个启用的长连接。停用重复连接；外部托管服务也应核对是否重复使用同一个机器人。
• 在线但没有回复： 先用单聊或明确的群聊 @ 测试；核对 QQ 的使用权限和 KEDA 访问名单。QQ 号不能作为 openid 使用。再查看运行记录中的余额、预算、审查或发送错误。

Discord

官方入口：Discord Developer Portal · 官方创建与安装步骤 · Gateway 与消息权限 · 机器人授权 · 获取当前应用。

在 Discord 官方后台操作

1. 登录 Developer Portal，点击 New Application，输入应用名称并创建；已有应用直接打开。
2. 在左侧打开 Bot。在 Token 区域获取 Bot Token；首次生成或遗失时使用 Reset Token，按 Discord 要求完成确认。重置会使旧 Token 失效，原来使用该 Token 的服务需要更新。
3. 在左侧打开 Installation，确认 Installation Contexts 支持 Guild Install，以便将机器人添加到服务器。你需要拥有目标服务器的管理权限，或请有权限的人完成安装。
4. 先保持 Message Content Intent 的默认设置即可。普通的频道 @ 和私聊是 KEDA 默认使用方式。

在 KEDA 连接并测试

1. 「平台接入 → 添加平台 → Discord」，只填写 Bot Token。KEDA 调用官方 GET /applications/@me 验证 Token 并自动识别应用 ID。
2. 设置使用范围。私有名单使用 Discord 用户 ID；在 Discord「用户设置 → Advanced／高级 → Developer Mode／开发者模式」启用后，右键目标用户或打开其更多菜单，选择 Copy User ID／复制用户 ID。不要填写用户名或昵称。
3. 点击「保存连接」，再点击连接卡片上的 「添加到 Discord 服务器」。在 Discord 官方授权页面选择目标服务器并确认。按钮使用官方机器人授权流程，无需设置 OAuth 回调地址。
4. 安装链接请求查看频道、发送消息和读取消息历史的权限；核对目标频道的权限覆盖规则，确保机器人能够查看并回复。首次测试建议选择普通文字频道。
5. 通过审查后发布 KEDA 机器人，等待状态显示 「Discord 已连接」，在服务器发送「@机器人 你好」，或打开与机器人的私聊发送消息。
6. 在 KEDA「运行记录」确认已收到消息并完成发送。若服务器限制成员私聊，可先使用频道 @ 测试。

读取未 @ 的普通频道消息（选用）

如果你需要机器人按关键词或语境自主参与普通频道对话，在 Discord Developer Portal 的 Bot → Privileged Gateway Intents 开启 Message Content Intent 并保存；再在 KEDA 添加连接时展开「高级设置（选填）」，勾选已启用此权限。在机器人设置中选择对应的参与对话方式。达到 Discord 验证或审核条件的应用还需满足官方审批要求。

仅勾选 KEDA 复选框不会替你开通 Discord 权限。无需读取普通频道内容时，保持此选项关闭；私聊和明确 @ 的消息可以先按默认流程验证。

已有 /ask HTTP 指令应用（高级）

展开「高级设置（选填）」，把「Discord 接入方式」设为「HTTP 指令回调（已有 /ask 应用）」。此时填写 Application ID 和 Public Key，它们来自 Developer Portal 的 General Information 页面。保存后将 KEDA 显示的地址填入应用的 Interactions Endpoint URL 并保存验证。

该模式还需要使用 Discord 官方应用命令 API 注册 /ask，带一个 string 类型的 message 参数，并把应用命令授权到目标服务器。KEDA 不会在此模式自动注册 /ask。它只处理 HTTP 指令交互；若你要使用默认聊天接入，使用 Bot Token 创建默认连接。

参考：官方应用命令 API及交互接收与签名验证。

Discord 常见问题

• Bot Token 无效： 确认粘贴的是 Bot 页面 Token；Token 重置后移除旧连接并用新 Token 添加。应用 ID、Public Key 和 Client Secret 不能替代 Bot Token。
• 服务器不在授权列表： 核对当前 Discord 账号是否拥有管理该服务器的权限，应用是否支持 Guild Install。私有机器人还需由应用所有者按 Discord 规则安装。
• 已连接但收不到普通消息： 先明确 @ 机器人测试。要读取未 @ 的消息，再核对官方 Message Content Intent 与 KEDA 的高级选项。
• 能接收但发不出回复： 核对频道中的查看、发送和消息历史权限及覆盖规则；线程需要单独的在线程发送消息权限，首次测试可先换到普通文字频道。
• Intent 权限错误或重复 Token： 按状态提示修正官方权限，或停用重复的 KEDA 连接；不要用相同 Token 重复创建多个活跃连接。

Telegram

官方入口：@BotFather · 官方机器人创建与管理 · Privacy Mode 与群聊说明。

在 Telegram 官方客户端操作

1. 打开官方 @BotFather，核对账号后发送 /newbot，按提示填写显示名称和机器人用户名，用户名需要满足 BotFather 的规则。
2. 创建成功后复制 BotFather 返回的 Bot Token。已有机器人可在 /mybots 选择机器人并管理 API Token；Token 被重置后需要同步更新 KEDA 连接。
3. 打开创建好的机器人聊天，点击 Start 或发送 /start。要在群聊使用时，将机器人添加到目标群。

在 KEDA 连接并测试

1. 「平台接入 → 添加平台 → Telegram」，填写 Bot Token，并设置允许的用户 ID 或主动开放使用范围。私有访问名单使用 Telegram 用户的数字 ID。
2. 保存连接，通过审查后发布机器人。
3. 在 Telegram 连接卡片点击 「注册 Telegram 回调」。KEDA 自动向 Telegram 登记站点地址，无需你手动到 Telegram 后台粘贴 URL。
4. 在机器人私聊发送「你好」，再到 KEDA「运行记录」确认结果。群聊可先通过 @ 或回复机器人来测试。
5. 如果确实要读取普通群聊消息，在 BotFather 使用 /setprivacy 按官方流程调整 Privacy Mode，并核对群内权限；按 Telegram 要求重新添加机器人后再测试。在 KEDA 同时选择适当的参与对话方式。

Telegram 常见问题

• 注册失败： 检查当前 Bot Token 和 KEDA 站点可用性；若提示公开站点地址未配置，需要管理员配置。再次点击注册可重新登记。
• 私聊正常、群聊无回复： 先用 @ 或回复测试，核对群成员权限与 Privacy Mode；KEDA 默认不会对所有普通群消息发言。
• 其他程序不再收到消息： 同一个 Telegram 机器人应交给同一个接收服务；Webhook 与 getUpdates 轮询不能同时使用。核对是否有其他程序接管了它。
• 不知道自己的用户 ID： 用户名和机器人 ID 都不能替代用户数字 ID。可从自己已有的官方 Bot API 更新数据取得；不要把 Token 发给第三方查询服务。若暂未取得，先明确设置所需访问范围再测试。

Webhook

此方式面向你自己的服务端程序，无需第三方机器人后台。

1. 「平台接入 → 添加平台 → Webhook」，设置使用范围，保存连接。
2. 立即保存弹窗中只显示一次的签名密钥，以及回调地址。密钥仅供调用方服务端保存；遗失时移除连接并重新创建。
3. 发布 KEDA 机器人。服务端准备唯一 event_id、sender、conversation 与 message，用实际发送的 JSON 字节计算 HMAC-SHA256。
4. 请求头包含 X-Bot-Timestamp（Unix 秒）与 X-Bot-Signature，签名输入为 timestamp + "." + body。服务器需同步时间；允许过去 5 分钟至未来 30 秒的时间戳。
5. 接口返回 run_id 后，使用同一连接的密钥对 /results 查询签名。每次查询重新生成时间戳和签名，查看 state、output 和 cost_cny。

import { createHmac, randomUUID } from 'node:crypto'

const endpoint = process.env.KEDA_BOT_WEBHOOK_URL
const secret = process.env.KEDA_BOT_WEBHOOK_SECRET
async function signedPost(url, value) {
  const body = JSON.stringify(value)
  const timestamp = String(Math.floor(Date.now() / 1000))
  const signature = createHmac('sha256', secret)
    .update(timestamp + '.' + body)
    .digest('hex')
  const response = await fetch(url, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Bot-Timestamp': timestamp,
      'X-Bot-Signature': signature,
    },
    body,
  })
  if (!response.ok) throw new Error(`Webhook HTTP ${response.status}`)
  return (await response.json()).data
}
const run = await signedPost(endpoint, {
  event_id: randomUUID(),
  sender: 'alice',
  conversation: 'private',
  message: '你好',
})
const result = await signedPost(endpoint + '/results', { run_id: run.run_id })
console.log(result.state, result.output, result.cost_cny)

sender 使用 1–120 位字母、数字、下划线或短横线。私有名单中的 ID 需要与 sender 相符。相同事件重试保持 event_id、发送者、会话和消息一致；不要生成新编号来重放同一事件。queued 或 running 时可稍后按自己的调度继续查询；终态以实际返回为准。

常见问题

已保存，为什么还没有回复？

保存连接只保存凭据和访问范围。依次确认：机器人已发布、连接开关已开启、平台状态正常、发送者在允许范围内、预算和余额可用。修改机器人提示词、代码或授权配置后，按界面提示重新保存并审查、发布。

先在 KEDA「试运行」验证机器人，然后去平台发送一条明确的私聊或 @ 消息。如果「运行记录」没有新记录，优先检查平台连接、事件类型和访问范围；已有记录但失败时，按该记录的错误提示处理。

发布后一直显示连接中怎么办？

状态会自动刷新。核对官方平台当前凭据，重复应用／Token，应用权限和托管服务可用性。遇到平台网络或限流问题时稍后重试；不要连续创建重复连接。持续异常时向工单提供平台名称、机器人名称、发生时间及不含凭据的状态截图。

HTTP 高级模式和默认连接怎么选？

首次接入 QQ 或 Discord 时，保持默认连接即可。高级 HTTP 模式适合已经使用官方事件回调或 /ask 指令的集成；文档中的回调操作只属于所选 HTTP 模式。Telegram 通过连接卡片自动注册回调，Webhook 由你自己的服务端签名调用。