七种应用框架怎么配置

这一篇接着 安装并对接应用端 往下讲。七个框架各有各的脾气，不用全看，找到你装的那一个就行。建议的顺序都一样：先让一条消息跑通，再慢慢加插件、模型和规则。

同一个框架可以有好几个实例，每个实例的配置和目录是分开的。动手改之前，看一眼详情页顶部的实例名和主机，别改错了对象。

先搞清楚改动存在哪

• 配置表单出现「有改动还没保存」时，点底部「保存」或者按 Ctrl+S。有错误的话点「去看看」定位过去；点「撤销」会丢掉这次没保存的草稿。
• 人格、知识库、学习记录这类运行数据，归框架自己的服务管。有的对话框点「创建」「保存」就直接写进去了，不经过底部那条保存栏。
• 提示「实例没在运行」，就先启动它；提示控制台登录失败，就核对这个实例的 WebUI 凭据。QQ 登录了，不代表框架的控制台也登录了。
• 看到重启提示就照做。自定义字段可以去原始文件里改。如果 WebUI 和 Desktop 同时改了同一份配置，先处理保存冲突，再继续往下。

应用端配置表单 · 演示数据

Karin：装一个插件，限定响应范围

连接与主人

1. 进入 Karin 实例详情，按 对接步骤 关联协议 Bot。
2. 在「权限」的「主人」里填你自己的 QQ 号，需要别人帮忙管理的话再填「管理员」。注意主人填的是你，不是 Bot 自己的号。
3. 看一下「用户名单」和「事件范围」。白名单只要不为空，就只会响应名单里的人；事件开关关掉的类型，不会交给插件处理。
4. 保存，启动 Karin 和 Bot，用主人账号在允许的会话里测一下。

两边日志都显示连接已建立，就说明接上了。至于普通指令有没有回复，还要看你装没装对应的插件。

Karin 权限页：先填主人，再检查名单与事件范围 · 演示数据

安装与管理插件

1. 进「插件」，搜插件名，可以按 npm、git、app 类型筛选。
2. 点安装，等任务结束。第一次建议挑一个文档齐全、依赖少的，出了问题也好查。
3. 已经装好的插件，在「插件操作」菜单里启用、禁用、更新或卸载。有配置入口的，打开把必填项填好再保存。
4. 按插件说明发一条指令试试。没反应的话，先看插件启用了没有，再去日志里找有没有依赖或配置错误。

暂时不想用某个插件，禁用比卸载更容易恢复。真要卸载，先把插件自己的数据备份一下。

规则、日志与渲染

「响应规则」分「群 / 频道」和「私聊」两块。改之前先分清楚，你要改的是默认规则，还是某一个具体的群或人。改完就在同一个会话里测，换个会话测可能碰上的是另一条规则。

「基础」里有运行器、NODE_ENV、日志等级、保留天数、单文件上限和 FFmpeg 路径。实例跑得好好的，装插件时没必要去动运行器。FFmpeg 路径留空，会自动从 PATH 里找。

「渲染与存储」用来配渲染器 WS / HTTP 的地址、Token，以及 Redis。图片类插件报渲染连接失败的话，查一下这里指向的渲染服务有没有启动。改 Redis 需要重启。另外，Redis 密码和渲染器 Token 是两个东西，别填混了。

NoneBot2：适配器、插件与命令前缀

接入 QQ

1. 进入 NoneBot2 详情的「适配器」，搜索并安装 OneBot v11 适配器。
2. 进「连接」，核对 HOST、PORT 和 ONEBOT_ACCESS_TOKEN。用一键对接的话，先在对接入口生成配置，再回来看一眼。
3. SUPERUSERS 填你自己的 QQ 号，NICKNAME 填你想怎么称呼 Bot。
4. 保存并启动，看日志里适配器有没有加载成功，有没有 Bot 连上来的记录。

已经对接过的实例，改了端口或 Token 会重写对接配置。跨机器的地址怎么填、正向反向 WS 有什么区别，见 OneBot 连接。

