机器人助手

机器人助手把主页插件的 AI Agent 接入微信、QQ 或飞书。配置完成后，不需要先打开思源中的聊天窗口，直接在常用聊天软件里发送自然语言，就能查询笔记、记录账目、管理纪念日、收藏、复习和日记任务。

它不是一套独立的“机器人命令系统”，而是本地 AI Agent 的远程输入和输出端：模型、工具、上下文与写操作确认仍由主页插件处理，微信、QQ 和飞书只负责收发消息。

一、先选择合适的渠道和运行环境

三个渠道使用同一套 Robot Core 和 Agent 能力，但运行位置不同。

QQ 和飞书依赖思源桌面客户端提供的 Electron 环境，因此不能在 Docker 浏览器端或思源移动客户端中建立连接。关闭对应的桌面客户端后，机器人也会离线。

微信运行在思源 Kernel 中，不依赖桌面窗口。把思源部署在 NAS 或服务器后，只要容器和网络保持运行，即使关闭浏览器，微信机器人仍然可以继续收消息和执行任务。

二、开始前完成 AI 模型配置

机器人助手复用“AI 知识库”中已经配置的模型，不需要单独填写另一套 API 地址和密钥。

开始前建议先完成以下检查：

1. 在“AI 知识库 → 大模型配置”中添加模型提供商；
2. 填写并保存 API Key；
3. 对准备使用的模型运行“测试连接”；
4. 再运行“测试 Agent”，确认模型支持工具调用；
5. 在本地 AI 对话中完成一次普通问答和一次工具调用。

“测试连接”成功，只代表模型可以回答问题；机器人需要调用知识库、记账等工具，因此还要通过 Agent 兼容性测试。模型能够普通聊天，但不支持工具调用时，远程机器人也无法完成实际操作。

三、开启机器人并指定唯一运行设备

打开“主页设置 → 机器人助手 → 总体设置”。

1. 启用 Robot Core

打开“启用机器人助手”，确认 Robot Core 状态变为“运行中”。如果显示内核未运行或初始化失败，请先重启思源与插件，再查看思源内核日志。

2. 选择当前使用的机器人

微信、QQ 和飞书的配置可以同时保存，但同一时间只会连接一个渠道。在“当前使用的机器人”中选择微信、QQ、飞书或“不使用机器人”。

切换渠道不会删除其他渠道的 App ID、密钥、绑定状态和白名单。需要改用另一渠道时，直接切换即可。

3. 指定运行设备

如果同一个思源工作空间同时在台式机、笔记本或 Docker 上打开，必须指定一台“运行设备”。只有该设备会连接当前机器人，其他设备显示待机，不会抢消息或重复回复。

准备更换设备时：

1. 先让最新设置和笔记数据完成同步；
2. 在新设备中打开机器人助手总体设置；
3. 点击“设为当前设备”；
4. 确认旧设备进入待机，新设备上的 Robot Core 和渠道状态正常。

思源同步不是实时数据库。设置先上传到云端，再由另一台设备下载，中间可能存在几十秒延迟。切换期间不要同时发送写入任务，确认新设备接管后再继续使用。

4. 调整运行限制

总体设置还可以调整：

• 单条消息与回复的最大长度；
• 全局 Agent 并发数量；
• 单次模型响应超时；
• 整轮 Agent 任务超时。

普通使用建议先保留默认值。模型响应较慢时可以适当增加超时，但不要通过无限增大并发来解决消息积压，否则更容易触发模型服务限流。

四、配置微信机器人（推荐）

微信不需要前往开放平台创建应用，主要流程是扫码绑定和批准允许使用的账号。

1. 扫码绑定

1. 在总体设置中把当前机器人切换为“微信机器人”；
2. 进入“微信机器人”标签页；
3. 点击“扫码绑定微信”；
4. 使用手机微信扫描二维码，并在手机上确认；
5. 等待设置页显示“微信已绑定，消息监听运行中”。

登录状态会保存下来。以后重启插件或重新打开设置页时，已经连接的账号会自动恢复，不会重复显示二维码。只有点击“重新扫码绑定”或“解除绑定”时，才会清除原绑定并进入新的扫码流程。

二维码过期时点击刷新即可；如果手机要求输入配对数字，按照页面提示填写并提交。

2. 设置私聊、群聊和白名单

可以分别控制：

• 是否允许私聊；
• 是否允许群聊；
• 群聊中是否必须 @ 机器人；
• 允许使用机器人的用户 ID；
• 允许使用机器人的聊天 ID。

不建议把机器人直接开放给所有联系人。点击“捕获下一条私聊”，再从准备授权的微信账号发送一条普通消息。设置页捕获到用户 ID 和聊天 ID 后，检查账号信息并点击允许，最后保存设置。

捕获只用于识别和批准账号，不会把这条测试消息当成正式 Agent 任务。微信、QQ 和飞书各自拥有独立的捕获区域，不会把微信捕获结果显示到其他渠道中。

