天枢群管家

连接机器人 ​

这篇帮你做什么：创建机器人档案、配置通信连接，并同步目标群。档案出现、连接显示“已连接”都不是最终结果；还要确认群号正确、机器人确实收到该群的消息。

实现端的协议支持、地址和登录状态须按所用软件核对。内置“默认QQ群设置”只是配置模板，真实群仍需在接入后同步。

先弄清三个词 ​

  • OneBot 实现端：真正登录 QQ、收发消息的软件（例如 NapCat、go-cqhttp 等）。天枢群管家不包含它，需要你另行安装并登录机器人 QQ 号。天枢群管家通过 OneBot 协议与它通信。
  • 机器人：控制台里给这个 QQ 账号建的档案（机器人管理页）。
  • 连接配置：规定天枢群管家与实现端之间"怎么连"——用什么协议、谁连谁、地址是什么（连接配置页）。

接通后还要同步真实群，再绑定方案或启用群级功能。完整关系见工作方式与作用范围。

开始前确认 ​

  • 你已经按首次使用启动了天枢群管家，并能打开控制台。
  • 你已经安装好一个 OneBot 实现端（如 NapCat），并知道它的连接方式。每种实现端支持的协议与连接方向不同，请以它的文档为准。

第一步：添加机器人档案 ​

  1. 打开 仪表盘 → 机器人管理，点 添加机器人。
  2. 填写：机器人名称（便于识别）、渠道（QQ）、机器人 ID（机器人的 QQ 号）、Token（机器人档案要求填写的口令字段）。这四项都是必填；留空 ID 或 Token 会有提示。连接是否需要鉴权，还要按实现端设置核对连接配置中的 Access Token，不能只填写档案就认定通信已受保护。口令不要放进截图、日志或公开提问。
  3. 绑定连接配置可以先不选（留空表示不绑定），全局权重保持默认 100 即可。
  4. 点 确认，提示"机器人创建成功"。
  5. 怎样确认成功：列表出现你的机器人，状态"启用"、在线状态"离线"——启用≠在线，离线是正常的，等连接通了才会变。

第二步：添加连接配置 ​

  1. 打开 仪表盘 → 连接配置，点 添加配置，填写必填的 配置名称（便于识别这条连接，可自行命名）。

  2. 根据 OneBot 实现端支持的协议选择 协议类型 与 通信方式。例如 NapCat 使用 OneBot V11；不要仅按版本数字大小选择。控制台中的 正向 = DataHub 作为服务端监听；反向 = DataHub 主动连接机器人端。

    创建连接配置对话框

  3. 方向怎么选（这是最容易错的一步）：

    通信方式谁听谁连你需要填什么
    WebSocket 正向连接本程序开端口等待，实现端连进来本程序的主机地址和端口
    WebSocket 反向连接本程序主动拨出，连到实现端开的地址实现端的 ws:// 地址

    注意：这里的"正/反向"是本程序视角的说法，和某些实现端软件的叫法正好相反。别按名字猜——先看你的实现端是"开端口等人"还是"主动往外连"，再对号入座。

  4. 选好后按提示填写地址等参数（反向连接需要实现端的 ws://地址:端口/路径；正向连接需要你指定本机地址和端口，保存后本程序会在该端口等待连入）。

  5. 状态选 启用，点 确认，提示"配置创建成功"。

  6. 怎样确认成功：列表里出现这条配置。此时"连接状态"只是说了链路这一半的情况——连接状态正常不代表已经收到群消息，最终以机器人在群里能否收到消息、执行操作为准。

第三步：把机器人和连接配置绑定 ​

回到 机器人管理，编辑你的机器人，在 绑定连接配置 里选择刚建的配置并保存。之后这条连接收发消息时，就会以这个机器人的身份处理。

连接状态的含义 ​

  • 未启用：配置存在但没启用。
  • 未连接：链路尚未建立；反向地址不可达时也可能显示此状态。检查实现端是否已启动及地址、端口、路径；到 logs\datahub.log 搜 dial failed 查看失败原因。
  • 连接中：正在尝试连接。如果目标地址写错或对方没开，会一直停在这个状态（后台反复重试），可到 logs\datahub.log 搜 dial failed 看具体原因。
  • 异常：连接出错，状态列会附上具体错误文字。
  • 已连接：链路已通。注意：正向连接下，只要本程序端口开成功就可能显示"已连接"，不代表实现端已经接入，也不代表机器人能收到群消息。

没成功先检查什么 ​

  1. 实现端是否已经启动并登录了机器人 QQ？
  2. 地址、端口、路径是否与实现端配置完全一致？方向选反了吗？
  3. 到 日志中心 → 应用日志 和 logs\datahub.log 搜错误关键字。
  4. 更多现象见常见问题。

怎样停止或改回 ​

  • 停用一条连接：连接配置列表把状态改为 禁用（或用批量操作），本程序会停止该连接的收发，随时可再启用。
  • 删除连接前先核对它绑定的机器人；仍被机器人绑定时，删除可能被拒绝。先编辑机器人解除绑定，再按需要删除连接；不要为了删连接误删仍要使用的机器人。
  • 删除机器人或连接配置不会清空整个数据库，但相关群设置会失去作用对象，请先确认影响范围。

更多说明 ​

  • 实现端接通后，先同步一个专用测试群，在已开启消息记录时，核对 日志中心 → 群消息记录 中是否出现该群的新消息；未开记录时不要仅凭列表为空认定连接失败。不要直接在真实成员身上尝试警告、禁言或踢出。没有消息时，按常见问题检查连接、身份绑定和群选择。
  • 接入成功后，到 群设置 → 群列表 点 同步群：
    1. 先选 单个群 或 全部群。第一次建议只同步一个测试群。
    2. 在连接配置下拉框中选择刚接通的 在线连接配置，确认选项名称已显示。
    3. 选择单个群时，填写实现端中的 平台群编码（QQ 群为群号），再点 确认同步。
    4. 怎样确认成功：关闭对话框后，目标群出现在列表中；核对群号和名称，不要只看按钮已点击。未出现时重新打开对话框确认在线连接和群编码，再查看错误提示与应用日志。
  • 群列表中的内置“默认QQ群设置”用于编辑模板，不代表机器人已经加入真实群。同步后请按真实群号核对接入结果。