NoneBot2 连接页：HOST、PORT、Token、主人和命令前缀在同一页检查 · 演示数据

装一个插件试试

1. 打开「插件」，搜索目标插件，看清楚说明和适配器要求再安装。
2. 需要配置的插件，打开配置入口，把 API Key、目标群这些填上。
3. 回到「连接」看「命令前缀」。比如前缀里有 /，插件命令是 help，那一般要发 /help；具体怎么触发，以插件文档为准。
4. 保存，需要的话重启实例。先在一个会话里测通，再放给更多群用。

「无前缀也响应」会往配置里加一个空前缀，开了以后群友随口聊天也可能触发插件。先关着，等你确认插件只会匹配该匹配的内容再说。「命令分隔」和「自定义键」按插件或项目的要求设置就好，不清楚是干什么的键，保持原值别动。

插件装上了却加载失败，去看实例的启动日志。目录里有这个包，不代表它被成功导入了。缺 Python 依赖、适配器不匹配、插件本身有 bug，这几种情况要分开处理。

AstrBot：先选模型，再决定怎么回复

添加提供商与默认模型

1. 进「模型」，点「添加提供商」，选你用的服务商对应的类型或预设。
2. 填你自己的「API Key」和服务商给的「接口地址」。确认提供商是启用的，在它下面加上服务商支持的模型标识，并启用模型。
3. 确认对话框，然后保存页面配置。新加的提供商没保存之前，服务端还不认识它，拉不到模型列表。
4. 在页面顶部的「默认模型」里选刚加的对话模型。想留个后手，就再选「备用模型」并排好顺序，默认模型出错时会依次往下试。
5. 保存，启动实例，或者按提示重启。

「默认模型」下拉框是空的话，检查提供商和模型是不是都启用了，以及这个提供商是不是对话类型的。接口地址、API Key 和模型 ID 都要照着同一家服务商的文档填，模型 ID 别填成网页上显示的那个好听的名字。

AstrBot 模型页：先配置提供商及模型，再选择默认与备用模型 · 演示数据

设个人格，收一条测试消息

1. 在「连接与账号」核对 OneBot v11 连接和 WebUI 凭据，完成和协议 Bot 的对接。
2. 启动 AstrBot，等控制台连上，进「人格」点「新建人格」。填一个不重复的「标识」，比如 helper，再写一段系统提示词，比如「回答先给步骤；不确定时说明缺少什么信息」。
3. 在人格列表里点「设为默认人格」，然后保存页面配置。人格内容是控制台即时保存的，但「默认用哪个人格」这一项，需要另外保存配置。
4. 进「回复设置」，打开「大模型回复」。检查「唤醒前缀」「对话额外前缀」「私聊也要唤醒前缀」和白名单，确保你的测试会话满足这些条件。
5. 在允许的会话里，带上前缀发一句话。收到回复，日志里也没有鉴权或模型调用的错误，就成了。

如果希望群里每个人都有自己的上下文，用「独立会话」。想控制花费，在「上下文与工具」里设保留轮数、工具调用步数和超时。语音和联网搜索需要对应的提供商才能用，光打开开关是不够的。

知识库、会话规则与子代理

删知识库会把里面的文档和向量一起删掉；删档案以后，绑定在它上面的会话会回到默认档案。动手之前，先把框架数据备份一下。

MaiBot（麦麦）：模型、名单和试聊

提供商、模型和任务分配

1. 进「模型」，在「提供商」里点「加提供商」，选预设，填「接口地址」和你的「API Key」。默认那个占位的 Key 一定要换掉。
2. 在「模型」里加条目：起一个你认得出来的「名称」，填服务商实际的「模型标识」，选刚才那个提供商。只有支持看图的模型才打开「能看图」。
3. 在「任务分配」里，至少给「回复」「规划」「杂务」各选一个模型。只加了模型不分配任务，麦麦还是开不了口。
4. 按需给「识图」选视觉模型，给「嵌入」选文本嵌入模型。嵌入任务不能拿普通对话模型凑数。
5. 保存。实例运行、WebUI 有响应以后，可以用提供商测试、拉取模型列表来核对一下。