3. 在 NAS 上保持 24 小时运行

使用 NAS / Docker 时，建议这样配置：

1. 确保思源容器能够访问互联网，并设置为自动启动；
2. 通过电脑浏览器打开这台 Docker 思源的设置页；
3. 在 Docker 对应的设置页完成微信扫码绑定；
4. 把 Docker 设备设为机器人当前运行设备；
5. 确认微信状态在线后关闭浏览器进行测试。

浏览器只是管理界面，真正的微信监听位于思源 Kernel。浏览器关闭不会中断机器人，但停止或重启思源容器会造成短暂离线，服务恢复后会自动尝试重新连接。

五、配置飞书机器人

飞书仍然使用企业自建应用和官方长连接 SDK。下面的开放平台配置步骤与旧版基本一致，但插件端已经不再使用外部 Node.js 网关。

飞书开放平台

创建并管理机器人助手使用的企业自建应用。

open.feishu.cn

↗

1. 创建应用并开启机器人能力

登录飞书开放平台，创建企业自建应用，然后开启机器人能力。

2. 添加消息权限

按照开放平台提示，为应用添加机器人收发消息所需的权限。

3. 配置长连接事件

在“事件与回调”中选择长连接接收事件，并添加消息接收事件。

4. 发布应用

完成配置后创建版本并发布应用。应用未发布、权限未生效或机器人不可见时，插件即使成功连接，也可能收不到消息。

5. 在插件中保存凭据

回到思源桌面客户端：

1. 在总体设置中选择“飞书机器人”；
2. 进入“飞书机器人”标签页；
3. 填写 App ID 和 App Secret；
4. 配置私聊、群聊、群聊 @ 要求和白名单；
5. 点击“保存飞书设置”；
6. 等待右上角状态变为“已连接”。

App Secret 输入框留空时，会保留已经加密保存的密钥，不会把旧密钥清除。需要更换密钥时再填写新的 App Secret 并保存。

接下来点击“捕获下一条私聊”，从自己的飞书账号给机器人发送一条消息，确认捕获到的用户与聊天 ID 后加入白名单。

六、配置 QQ 机器人

QQ 机器人需要先在 QQ 开放平台创建，然后通过 App ID 和 App Secret 接入主页插件。

QQ 开放平台

创建 QQ 机器人并获取 App ID 与 App Secret。

q.qq.com

↗

完成开放平台中的机器人创建、权限和发布流程后：

1. 在总体设置中选择“QQ 机器人”；
2. 进入“QQ 机器人”标签页；
3. 填写 App ID 和 App Secret；
4. 配置允许的私聊、群聊、用户 ID 和群 ID；
5. 点击“保存 QQ 设置”；
6. 等待状态显示已连接；
7. 使用“捕获下一条私聊”批准自己的 QQ 账号。

QQ 开放平台中的“连接第三方 Agent 服务”或扫码页面，不等于主页插件已经取得机器人凭据。主页插件当前使用 App ID 和 App Secret 通过官方 SDK 建立连接，应以插件设置页的连接状态为准。

部分 QQ 机器人会要求配置公网出口 IP。更换网络、使用代理或切换电脑后突然无法连接时，请根据控制台提示和 QQ 开放平台后台检查 IP 白名单。

七、选择 Agent 模型和远程工具

进入“机器人助手 → Agent 设置”。

1. 选择执行模型

“执行模型”会列出 AI 知识库中已经配置并启用的模型，可以选择：

• 跟随 AI 知识库默认模型：本地默认模型改变后，机器人也跟随切换；
• 指定模型：机器人始终使用选中的提供商和模型，不影响本地聊天框的默认选择。

选择后，模型配置和对应 API Key 会同步到 Robot Core。已经删除、停用或尚未同步到当前设备的模型会显示为暂不可用。

远程 Agent 需要稳定的工具调用能力。长思考模型、纯补全模型或仅支持普通聊天的接口，不一定适合作为机器人模型，选择前应先在 AI 知识库中运行“测试 Agent”。

2. 控制工具权限

机器人可以使用的工具包括知识库查询、日记任务、数据库、文档编辑、目录结构、文档属性、资源文件、Riff 卡片，以及主页插件的快速笔记、专注清单、记账、固定资产、纪念日、收藏和复习等能力。

具体工具会随插件版本变化，并受会员权限和当前配置影响。可以逐项关闭“允许远程使用”，也可以为写操作选择：

• 写操作需确认：先展示准备执行的操作，收到确认后再写入；
• 写操作拒绝：远程聊天只能查询，不能执行该工具的写入动作。

建议只开放自己确实会远程使用的工具。涉及删除或批量修改时，应先在电脑端检查目标内容。

八、通过聊天使用 AI Agent

授权完成后，直接发送自然语言即可。例如：

帮我记一笔账，今天午饭 18 元，账户是微信。

