Kirara AI

Appearance

连接聊天平台 ​

Kirara AI 支持连接多种聊天平台，通过适配器机制实现跨平台的消息处理。本文将指导您完成平台连接的配置。

image

适配器：平台连接的桥梁 ​

适配器是 Kirara AI 与外部平台之间的连接桥梁，主要功能包括：

  • 处理不同平台的消息协议
  • 转换消息格式为统一结构
  • 管理平台特有的认证机制

配置入口 ​

通过 WebUI 左侧导航栏按路径操作：
聊天平台管理 → 选择连接方式 → 添加配置

配置步骤 ​

一、选择适配器类型 ​

Kirara AI 提供以下适配器：

  • 内置适配器：HTTP API、 QQ 开放平台机器人、 Telegram 机器人、企业微信应用等主流平台
  • 插件适配器：通过插件市场扩展的平台支持

▸ 提示：若目标平台未列出，需先安装对应插件

二、添加配置 ​

每个配置都需要有一个名称，名称的命名规范为：

  • 格式：[平台]_[用途]（示例：telegram_cs_bot）
  • 字符限制：小写字母/数字/下划线
  • 全局唯一性：不可与现有配置重名

三、填写平台相关信息 ​

不同的平台连接机器人的方式都不一样，下面介绍了几个内置适配器的配置填写方式。

TIP

对于插件提供的适配器，可以参考插件的文档来了解如何填写配置。

内置适配器配置指南 ​

平台关键参数获取位置
Telegram 机器人Bot Token@BotFather 创建机器人时获取
HTTP API 服务API Key自定义
企业微信应用CorpID + Secret + AgentID 等参数企业微信管理后台 应用详情页
微信公众号Secret + AgentID 等参数微信公众号管理后台 应用详情页
QQ 开放平台机器人AppID + AppKey + Token 等参数QQ 开放平台 应用详情页

Telegram 机器人 ​

▸ 必须参数：

  • Token：格式为 数字:字母组合，从 @BotFather 获取

TIP

如果机器人以普通成员身份加入群组，则需要开启 Privacy Mode 才接收普通消息。

QQ 开放平台机器人 ​

▸ 必须参数：

  • AppID：QQ 开放平台的 AppID
  • AppKey：QQ 开放平台的 AppKey
  • Token：QQ 开放平台的 Token

▸ 参数获取路径：

  1. 参考 平台入驻文档 注册账号，并创建一个机器人。
  2. 参考 开发基础设置，可以获取到 AppID、App Secret、Token 参数，分别对应 Kirara AI 的同名配置。
  3. 勾选 Sandbox，保存 Kirara AI 中的配置，如果信息填写正确，此时你可以看见 WebUI 中展示出机器人的头像和昵称。
  4. 在 QQ 开放平台中，点击「回调配置」，填写 请求地址，这个参数是 Kirara AI 的 公网 WebUI HTTP 地址 + 机器人回调地址，并点确定配置。

QQ Callback

TIP

关于什么是 Kirara AI 的 公网 WebUI HTTP 地址，可以参考下方的 「如何填写回调地址」小节。

  1. 在「添加事件」中，勾选单聊、群聊中的所有事件，你应该会勾选 11 个事件。

  2. 参考 平台入驻文档，完成沙箱环境的配置，即可和机器人进行对话。

TIP

尽管文档中提到个人开发者暂不开放 QQ 群和单聊能力，但是在沙箱模式下你仍然可以使用这些功能和机器人进行对话。

HTTP API 服务 ​

通过 HTTP 协议将 Kirara AI 的能力开放给其他系统，使外部程序可以通过 API 调用获得 AI 服务。

▸ 配置参数：

  • API Key：API 调用密钥，可选项。

API Key 填写后，只有请求头携带了 Authorization: Bearer ${API Key} 字段的请求才会被处理。 若不填写，则所有请求都会被处理。

当任意一个 HTTP API 服务被配置后， Kirara AI 的 HTTP API 接口才会被启用。

你可以在HTTP API 接口文档 查看详细的 API 接口文档。

企业微信应用 ​