「高级选项」里有鉴权、重试、超时、温度、最大输出和计价，先用服务商推荐的默认值。这里填的输入输出价格只是用来统计花了多少钱，不会改变你实际的账单。删掉一个还被任务引用着的模型，会被标红提醒，先把任务改到别的有效模型上再保存。

麦麦模型页：提供商、模型与任务分配需要逐层配置 · 演示数据

放行一个测试会话

1. 在「连接」确认已经对接了协议 Bot，核对 WebUI 端口。旧版的消息服务端口即使用不上，也必须空着，否则麦麦可能起不来。
2. 打开「聊天名单」，看「按名单过滤」，以及群聊、私聊各自的名单模式。
3. 默认是空白名单，也就是什么消息都不放行。第一次只加你自己的 QQ 或者一个测试群就好，别一下子让它接进一大堆群的消息。
4. 看一眼「屏蔽用户」，确认测试账号不在里面。保存，启动麦麦和协议 Bot。
5. 回到「概览」看对接、模型、名单和运行状态，都正常了再去 QQ 里测试。

先试聊，再调人格与提示词

「试聊」直接走麦麦 WebUI 的聊天室，不经过 QQ。这样就能把「模型那边有问题」和「OneBot 那边有问题」分开排查。

1. 麦麦在运行、WebUI 也连上以后，进「试聊」，填一个昵称，麦麦会用它来称呼你。
2. 发一句简单的话。Enter 发送，Shift+Enter 换行。图片可以选择、粘贴或者拖进来，一条最多 8 张，本机图片单张预览最大 3 MB。
3. 如果试聊里能回、QQ 里不回，那问题多半出在协议 Bot 对接、聊天名单或者会话规则上。
4. 在「人格」里调整它的身份和说话方式。想改模板的话进「提示词」，按语言或关键词找到对应模板，改完保存，再拿同一个问题对比一下效果。

提示词在运行时通过 WebUI 保存，停止状态下直接改文件。刚启动、WebUI 还没就绪的时候，稍等一会儿再改，也别两个地方同时改。清空试聊只会清掉这里的对话记录，麦麦对你的印象、学到的东西可能还在。

调整一个群的表达学习策略

「表达学习」管的是要不要学、要不要用；「表达方式」里是已经学到的记录。关掉学习不会删掉旧记录，也不会阻止它继续使用旧记录。

1. 进「表达学习」，找到「表达方式 → 学习配置」。实例在运行、WebUI 连通时，可以点「从聊过的里选」挑出测试群；还没有聊天记录的话，点「加一条」，手动填这个聊天的平台、群号和「聊天类型」。
2. 在这条规则里保持「使用」开启，关掉「学习」。这样这个群还能用已经学到的表达，但不会再学新的。注意，平台和聊天流 ID 都留空的话，这条会变成默认规则，只想管一个群就要填完整。
3. 保持「使用精选表达」开启。想让麦麦用上某条已有的表达，去「表达方式」里给它点上星标精选。
4. 点底部「保存」，然后重新进这个页面，确认目标群和两个开关还是刚才设的值。有重启提示就照做。学习是在后台慢慢进行的，刚发一句话没看到新记录，不能说明配置有问题。
5. 「黑话」有自己单独的「学习配置」。如果同一个群也不想让它继续学黑话，就在这里给同一个目标关掉「学习」，上面的表达规则管不到这里。

「优化表达方式学习」会在写入之前让 AI 先过一遍内容，所以会多调用几次模型。「表达使用方式」选「超级精细」需要配好嵌入模型，没配的话就保持「随手」。需要跨群共享表达时再去配共享组，配的时候逐个核对组里的聊天，免得几个群的说话风格混到一起。

给一个会话追加提示词与时间规则

用一个已经在「聊天名单」里放行的测试群来试。这里的规则只会改变它怎么回复，不能代替名单放行。

