安装应用端，让 Bot 做事

Bot 登录以后能收发消息，但收到消息要怎么回、该执行哪个指令，它自己是不知道的，这些要交给应用端。NapCat / SnowLuma 是协议端，Karin、NoneBot2、AstrBot 这些是应用端。两边都跑起来、并且连上了，Bot 才算真正能干活。

这一篇带你走一遍「装实例 → 配置 → 对接 → 测试」。各个框架具体怎么配，见 应用框架。

开始前

• 已经按 第一个 Bot 建好了 Bot，QQ 已登录。
• 想好应用端装在本机还是远端。装远端的话，要先 添加 SSH 主机。
• 第一次建议把 Bot 和应用端放在同一台机器上，连通了以后再考虑拆开。

1. 新建应用实例

1. 打开「组件」，选好主机，找到要装的框架卡片，点「新建实例」。在「应用端」列表里点「去组件页安装」也能进到这里。
2. 「安装位置」选「本机」或者已经添加的远端主机。从组件页进来的话，固定就是当前选中的主机。
3. 填「实例名」，比如 测试用 AstrBot，只是方便你自己区分。
4. 「监听端口」可以留空，Desktop 会自动分配一个不冲突的高位端口。要手动填的话，范围是 1–65535，同一台机器上不能重复。
5. 「安装目录」用自动生成的路径就行。自己选的话，每个实例用一个单独的目录，Linux 远端要写 / 开头的绝对路径。
6. 按框架提供的选项选版本、WebUI 账号或者渲染器。弹出上游的使用条款时，读完再继续。
7. 提交并开始安装，到「任务」里看下载、装依赖和部署的进度。

新建应用实例：先确定主机，再检查端口与安装目录 · 演示数据

装完以后，「应用端」列表里会多出一张实例卡片。如果卡片还显示未安装，说明只建了档案，点卡片上的「安装」就行。

同一个框架可以建好几个实例，它们的目录、依赖和配置互不影响。「随桌面端启动」是每个实例单独设置的，新建时默认关着。

2. 配置并启动

1. 点实例卡片，进入详情。
2. 填好必要的配置。插件类框架先看连接、主人或者权限；AI 类框架先配模型提供商、模型和密钥。详见 七种框架。
3. 保存，看一眼保存结果。提示不支持热加载的，要重启实例才会生效。
4. 启动实例，打开「日志」，确认没有端口被占用、缺依赖或者配置解析出错。
5. 带 WebUI 的框架，可以从卡片上直接打开，核对账号和服务状态。

应用端列表：卡片下方集中放置启停、对接、WebUI 和日志入口 · 演示数据

部分模型、会话、插件和统计页面，要等实例跑起来才读得到数据。如果提示 Dashboard 不可达，先看进程和日志；如果是旧版框架缺少接口，按提示升级，或者去上游的面板里操作。

3. 一键对接协议 Bot

1. 在实例卡片或详情里点「对接」。从 Bot 配置页进「对接应用端」，打开的也是同一个对话框。
2. 核对「协议 Bot」和「应用实例」，别把测试用的实例接到你正在用的账号上。
3. 等对接计划生成出来，看一下连接方向、地址和主机组合。
4. 确认应用。Desktop 会把两边的配置一起改好。已经绑定过的，界面上会写明要改绑到哪个 Bot。
5. 启动应用端和 Bot，有提示的话重启一次，让新连接生效。
6. 在应用端日志或者上游面板里确认适配器已经连上，再用测试账号发一条配置好的指令。AI 类框架按它的会话规则发一句话试试。

对接前核对 Bot、应用实例和连接计划 · 演示数据

两个进程都在跑还不能说明问题，要看到连接建立了，测试消息也得到了预期的回应，才算真的对接成功。

同一台机器上直接连，支持的跨机组合会自动走 SSH 隧道。Docker 部署的 Bot 暂时不支持一键对接，选项是灰的，需要手动配置的话看 OneBot 连接。

不再需要的时候，点卡片上的「解除对接」，两边的对接配置都会恢复原样。想换一个 Bot，用改绑，核对好计划再应用。

导入已有项目

导入是原地接管，项目不会被复制到别处，启动入口也不变。开始之前先备份一下项目，再把你原来用终端、脚本或者服务启动的那个实例停掉，不然两边会抢同一个端口。

1. 在「应用端」选「导入已有项目」。
2. 选好「框架」和「主机」。
3. 「项目目录」选框架项目的根目录，也就是项目配置文件所在的那一层，远端填绝对路径。
4. 点检查，看识别结果和警告。目录、主机或框架改过的话，要重新检查一次。
5. 核对识别出来的实例名和状态，确认导入。
6. 进入详情，检查配置、连接和日志，然后交给 Desktop 来启动。

检查没通过的话，先确认目录、权限和框架类型选对没有。别为了让检查通过，去新建一个空的配置文件，那样只会把「目录选错了」这个真正的问题藏起来。

表单、原始文件和保存冲突

常用的设置在表单里改就行。表单里没有的自定义字段，到详情的「原始文件」里找到对应的文件直接编辑，保存时保持原来的格式（JSON、YAML、TOML 或 dotenv）。

保存时提示冲突，一般是上游 WebUI、别的编辑器或者框架进程同时改了这个文件。先把自己的改动留着，重新读取一下，对比完差异再合并。Bot 侧的对接文件在原始文件页里是只读的，要改连接请回 Bot 配置或者对接入口。

更新、删除和释放接管

支持版本管理的实例，可以在详情里看版本、更新或重装。更新之前先 导出配置并备份程序数据，再把实例停掉。配置包里不含插件程序和数据库，这些要另外备份。

删除时看清楚确认框：

• Desktop 新建的实例用「删除实例」。连目录一起删不删，看「同时删除安装目录」有没有勾上。
• 导入的实例默认是「释放接管」：还原导入时的配置和 systemd 设置（如有），删掉 Desktop 里的记录，已绑定的 Bot 连接也会一起移除。
• 导入的实例如果勾了「同时删除安装目录」，原来的项目会被删掉，快照也没法再还原。

启动了但没有回复

按这个顺序查：安装任务是不是成功了，应用端日志里有没有报错，Bot 登录没有，两边的 OneBot 连上没有。模型鉴权失败、插件没启用、会话名单没放行这个群，表现出来都是「不回复」。每次只改一个地方，再用同一条消息测试，这样才知道到底是哪一处起了作用。

下一步：按框架配置 · 用调试台检查接口与事件