▸ 参数获取路径：

  1. 登录 企业微信管理后台
  2. 点击顶部的 「我的企业」→「企业信息」，获取 企业ID 参数，这里的值对应 Kirara AI 的 企业ID。 WeCom CorpID
  3. 从顶部导航栏进入「应用管理」→「应用」→「自建」→「创建应用」 WeCom Create App
  4. 应用 Logo、名称、介绍 可随意填写，「可见范围」按照实际情况选择。
  5. 在应用详情页，可以获取到 AgentID、Secret 参数，分别对应 Kirara AI 的 应用ID、应用Secret。
  6. 点击下方的 「接收消息」→ 「设置API接收」 按钮，将 URL 设置为 Kirara AI 的 公网 WebUI HTTP 地址 + 微信端回调地址。

TIP

关于什么是 Kirara AI 的 公网 WebUI HTTP 地址，可以参考下方的 「如何填写回调地址」小节。

Token 和 EncodingAESKey 则点击「随机获取」，然后把获取到的参数填写到 Kirara AI 的配置中。
此处的配置是为了让 Kirara AI 能够从微信服务器接收消息。 WeCom API Settings 6. 接下来，先在 Kirara AI 中保存配置，然后再保存企业微信端的配置，否则会出现 「openai回调请求不通过」的错误。 7. 返回上一个页面，点击下方的 「企业可信IP」，填写 Kirara AI 的 IP 地址，点击「确定」。
此处的配置是为了让 Kirara AI 能够正常地回复消息。 WeCom Trusted IP 8. 最后，在企业微信App中，你就可以看见新创建的应用，并发送消息了。

▸ 常见问题

  1. 「openai回调请求不通过」
    • 原因：Kirara AI 的配置未保存，或者配置出现错误。
    • 解决：检查 Kirara AI 的输出日志。
  2. 可以收到消息，但是无法回复。
    • 原因：Kirara AI 的 IP 地址未添加到企业微信的「可信IP」列表中。
    • 解决： 检查 Kirara AI 的输出日志，看是否有下面类似的日志：
    | ERROR    | Wecom-Adapter | Failed to send text message: Error code: 60020, message: not allow to access from your ip, hint: [****], from ip: *.*.*.*, more info at https://open.work.weixin.qq.com/devtool/query?e=60020
    这里 from ip 就是 Kirara AI 的 IP 地址，将这个 IP 地址添加到企业微信的「可信IP」列表中即可。

如何填写回调地址 ​

在配置机器人时，你可能会看到类似下面的提示：

example webhook hint

什么是回调地址？

简单来说，回调地址就像一个“收信地址”。你需要告诉机器人平台（例如 QQ、微信），当收到消息时，应该发往哪个地址，Kirara AI 才能接收和处理这些消息。

地址类型：公网地址 vs 内网地址

填写回调地址时，你需要根据你的 Kirara AI 的使用场景，选择 公网地址 或 内网地址。

  • 公网地址：

    • 定义：公网地址是可以被互联网上的任何设备访问的地址。
    • 适用场景：主要用于连接 QQ开放平台、微信公众平台、企业微信 等外部平台。
    • 如何判断：
      • 云服务器：如果你使用云服务器部署 Kirara AI，服务商通常会为你分配一个公网 IP 地址。
      • 域名：如果你拥有一个域名，并且已经将其解析到你的服务器，那么这个域名也指向公网地址。
      • 简单测试：在浏览器中输入你的公网 IP 地址或域名，如果能够正常打开 Kirara AI 的 WebUI 界面，那么这就是公网地址。
    • 示例：假设你的云服务器 IP 地址是 123.45.67.89，Kirara AI WebUI 的端口是 8080，那么公网地址就是 http://123.45.67.89:8080。

    TIP

    国内云服务器备案： 如果你使用中国大陆地区的云服务器，根据中国法律法规，可能需要进行网站备案才能对外提供 HTTP 服务。请确保你的服务器已完成备案。

  • 内网地址：

    • 定义：内网地址仅能在同一局域网内的设备访问，例如家庭网络、公司内部网络等。
    • 适用场景：主要用于连接自建程序，或者仅在局域网内部使用 Kirara AI 的场景。
    • 如何判断：
      • 常见内网地址：常见的内网地址通常以 127.0.0.1、localhost 或者 192.168.x.x、10.x.x.x、172.16.x.x 开头。
      • 简单测试：在你的电脑浏览器中输入 http://127.0.0.1:8080 可以访问，但在其他网络环境下无法访问，那么这就是内网地址。
    • 示例：如果你在本地电脑部署 Kirara AI，并且 WebUI 监听的端口是 8080，那么内网地址通常是 http://127.0.0.1:8080。