1. 进「会话规则 → 按聊天追加的提示词」，在「额外 Prompt」里点「从聊过的里选」挑出目标。手动填的话，要把 platform、item_id、rule_type 和 prompt 都填齐，类型要和目标对得上（群聊或私聊）。
2. prompt 里写一条容易看出效果的要求，比如「讲解安装问题时，先给一个操作步骤，再等待我确认」。平台、聊天 ID 和提示词少填一项都保存不了。
3. 保存以后，在这个会话里问一个安装相关的问题，看看回复风格有没有变化，再去一个没有这条规则的会话里对比一下。它是叠加在通用人格之上的，模型也不一定每次都完全照做。
4. 想让它晚上少说点话，在同一页的「分时段发言频率」里打开「启用动态发言频率规则」，在「动态发言频率规则」里给同一个目标加一条：时间段填 22:00-08:00，频率先设成 0.3。
5. 保存，核对规则的目标，以及麦麦所在机器上的实际时间。频率 1 是正常水平，数值越低越安静，它并不是「每几条消息必回一条」的意思。先加这一条，确认效果后再往别的时段扩展。

「关键词反应」可以在消息命中时追加一段固定提示：关键词和正则至少填一种，再填命中以后的反应提示，正则一行写一条。「消息过滤」是用来排除内容的。要是它突然完全不回了，先查名单和过滤条件，再查发言频率。每次只改一组规则，不然很难知道是哪一处起的作用。

接入一个已有的 MCP 服务

这一节配置的是 MaiBot 作为 MCP 客户端。如果你要让本机 AI 工具访问 Desktop 管理的 Bot，按 接入 NCD MCP 配置 Desktop 自己提供的服务。

先准备好一个你已经部署、或者有权限使用的 MCP 服务，拿到它的传输方式、地址和鉴权信息。普通网页或者模型 API 的地址不是 MCP 地址，填进来是连不上的。Desktop 只负责配置和试连，不会替你部署服务。

1. 进「MCP」，打开「启用 MCP」，在「MCP 服务」里点「加一条」。填一个不重复的「服务名称」，比如 test-tools，打开「启用服务」。
2. 服务要求 Streamable HTTP 的话，「传输方式」选「远程 HTTP」，「服务 URL」填完整地址；要求 SSE 就选「旧版 SSE」。需要 Bearer 认证的，「远程认证」选 Bearer Token 并填上令牌，其他请求头填在「请求 Headers」里。
3. 服务要求用本地命令启动的，选「本地命令（stdio）」，按它的安装说明填「启动命令」「命令参数」「环境变量」，每个参数单独占一条。这个命令必须能在麦麦所在的那台机器上运行，远端的实例可用不了你 Windows 电脑上的程序路径。
4. 启动麦麦，等 WebUI 连通后，页面顶部会显示每个服务的连接状态。点这个服务的「试连」，用当前的草稿测一下：成功会显示「连得上」和工具数量；失败的话，按提示去查地址、认证、运行依赖，或者服务本身。
5. 试连通过以后，还要记得点底部的「保存」。等麦麦重新加载配置，状态变成「已连上 · … 个工具」。如果提示刚保存、需要等重载，就稍等一下或者按提示操作。
6. 最后问它一个确实需要用到某个工具的问题，再去麦麦日志里确认有没有调用。「连得上」只说明连接没问题，模型会不会去用这个工具、工具能不能执行成功，要到这一步才知道。

启用的服务必须有一个不重复的名称；stdio 必须填启动命令，HTTP / SSE 必须填 URL，选了 Bearer 认证就必须填 Token。缺了哪项会标红，点保存栏上的「去看看」能直接定位过去。没配完的空条目可以删掉，或者先把「启用服务」关掉。

「客户端高级能力」里，Roots 会告诉服务它能访问哪些目录，Sampling 允许服务反过来请求调用模型，确实用得上再配。标着「暂未支持」的 Elicitation、携带上下文这些，保持关闭。MCP 配置里可能有令牌和环境变量，导出的配置包记得按 备份说明 好好保管。

