接入聊天平台
TIP
本节介绍如何把机器人接入 QQ、Discord、Telegram 等聊天平台。接入后，平台消息会进入 ChatLuna 处理，回复再原路发回平台。
ChatLuna 不直接与聊天平台通信，而是通过适配器（Adapter）。适配器负责登录平台账号、收发消息，并把各平台不同的数据格式转换为统一格式。因此，场景规则、权限、预设和长期记忆在接入新平台时都可以直接复用。
一个实例可以同时接入多个适配器和多个账号，例如一个 QQ 号和一个 Discord 机器人在同一个控制台中并行运行。
聊天平台页
在左侧导航栏的「配置」分组中点击「聊天平台」。每张卡片对应一个平台账号，显示：
- 平台与名称：平台类型和你设置的别名。
- 启用状态：适配器是否正在运行。
- 包状态：适配器插件是否已安装。
- 凭据状态：必填的令牌、密钥是否已填写。
- 机器人状态：
在线、离线、连接中、断开、重连中，以及平台头像和昵称。
机器人状态会定时自动刷新。
添加平台
点击右上角的「添加」，选择平台类型后填写配置表单：
| 平台 | 说明 |
|---|---|
| OneBot (V11) | QQ 生态最常见的协议，需要配合 OneBot 实现端使用 |
| 官方 QQ 机器人接口 | |
| Discord | 服务器与频道 |
| Telegram | 群组与私聊 |
| KOOK | 语音社区平台 |
| 飞书 / 钉钉 / 企业微信 | 企业办公场景 |
| Slack / Matrix / Zulip | 团队协作场景 |
| WhatsApp / LINE / Mail / 微信公众号 | 其他平台的接入 |
| Satori | 连接另一个 Satori 服务，适合多实例组网 |
核心配置通常只有几项：账号标识、服务地址、访问令牌，以及少数平台特有的参数。表单由适配器插件提供，插件更新后新增的配置项会自动出现。
TIP
控制台内置了一个无需配置的网页渠道。在接入外部平台前，可以先在「聊天」页面验证模型和预设是否正常。
安装与卸载
部分适配器以独立扩展包提供，未安装时卡片显示 未安装 并提供「安装」按钮。安装失败（通常是网络或包名问题）时，卡片底部会显示命令行输出。
不再需要某个平台时，先停用再卸载。
WARNING
卸载适配器不会删除你在第三方平台创建的机器人应用，只是断开 ChatLuna 与它的连接。
配置项
凭据
访问令牌、应用密钥等敏感字段保存后加密存储，界面上只显示 已配置 或 缺失。再次编辑时留空即可保留原有凭据。必填凭据缺失时可以保存，但无法启用，界面会标明缺少的项目。
WARNING
不要把访问令牌发到群聊、截图或公开文件中，泄露后他人可以冒充你的机器人。不慎泄露时，请立即在平台侧重置令牌并重新保存。
账号标识
每个适配器实例都需要一个账号标识，通常是机器人在该平台的账号 ID。同一平台接入多个账号时，标识必须唯一，否则系统无法判断消息该交给哪个账号。
配置快照
在适配器插件的设置中指定一个本地目录后，每次保存适配器配置前都会自动备份，出问题时可以从快照恢复。默认关闭。
启用与停用
保存配置后打开卡片上的「启用」开关，适配器会加载插件、用凭据登录平台、同步账号状态和头像昵称，然后开始接收消息。停用时断开连接，但保留配置，适合临时下线或排查问题。
修改并保存配置后适配器会自动重连。如果状态长时间没恢复，可以先停用再启用。
多个账号
常见的多账号用法：
- 一个号负责群聊，另一个号负责私聊答疑。
- 不同群分配不同的机器人，避免一个号被风控导致所有群失联。
- 测试账号与正式账号分开。
场景规则支持同时按「平台」和「机器人账号」匹配，可以让 A 账号只在技术群回答、B 账号只在娱乐群出现。
消息怎么流转
- 平台把用户的消息推送给适配器。
- 适配器转换为统一格式交给 ChatLuna。
- ChatLuna 根据内容、群组和发送者匹配场景规则。
- 由绑定的引擎和模型处理。
- 回复返回给适配器。
- 适配器按平台规范格式化后发出。
任何一环出问题，表现都是「机器人不回复」。排查时沿着这条链路逐级检查，不要直接归咎于模型。
平台差异
- 长度限制：超长回复会被拆成多条发送。
- 消息元素：图片、语音、表情、卡片和按钮并非所有平台都支持。
- 撤回与编辑：支持编辑已发消息的平台，流式输出的体验更好。
- 频率限制：频繁发送可能触发限流或风控，部分回复会被静默丢弃。
- @ 与引用：各平台实现不同，会影响触发判定。
「在 A 平台正常、在 B 平台格式混乱」时，先确认是不是平台本身的差异。
推荐配置
只接一个 QQ 号
- 在 OneBot 实现端中登录 QQ 账号。
- 在「聊天平台」页面添加 OneBot 适配器，填入连接地址和访问令牌。
- 连接成功后，卡片上的状态显示为
在线。
建议先在私密测试群中验证对话和指令，再拉入正式群。
多平台同时服务
QQ、Discord、Telegram 可以共用同一套模型和预设。不同平台的群 ID 格式不同，需要为规则分别配置匹配条件。通用的模型、预设和记忆策略放在全局配置，各平台特有的群规则、权限和触发名称单独管理。
企业办公
飞书、钉钉、企业微信通常需要管理员在开放平台中创建机器人应用，再把凭据填入表单。这些平台对消息格式和权限审核更严格，建议先在小范围内部群中测试。
自建网关
多个 ChatLuna 实例可以通过 Satori 适配器组网：一个实例作为消息网关汇聚各平台消息，其他实例按平台或业务分流处理。
常见问题
适配器一直显示未安装：点击「安装」查看输出日志，常见原因是网络无法访问软件源或包名变更。
已启用但机器人离线：查看卡片上的错误提示，常见原因有令牌失效、地址或端口错误、账号被风控、网络不通。使用 OneBot 时，先确认实现端在线，并检查其连接白名单。
机器人在线，但群里不回复：适配器正常。到「场景规则」确认该群是否命中规则，到「轨迹」页面检查消息是否进入了系统。
消息格式混乱：平台不支持某些消息元素，或回复太长被拆分。调整预设中的回复格式，或在场景规则中限制输出长度。
两个账号互相回复：两个机器人在同一个群里互相触发。关闭其中一个的无前缀触发，或在过滤条件中排除对方的账号。
修改配置后没生效：确认已保存并重新启用、改的是正在生效的卡片，以及没有更具体的场景规则覆盖。