查一下知识库里关于主页插件发布流程的笔记，先总结，不要修改。

新建一个纪念日：项目上线，日期是 8 月 20 日，每年提醒。

机器人会根据问题选择允许的工具，并把最终结果回复到当前聊天。

写操作必须确认

记账、新建或修改笔记等写操作会先返回操作摘要。请检查目标、金额、日期和影响范围，再在两分钟内严格回复：

• 确认：继续执行；
• 取消：放弃操作。

确认后会先收到“已确认，正在执行”，随后再收到最终结果。确认已经过期时，原操作不会执行，需要重新发送原始请求。

等待确认期间发送其他文字，不会被当成确认，也不会偷偷排到后面执行。机器人会提醒只回复“确认”或“取消”。重复发送确认、平台重复投递同一条消息，也不会造成同一写操作重复执行。

内部命令

机器人支持以下平台无关命令：

• 帮助 或 #help：查看当前使用方式；
• 状态 或 #status：查看渠道和模型状态；
• 新会话 或 #new：创建并切换到空白上下文；
• 确认 或 #confirm：批准当前等待确认的操作；
• 取消 或 #cancel：取消当前等待确认的操作。

“取消”只用于正在等待确认的写操作，不能强制中断已经提交给模型的普通问答。

九、连续上下文与会话管理

同一渠道、机器人账号、聊天和联系人会使用同一个默认远程会话。下次继续给机器人发消息时，会继承原来的上下文，不会因为关闭设置页或闲置一段时间自动清空。

远程会话使用与本地 Agent 相同的消息和工具调用上下文格式。较长对话会进行存储级上下文整理，不会把所有历史原文无限塞回模型；用户可见的近期聊天记录和工具摘要仍会保留，便于检查执行过程。

进入“机器人助手 → 会话管理”可以：

• 按渠道和机器人账号筛选会话；
• 在左侧选择已有对话；
• 在右侧查看用户消息、Agent 回复和工具执行记录；
• 新建、重命名或删除对话；
• 把某个对话设为当前聊天的默认会话。

发送“新会话”只会切换到新的空白上下文，旧对话不会丢失，可以稍后在会话管理中重新设为默认。

十、消息延迟、连续发送和消息日志

手机网络延迟或平台重试可能让多条消息短时间集中到达。Robot Core 会按同一聊天中的接收顺序串行处理：上一条尚未完成时，后续消息进入短队列，并提示前面还有多少条等待处理。

队列不是无限的。消息积压过多或等待超过安全时限时，机器人会拒绝或取消该条消息，让用户重新发送，避免过期指令在很久以后突然执行。不同会话可以在总体并发限制内同时处理。

进入“机器人助手 → 消息日志”可以查看最近的消息接收、过滤、执行、回复和失败状态。日志只保留最近 20 条，并对用户和聊天 ID 做掩码，不会无限增长。需要排查“平台收到了但没有回复”时，先查看这里，再检查渠道状态和思源日志。

十一、常见问题

扫码后仍显示等待登录

先等待几秒并刷新状态。手机必须完成扫码后的确认步骤；二维码过期后应重新生成。已经绑定成功时不应重复扫码，只有更换微信账号才使用“重新扫码绑定”。

机器人显示已连接，但发消息没有回复

依次检查：

1. 当前使用的机器人是否选中了这个渠道；
2. 当前设备是否为唯一运行设备；
3. 发送账号和聊天是否已经加入白名单；
4. 私聊、群聊和群聊 @ 规则是否允许；
5. Agent 模型是否配置并同步成功；
6. 消息日志中是被过滤、排队、执行失败还是回复失败。

飞书已连接但收不到消息

检查应用是否已经发布、机器人能力是否开启、消息权限是否生效，以及事件订阅是否选择长连接并添加了消息接收事件。飞书只在思源桌面客户端运行，浏览器和 Docker 页面不能建立飞书连接。

QQ 提示机器人未连接

确认 App ID 与 App Secret 已保存，机器人已经在 QQ 开放平台发布，并检查平台要求的公网出口 IP。QQ 连接依赖思源桌面客户端，关闭客户端后会离线。

从早期测试版升级后，如果页面提示 App Secret 无法读取，说明旧密文与当前设备的安全主密钥不一致。旧密文不能安全还原，请重新填写一次 App Secret 并保存；新版会统一由 Robot Core 加密，之后切换渠道不需要重复填写。

Docker 与电脑同时打开后重复回复

在总体设置中只保留一个当前渠道，并明确指定一台运行设备。等待思源完成设置同步，确认另一台设备显示待机后再发送新消息。长期在线场景建议让 NAS 运行微信机器人，电脑只作为管理端使用。

确认后没有执行

确认必须来自发起操作的同一账号和聊天，并在两分钟内严格回复“确认”。如果已经过期、Robot Core 重启或回复了其他文字，原写操作都会安全失效，需要重新发送原始请求。