学到的内容与长期记忆

学习记录、知识库和聊天数据都在框架自己的数据库里，Desktop 导出的配置 ZIP 不会包含它们，见 备份边界。

Koishi：插件树、市场与沙盒

先跑通连接

1. 打开 Koishi 详情，完成和协议 Bot 的对接，启动实例。
2. 在「服务器」里核对端口和监听地址。控制台和 Bot 的反向 WS 共用这个端口，改了端口的话，Desktop 会同步更新 Bot 那边的对接地址。
3. 跨机器对接会走 SSH 隧道，不用为了对接把端口暴露到公网上。
4. 在「连接」里看当前的对接情况，在「概览」里看控制台显示的 Bot 在线状态。

selfUrl 是在有域名、走反向代理的时候，用来生成对外链接的。收图片或者回调出了问题，再结合你的代理和网络配置去核对它。

先装包，再加进插件树

1. 在「插件市场」里搜索并安装插件包，等任务结束。
2. 回到「插件」点「添加插件」，从已安装的包里选出来。在市场里装包，和在插件树里启用，是两个独立的步骤，第一次用很容易漏掉后一步。
3. 在左侧选中插件，右侧按表单填好必填项，也可以切到配置原文直接改。
4. 打开这个节点的开关，保存。运行中改配置可能会触发 Koishi 重载，Bot 会短暂断开再重连。
5. 先在「试聊」里发插件规定的指令，再到真实的 QQ 会话里验证一次。

插件树可以分组、移动，同一个插件也能多开一份配置，比如给第二个适配器账号单独用一份。Desktop 对接时写入的节点会标明用途。界面提示是 Koishi 或 Desktop 必需、不能停用的插件，留着就好。

Koishi 配置面板：从实例导航进入对应设置，再检查运行和保存状态 · 演示数据

即使节点开关是打开的，「载入条件」也可能让插件不加载。要改载入条件得去原始文件里改，改之前先复制一份现有的配置。

用自带工具排查

• 「全局设置」：指令前缀、昵称、国际化、延迟等。运行中保存会触发重载，短暂断线是正常的。
• 「试聊」：控制台里的沙盒，不经过 QQ。可以调整模拟用户名和对话模式，用来单独验证插件本身有没有问题。
• 「指令」：搜索指令或别名，调整权限等级、冷却时间和次数上限。测试的时候留意账号权限够不够、是不是还在冷却。
• 「数据库」：看表结构和分页记录，目前只读。要改数据，请用插件或者上游控制台。
• 「文件」：浏览实例目录，可以新建、重命名、删除。文本文件能编辑，图片能预览，二进制文件不支持编辑。改运行配置之前先备份，改完按框架要求重载。

TRSS-Yunzai（云崽）：主人权限与群规则

配主人并验证指令

1. 在「主人与权限」的「主人 QQ」里填你自己的 QQ 号。有多个 Bot、每个要不同主人的话，在「只对某个 Bot 的主人」里按 Bot号:主人号 的格式填。
2. 在「连接」完成 OneBot 对接，核对云崽的服务端口和 token。HTTP 和 WS 共用这个端口，改了需要重启。
3. 检查 Redis 配置，本机的 Redis 可以在「组件」页里管理。连不上的话，先查地址、端口、库号和密码。
4. 保存，启动云崽和 Bot，按插件说明分别测一条普通指令，和一条只有主人能用的指令。

普通指令能用，不代表主人已经配好了。#更新、#重启 这类管理指令只认主人。主人号填错了就改过来，不要为了让指令能用就把所有人的权限放开。

云崽的主人与权限：用自己的 QQ 号设置主人，并核对申请与消息范围 · 演示数据

只让某个群用某些功能

1. 进「群聊」，先看「所有群的默认」里的「响应哪些消息」、群冷却、个人冷却和功能名单。
2. 只想改测试群的话，在「单独设置」里加上目标群号，填要覆盖的项目，没填的沿用默认值。
3. 同一个群里有好几个 Bot 时，用 Bot号:群号 来指定。优先级从高到低是 Bot号:群号 → 群号 → Bot号:default → 默认。
4. 保存，在目标群里测试。冷却时间内再发一次可能没反应，等冷却过了再试。