常见场景和填写方法

  • 场景一：云服务器 + QQ开放平台/微信公众平台等外部平台

    • 地址类型：公网地址
    • 填写方法：
      1. 登录你的云服务器管理控制台，获取你的云服务器的公网 IP 地址。
      2. 确认你的 Kirara AI WebUI 监听的端口号（默认 8080），并且监听的地址是 0.0.0.0。
      3. 将以下格式中的 <你的公网IP地址> 和 <端口号> 替换为你获取到的信息：http://<你的公网IP地址>:<端口号>/im/webhook/xxxx
      4. 将完整的地址填写到机器人平台的回调地址设置中。

  • 场景二：家用电脑 + QQ开放平台/微信公众平台等外部平台

    • 问题：家用宽带通常没有公网 IP 地址，或者公网 IP 地址会动态变化。
    • 解决方案：
      1. 端口穿透：使用端口穿透工具（例如 frp）。Kirara AI WebUI 设置页面集成了 frp 客户端，你可以尝试使用它进行内网穿透。
      2. 云服务器：如果端口穿透设置较为复杂，或者你需要更稳定的服务，可以考虑将 Kirara AI 部署到云服务器上。
    • 填写方法（以端口穿透为例）：
      1. 配置并启动端口穿透工具，获取端口穿透服务提供的公网地址（通常是一个域名或 IP 地址 + 端口号）。
      2. 将以下格式中的 <端口穿透公网地址> 和 <端口号> 替换为你获取到的信息：http://<端口穿透公网地址>:<端口号>/im/webhook/xxxx
      3. 将完整的地址填写到机器人平台的回调地址设置中。

  • 场景三：Docker 部署

    • Docker 网络：如果你使用 Docker 部署 Kirara AI，需要注意 Docker 的网络模式。
    • 桥接模式：如果使用桥接模式，你需要使用宿主机的 IP 地址 和端口映射。
    • Host 模式：如果使用 Host 模式，你可以直接使用宿主机的 IP 地址。
    • 填写方法：
      1. 确定你的 Docker 网络模式。
      2. 获取宿主机的 内网 IP 地址 或 公网 IP 地址（如果需要公网访问）。
      3. 确认你是否进行了端口映射，以及映射的端口号。
      4. 将以下格式中的 <宿主机IP地址> 和 <映射端口号> 替换为你获取到的信息：http://<宿主机IP地址>:<映射端口号>/im/webhook/xxxx
      5. 将完整的地址填写到机器人平台的回调地址设置中。

  • 场景四：连接自建程序

    • 地址类型：内网地址
    • 填写方法：
      1. 确保你的自建程序和 Kirara AI 运行在同一个网络环境下。
      2. 获取运行 Kirara AI 的电脑的 内网 IP 地址。
      3. 确认你的 Kirara AI WebUI 监听的端口号（默认 8080）。
      4. 将以下格式中的 <内网IP地址> 和 <端口号> 替换为你获取到的信息：http://<内网IP地址>:<端口号>/im/webhook/xxxx
      5. 将完整的地址填写到你的自建程序的回调地址设置中。

快速判断

  1. 是否需要连接 QQ开放平台、微信公众平台等外部平台？

    • 是：需要使用公网地址 (场景一、二、三)。
    • 否：需要使用内网地址 (场景四)。

  2. 是否使用云服务器部署 Kirara AI？

    • 是：通常使用公网地址 (场景一)。
    • 否：请继续判断。

  3. 是否使用 Docker 部署 Kirara AI？

    • 是：请参考 场景三。
    • 否：你可能是在家用电脑或公司电脑本地部署，请参考 场景二 或 场景四。

安全提示

  • 密码设置：如果 Kirara AI 暴露在公网，请务必设置高强度密码，以防止未授权访问。
  • 选择性公开 (可选，进阶)：
    • 对于有更高安全需求的用户，可以使用 Nginx 等 Web 服务器，只公开 /im 开头的 URL，限制对 WebUI 面板的直接访问，从而提高安全性。
    • Nginx 配置

连接其他平台 ​

若需连接未内置的平台：

  1. 访问 插件市场 搜索目标平台适配器
  2. 安装完成后，返回本页面即可在下拉菜单看到新选项
  3. 根据插件文档填写配置参数