「主人与权限」里还管着好友申请、群邀请、私聊和黑白名单。白名单只要不为空，就只处理名单里的目标。「谁拉进群都同意」打开之前，想清楚你是不是真的需要。

图片渲染与插件

「渲染」可以选自动、shotium 或 puppeteer。自动模式会根据模板里有没有脚本来选。puppeteer 需要浏览器，安装时没有下载 Chrome 的话，填一个电脑上能用的 Chrome / Edge 路径，或者配一个单独运行的远程浏览器地址。

插件在「插件」页里安装、配置、更新或卸载。云崽的目录插件是整个一起加载的，只有支持的单 JS 插件可以单独启停，开关是灰的时候按提示处理。「基础」里还能设置自动更新、自动重启、cron 计划、日志和文件监听。建议先让实例稳定跑一段时间，再加这些定时操作。

NeoBot：先连上面板，再配模型

面板凭据

1. 启动 NeoBot，进「面板凭据」。等它探测完，会告诉你面板是还没启动、还没设密码，还是已经有密码等你登录。
2. 还没设过密码，就填「新面板密码」和「确认密码」；已经有密码了，就填「面板密码」。提交后看登录验证的结果。
3. 提示版本不支持的话，先在版本页或者上游那边升级。Desktop 代你登录，要用到 NeoBot 1.2.4a1 才开始提供的登录接口，旧版本密码输多少遍都没用。
4. 验证通过后进「概览」，能读到版本、运行时长和连接状态，再继续往下配模型。

面板密码存在本机的密钥库里。换了电脑或者恢复配置以后，可能需要重新填一次，见 备份与恢复。

供应商和模型分配

1. 在「供应商与密钥」的「API 供应商」里填名称、API 地址和你的 API Key，点这一页的保存按钮。
2. 打开「模型」，在「模型库」里加模型条目。要填的字段由当前的 NeoBot 面板决定，模型标识填服务商那边真实的名字；有拉取或测试入口的话，用它确认一下。
3. 在「模型分配」里给各个用途选好模型，点「保存分配并重载」。模型库里有条目、用途却还显示「未分配」的话，对应的任务就没有模型可用。
4. 进「部署」检查有没有缺项，以及 OneBot 对接情况。同机地址和局域网地址，按 NapCat 实际跑在哪台机器上来选；Access Token 必须和协议端那边一致。
5. 回到「概览」「系统与运行」确认连接正常，在允许的会话里测一条回复。

「本体配置」可以用表单改，也可以直接改 TOML 原文。重新读取会丢掉当前的草稿；恢复默认只是替换草稿，保存以后才会生效。页面是只读的话，检查一下当前面板会话有没有对应权限。

NeoBot 模型页：模型库与用途分配分别检查，保存后再测试回复 · 演示数据

提示词、运行数据和扩展

这些页面走的都是 NeoBot 自己的面板接口。碰到接口不兼容、服务还没就绪或者权限不够，先看页面上给出的原因，也可以点「打开上游 WebUI」进一步核对。

都不行的时候，按这个顺序查

1. 实例没启动：看安装任务和实例日志，查运行时、依赖和端口。
2. 实例在跑，面板读不到数据：先看 WebUI / Dashboard 是否就绪，再查凭据和版本。
3. 面板正常，QQ 里不回复：查协议 Bot 是否在线、OneBot 连接、模型分配、名单和触发条件。
4. 只有某个插件或模型出问题：用最简单的一条指令或问题复现，看那一次调用的日志，先查它自己的配置和上游服务。
5. 改了没生效：看看是不是还有没保存的草稿、是不是需要重启、是不是有别的窗口把配置又改回去了。

各个框架的字段和插件行为会随着上游版本变化，以当前页面的提示和框架自己的文档为准。

接着看：查看任务和日志 · OneBot 调试台 · 备份与恢复